Cloud Shell

Oracle Cloud Infrastructure (OCI) Cloud Shell is a web browser-based terminal accessible from the Oracle Cloud Console.

Oracle Cloud Infrastructure (OCI) Cloud Shell is a web browser-based terminal accessible from the Oracle Cloud Console. Cloud Shell is free to use (within monthly tenancy limits), and provides access to a Linux shell, with a pre-authenticated Oracle Cloud Infrastructure CLI, a pre-authenticated Ansible installation, and other useful tools for following Oracle Cloud Infrastructure service tutorials and labs. Cloud Shell is a feature available to all OCI users, accessible from the Console. Your Cloud Shell will appear in the Oracle Cloud Console as a persistent frame of the Console, and will stay active as you navigate to different pages of the Console.

Cloud Shell provides:

  • An ephemeral machine to use as a host for a Linux shell, pre-configured with the latest version of the OCI Command Line Interface (CLI) and a number of useful tools

  • 5GB of storage for your home directory

  • A persistent frame of the Console which stays active as you navigate to different pages of the console

How Cloud Shell Works

The Cloud Shell machine is a small virtual machine running a Bash shell which you access through the OCI Console. Cloud Shell comes with a pre-authenticated OCI CLI, set to the Console tenancy home page region, as well as up-to-date tools and utilities.

Cloud Shell comes with 5GB of persistent storage for the home directory, so you can make local changes to your home directory, and then continue working on your project when you come back to Cloud Shell.

Cloud Shell is free to use (within your tenancy's monthly limits) and doesn't require any setup or prerequisites other than an IAM policy granting access to Cloud Shell. Your Cloud Shell includes a VM provisioned for you that executes in its own tenancy (so it doesn't use any of your tenancy's resources) and hosts your shell in an Oracle Linux OS while you're actively using Cloud Shell.

What's Included With Cloud Shell

In addition to the OCI CLI, the Cloud Shell VM comes with current versions of many useful tools and utilities pre-installed, including:

  • Git
  • Java
  • Python
  • Oracle GraalVM JDK 17 and Native Image
  • Most OCI SDKs, including:
    • Java
    • Python
    • Go
    • TypeScript and JavaScript
  • SQLcl
  • kubectl
  • helm
  • maven
  • terraform
  • ansible
  • node.js
  • iputils
  • jqmake
  • tmux
  • vim
  • NPM
  • wget
  • zip/unzip
  • nano
  • emacs
  • pip
  • bash
  • sh
  • tar
  • nvm
  • mysql-community-client
  • mysqlsh
  • Docker engine
  • ipython
  • oci-powershell-modules (x86_64 only)
  • GoldenGate Admin client (x86_64 only)

Required IAM Policy

To get started with Cloud Shell, you'll need to grant user access to Cloud Shell via an IAM policy. Each service in Oracle Cloud Infrastructure integrates with IAM for authentication and authorization, for all interfaces (the Console, SDK or CLI, and REST API).

To use Oracle Cloud Infrastructure, you must be given the required type of access in a policy written by an administrator in the tenancy's root compartment, whether you're using the Console or the REST API with an SDK, CLI, or other tool. If you try to perform an action and get a message that you don't have permission or are unauthorized, confirm with your administrator that you have been granted access.

Note

Cloud Shell does not support policies at the compartment level, only at the tenancy level.
The resource name for Cloud Shell is `cloud-shell`. The following is an example policy to grant access to Cloud Shell:
allow group <GROUP-NAME> to use cloud-shell in tenancy
This example policy shows how to allow a group within a domain to use Cloud Shell:
allow group <DOMAIN-NAME>/<GROUP-NAME> to use cloud-shell in tenancy

If you're new to policies, see Getting Started with Policies and Common Policies and Creating a Policy and Dynamic Group.

Cloud Shell Limitations

Keep the following limitations in mind when using Cloud Shell:

  • Cloud Shell comes with 5GB of storage for the VM's home directory. This storage is persistent from session to session, but after 6-months of non-use, the administrator for your tenancy will receive a notification that the storage will be removed in 60 days. Starting a cloud shell session resets the storage removal timer.
  • Cloud Shell does not support mounting additional storage.
  • Cloud Shell does not scan user files for malware or viruses.
  • Cloud Shell sessions do not allow for any incoming connections, and there is no public IP address available.
  • The OCI CLI will execute commands against the region selected in the Console's Region selection menu when the Cloud Shell was started. Changing the region selection in the console will not change the region for existing Cloud Shell instances; you will need to open a new Cloud Shell instance to change regions.
  • Cloud Shell sessions have a maximum length of 24 hours, and time out after 60 minutes of inactivity.
  • Cloud Shell uses websockets to communicate between your browser and the service. If your browser has websockets disabled or uses a corporate proxy that has websockets disabled you will see an error message ("An unexpected error occurred") when attempting to start Cloud Shell from the console.

  • Cloud Shell is designed for interactive use with Oracle Cloud Infrastructure resources. Users who need additional storage for Cloud Shell or want to run non-interactive long-running tasks are encouraged to use Compute and Storage resources in their tenancy.
  • For maximum compatibility, Cloud Shell includes Python version 2 and Python version 3. Python 2 is the default that will run when you enter 'python' at the command line. To run Python 3, enter 'python3' at the command line.
  • The following reserved words can't be used as the user name for a Cloud Shell user: oci, root, bin, daemon, adm, lp, sync, shutdown, halt, mai, operator, games, ftp, nobody, oci, systemd-network, dbus, polkitd, tss, and apache. Attempting to create a Cloud Shell session when logged in with a user name (or the part of the name before the @ sign if the user name is an email address) that is one of these reserved words will result in an "Unexpected Error" message.
  • Entirely numerical user names (for example, "1234") are not supported by Cloud Shell.
  • The Cloud Shell session time zone is UTC, and cannot be changed.
  • Cloud Shell does not allow root access or the use of sudo, so packages that require root access for installation can't be installed. Many packages are available in versions that do not require root for installation; you can unpack and install these in your home directory.
  • Cloud Shell does not allow the use of ping, since ping requires root access.
  • Cloud Shell boots in FIPS mode, which might affect the behavior of some commands.
  • Cloud Shell cannot generate PKCS#1 keys when using the openssl command, because Cloud Shell boots in FIPS mode. FIPS mode requires that Cloud Shell generates PKCS#8 keys.
  • For more information on Cloud Shell limits, see the Cloud Shell section in Service Limits.

Cloud Shell Access and Other Restrictions

You can access OCI resources from Cloud Shell according to the policies granted by your tenancy administrator. There is no additional access because you're using Cloud Shell, and Cloud Shell does not provide any additional access to your tenancy, or private resources in your tenancy VCNs.
Note

Cloud Shell uses websockets to communicate between your browser and the service. If your browser has websockets disabled or uses a corporate proxy that has websockets disabled you will see an error message ("An unexpected error occurred") when attempting to start Cloud Shell from the console.

While Cloud Shell provides access to the internet, there is no ingress from the outside world into Cloud Shell (for example: you cannot ssh in to Cloud Shell) and no public IP address available. If your tenancy admin does not want to enable access to the internet from OCI, they should not grant access to Cloud Shell with an IAM policy.

Cloud Shell Resource Location and Ownership

When you first start Cloud Shell, the service creates a persistent block storage volume (5GB) for your home directory. The home directory volume is located in your tenancy home region. The machine running your Cloud Shell session is also located in your tenancy home region.

Note

Cloud Shell uses your user OCID to create your home directory. If you have multiple accounts in a tenancy (for example, you have a federated and a non-federated user account), you will get a separate, unique Cloud Shell home directory for each account.

Changing the Console region selection, or logging in to the Console via a different regional URL will have no effect on where your Cloud Shell machine and home directory volume are located. To confirm your tenancy home region, view your Tenancy Details page in the Console.

Note

Cloud Shell resources (including the VM used for your Cloud Shell session) are owned by the Cloud Shell service and do not exist in your tenancy. Because of this, you cannot add the Cloud Shell VM you are using to a dynamic group in your tenancy, or use the instance principle of the instance used for your Cloud Shell session.

Cloud Shell and Regions

When you start Cloud Shell, the service configures your Cloud Shell session with the currently selected region in the Console so that the OCI CLI is interacting with the selected Console region.

In the default bash prompt in Cloud Shell, the region that the OCI CLI is interacting with is echoed in the Cloud Shell command line prompt:

Cloud Shell prompt with region information

Any changes to the selected region in Console after you've started your Cloud Shell session will not have an effect on your active Cloud Shell session.If you want to change the region that the OCI CLI is interacting with, in Cloud Shell, you can either:

  • Exit your current Cloud Shell session, then change the selected region in the Console, then start a new Cloud Shell session.
  • Modify the currently selected OCI CLI profile via the OCI_CLI_PROFILE environment variable

For more information, see the "Managing Regions" section in Using Cloud Shell.

Cloud Shell Architecture

If you are a paid tier user, you can choose a default architecture (ARM (aarch64), x86_64 or No Preference) for your Cloud Shell sessions.

By default, the architecture preference is set to No Preference. When this is selected, your Cloud Shell sessions will be based on either the x86_64 or ARM (aarch64) architecture, depending on the hardware available in the region.

Selecting an architecture

To select an architecture:

Open the Actions menu, which is accessible from within Cloud Shell or Code Editor, and choose Architecture.

Cloud Shell architecture action menu

This will display the Architecure dialog:

Cloud Shell Architecture dialog

The Architecture dialog shows the currently selected architecture.

To select your preferred architecture, select the appropriate radio button and then click the Confirm and Restart button.
Note

If a region does not support a particular architecture, you will not be able to choose that architecture.
Cloud Shell switch architecture dialog
Note

Before switching your Cloud Shell architecture, ensure that your tools and workloads are compatible with the architecture you are about to choose.

After a successful architecture migration, you will see this notification:

Cloud Shell architecture selection success message

Cloud Shell Private Networking

Cloud Shell Private Networking allows you to connect a Cloud Shell session to a private network so you can access resources in your private network without having the network traffic flow over public networks. Examples of where Private Networking can be useful include using it to SSH into compute instances inside of a private network or managing a private OKE cluster.

Note

A Cloud Shell instance is a private instance, and works like a private instance for the purposes of network setup. Using only an internet gateway will not allow egress to the internet from a private subnet. Using a service gateway or a NAT gateway will. For more information, see the Internet Gateway documentation.

Requirements and IAM Policy

To use Private Networking, you (or an administrator) will need to specify the following policies:

  • allow group <group> to use subnets in compartment <compartment>
  • allow group <group> to use vnics in compartment <compartment>
  • allow group <group> to use network-security-groups in compartment <compartment>
  • allow group <group> to inspect vcns in compartment <compartment>

If you're new to policies, see Getting Started with Policies and Common Policies.

You'll also need to create private VCNs and Subnets in the appropriate compartments. For more information, see VCNs and Subnets in the Networking documentation.

Cloud Shell Private Networking Limitations

When using Private Networking, keep the following limitations in mind:
  • You'll need to create private VCNs and Subnets in the appropriate compartments. For more information, see VCN and Subnet Management in the Networking documentation.
  • You can have up to 5 favorite private networks assigned.
  • A temporary ephemeral network is only valid for the length of your Cloud Shell session, and will not be persisted to your list of defined private networks.
  • Only VCNs and Subnets in your home region are available for creating a Private Network. If you need to access a subnet in a region that is not your home region, you can use peering from the subnet used by Private Networking to reach it. For more information, see VCN Cross-Region Peering.
  • A subnet chosen for a Cloudshell Private Network must have at least one non-reserved IP address for the subnet's CIDR block available. If all non-reserved IP addresses have been allocated, Cloudshell cannot attach to that subnet.
  • A subnet can only have a maximum of 5 associated network security groups.
  • Resolving endpoints through custom DNS resolvers is not supported.

Using Cloud Shell Private Networking

This section covers how to use Cloud Shell Private Networking.

Selecting a Network

To change which network your Cloud Shell session is using, use the drop-down Network menu at the top of the Cloud Shell terminal window:Cloud Shell Network menu location

The network selection menu appears:

Private network setup menu item.

From this menu you can select a network connection, access the list of private network definitions, or create an ephemeral (temporary) private network.

Using the Private Network Definition List

The Private Network Definition List item on the network selection menu displays the Private Network Definition List panel: Cloud Shell Private Network definition list

This panel allows you to create or modify private networks, designate favorite private networks, and select a default network.

Designating favorite networks

You can designate up to 5 favorite networks. To designate a network network as a favorite, click the star in the Favorite column.

Selecting a default network

You can select a default network from the drop-down list in the Default network panel. This is the network that is used when a new Cloud Shell session starts.

Creating a new private network definition

You can create a new private network definition by clicking the Create private network definition button. This will bring up the Create Private Network Definition panel.
Note

To create a temporary ephemeral network, select Ephemeral Private Network Setup from the network selection drop-down. This is temporary network is only valid for the length of your Cloud Shell session, and will not be persisted to your list of defined private networks.

Enter a name for your private network definition in the Name text box.

Select the VCN and the Subnet to use from the drop-down list boxes. You can also optionally select one or more Network Security groups to use.
Note

Only VCNs and Subnets in your home region are available. If you need to access a subnet in a region that is not your home region, you can use peering from the subnet used by Private Networking to reach it. For more information, see VCN Cross-Region Peering.
Note

A subnet chosen for a Cloudshell Private Network must have at least one non-reserved IP address for the subnet's CIDR block available. If all non-reserved IP addresses have been allocated, Cloudshell cannot attach to that subnet.

For example:

Example completed Cloud Shell private network setup dialog

If you want to set this definition as the active network, enable the Use as active network checkbox.

Click the Create button to create your Cloud Shell private network definition.

If you selected the Use as active network checkbox, your Cloud Shell session will be connected to your private network, as indicated in the Network drop-down at the top of the Cloud Shell terminal session:

Cloud Shell networking drop-down

You can see details about your private network connection by clicking the Details link:

Cloud Shell private network details view