Oracle Cloud Infrastructure Documentation

Working with the OCI CLI Container Image

This section covers how to install and use the OCI CLI Container Image.

The Oracle Cloud Infrastructure (OCI) Command Line Interface (CLI) Container Image is a Docker image that has the OCI CLI tools pre-installed. This section covers how to install and use the OCI CLI Container Image.

Requirements

To use the OCI CLI container image, you must have:

  • A standards-compliant container runtime engine, such as Docker, or Podman
  • An Oracle Cloud Infrastructure tenancy
  • A user account in that tenancy that belongs to a group to which appropriate policies have been assigned to grant the required permissions.
  • A keypair used for signing API requests, with the public key uploaded to Oracle. Only the user calling the API should possess the private key. For more information, see Configuring the CLI.

For examples of how to set up a new user, group, compartment, and policy, see the Adding Users. For a list of other typical OCI policies, review the list of common policies.

Using the OCI CLI container image

To use the container image, pull the latest version from the GitHub Container Registry:
$ docker pull ghcr.io/oracle/oci-cli:latest
$ docker images
REPOSITORY                              TAG               IMAGE ID       CREATED        SIZE
ghcr.io/oracle/oci-cli                  latest            387639e80a9a   3 days ago     711MB
Consider tagging the image as oci to make it a more seamless drop-in replacement:
$ docker tag ghcr.io/oracle/oci-cli:latest oci
$ docker images oci
REPOSITORY   TAG       IMAGE ID       CREATED      SIZE
oci          latest    387639e80a9a   3 days ago   711MB
                   
$ docker run -v "$HOME/.oci:/oracle/.oci" oci os ns get
{
    "data": "demo-tenancy"
}
For added convenience, you can create an shell alias that runs the container for you:
$ alias oci='docker run --rm -it -v "$HOME/.oci:/oracle/.oci" oci'
$ oci os ns get
{
    "data": "demo-tenancy"
}

API Signing Key Authentication

This is the default authentication method used by all OCI SDKs and the OCI CLI. To use this method, mount a location on the host system to the /oracle/.oci directory inside the container.

If you have previously configured the OCI CLI on the host machine, the easiest way to provide access to your API signing key is to map your $HOME/.oci directory to /oracle/.oci/ inside the container.

For example:
$ docker run --rm -it -v "$HOME/.oci:/oracle/.oci" ghcr.io/oracle/oci-cli os ns get
{
    "data": "example"
}

You can also pass the OCI_CLI_CONFIG_FILE environment variable to use a different location for the OCI CLI config file.

Note

Ensure that the key_file field in $HOME/.oci/config uses the ~ character so that the path resolves both inside and outside the container; for example: key_file=~/.oci/oci_api_key.pem.
If you have not configured the OCI CLI, create the $HOME/.oci directory:
mkdir $HOME/.oci
Next, start the OCI CLI interactive setup process:
docker run --rm -it -v "$HOME/.oci:/oracle/.oci" ghcr.io/oracle/oci-cli setup config

For more information, see Setting Up the Configuration File.

Session token authentication

To use token-based authentication, map port 8181 to the container:
docker run --rm -it \
   -v "$HOME/.oci:/oracle/.oci" \
   -p 8181:8181 \
   ghcr.io/oracle/oci-cli session authenticate

For more information, see Token-based Authentication for the CLI.

Instance principal authentication

To enable instance prinicipal authentication, you can use the --auth instance_principal command-line parameter:
docker run --rm -it ghcr.io/oracle/oci-cli --auth instance_principal os ns get
You can also pass the OCI_CLI_AUTH environment variable:
docker run --rm -it -e OCI_CLI_AUTH=instance_principal ghcr.io/oracle/oci-cli os ns get

If you created a shell alias, add it to the alias definition.

For more information, see OCI SDK Authentication Methods.

Local file access

The simplest way to allow the OCI CLI running inside the container to access files on the host is to bind mount a directory from the host into the container.

In the following example, the $HOME/scratch directory is bind mounted as /oracle/scratch in the container so that the files inside that directory can be bulk uploaded to OCI Object Storage using the OCI CLI:
docker run --rm -it \
    -v "$HOME/.oci:/oracle/.oci" \
    -v "$HOME/scratch:/oracle/scratch" \
    ghcr.io/oracle/oci-cli os object bulk-upload -ns <namespace> -bn <bucket name> --src-dir /oracle/scratch/