Install and configure the Oracle Cloud Command Line Interface

I love working with cloud resources.  I don't have to bog down my laptop and I don't have to maintain all of the back-end stuff.  I don't mean to make it sound as if I think the "back-end stuff" is easy.  It's actually, I understand just enough of that "stuff" to make it go (most of the time) so it's nice to have experts in the cloud taking care of it for me.

Some of you may be thinking "but cloud resources are expensive."  That's true sometimes, but it depends on who's cloud you're using.  If you've been following me you should already know how much I like Oracle's Always Free Services and you should know that I love to automate anything I can.  If you'd like to follow along but you don't have an Oracle Cloud account, click that link, create an Always Free account then come back.

In this post I'll cover how to use the Oracle Cloud Command Line Interface (OCI-CLI) to access and control your Oracle Cloud resources.

CLI Overview

Oracle's cloud CLI is a small application you can use to control your Oracle Cloud resources.  It gives you the same core functionality as you'd get using the Web Console, and some extra commands.  It allows you to control your cloud account from your local console application so you can easily automate the control of your resources.

Pre-requisits

Python 3.5+

The CLI is built with Python so make sure you have Python version 3.5 or higher installed.

RSA Key Pair

You will need an RSA key attached to your cloud user in order to remotely access your account.  This must be an RSA key pair in PEM format (minimum 2048 bits).

The easiest way to generate this key par is with openssl.  The following commands work in Linux/Mac environments.  For Windows you can use your favorite tool or execute the commands in GitBash, WSL or some other Linux shell environment.

openssl genrsa -out myPrivateKey.pem 2048
openssl rsa -pubout -in myPrivateKey.pem -out myPublicKey.pem

The first command creates a PRIVATE KEY called 'myPrivateKey.pem' (name yours whatever you'd like).  This is the key you will use to access remote systems.  DO NOT share this key, whoever has this key can connect to those systems as you.  Think of it as your admin password.

The second command uses your private key to create a PUBLIC KEY called 'myPublicKey.pem' (name yours whatever you'd like).  This is the key you will share with remote systems.  Those systems will add your PUBLIC KEY to their authorized keys list, allowing you to access their system using your private key.

Store these keys in a secure location. On Linux, the default location is usually in the ~/.ssh directory.  But, if you're creating separate keys for your projects, you can store them wherever you'd like.  Just remember the location for later.

Cloud Account

You need to have access to an Oracle Cloud account with a user that is authorized to preform the tasks you intend to automate.  A good way to tell if your user has the correct permissions is to log onto your account through the Web Console and create an Always Free database then terminate it. While you're logged into the Web Console collect some information.

1. Tenancy
   1. In the menu, under Administration, click Tenancy Details.
   2. Locate the OCID and click Copy.
   3. Save this value for later.
2.  User
   1. In the menu under Identity click Users.
   2. Select your user.
   3. Near the bottom click 'API Keys' under the resource menu.
   4. Click the 'Add Public Key' button.
   5. Choose the PUBLIC key file you generated earlier.
   6. Click the 'Add' button.
   7. Your key should now show up in the 'API Keys' list.
   8. Copy the fingerprint of your key and save it for later.
   9. Near the top of the user page, locate the OCID and click Copy.  Save this value for later.

Quickstart Install

You can download an execute a script that will ask you typical installation configuration questions, after which it will install and configure the OCI-CLI.

The following is current as of the publish date for this post, but you may want to review the instructions in case things change.

Linux / Mac

Open a terminal and run the following command.

bash -c "$(curl -L https://raw.githubusercontent.com/oracle/oci-cli/master/scripts/install/install.sh)"

Windows

Open PowerShell as Administrator.

Set-ExecutionPolicy RemoteSigned

powershell -NoProfile -ExecutionPolicy Bypass -Command "iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/oracle/oci-cli/master/scripts/install/install.ps1'))"

In either system, answer the questions to complete the install.

Install with Python

If you don't have the rights on your computer or you'd rather not execute the above scripts, you can install the OCI-CLI with Python.

I recommend using a virtual environment when working with python.  It helps keep all of your projects clean and isolated.

python3 -m venv oci-cli-env

# Linux / Mac
source oci-cli-env/bin/activate

# Windows
oci-cli-env\Scripts\activate.bat

Once your virtual environment is active, install the OCI-CLI with pip.

pip install oci-cli

You can see if the install was successful by checking the version.

oci -v

2.9.5

Configure the OCI-CLI

Using the values you saved from above, you can create a config file with this command.

oci setup config

You will be prompted for the following information.

Enter a location for your config [/home/bcarter/.oci/config]:
Enter a user OCID: <User OCID from above>
Enter a tenancy OCID: <Tenancy OCID from above>
Enter a region (e.g. us-ashburn-1, us-phoenix-1): us-ashburn-1
Do you want to generate a new RSA key pair? [Y/n]: n
Enter the location of your private key file: /home/bcarter/.ssh/myPrivateKey.pem
Fingerprint: <saved value>

• The default location for the config file is typically '~/.oci/config'.  If you use a different location you will need to remember where it is.
• Enter the user and tenancy OCIDs saved from your account.
• Enter the region you want to work in.  The system will display some examples you can choose from.
• You already generated an RSA key pair so enter 'n'.
• Enter the location of your PRIVATE key.  This will not be uploaded, the CLI will use your PRIVATE key to make the connection to the cloud.
• Enter the Fingerprint you saved when you uploaded your PUBLIC key.

Once it's complete, you should see a response similar to this.

Config written to /home/bcarter/.oci/config

Your OCI-CLI should now be configured.  If you open the config file it should look similar to this.

[DEFAULT]
user=ocid1.user.oc1..aaaaaaaat5nvwcna5j6aqzjcaty5eqbb6qt2jvpkanghtgdaqedqw3rynjq
fingerprint=20:3b:97:13:55:1c:5b:0d:d3:37:d8:50:4e:c5:3a:34
key_file=~/.oci/oci_api_key.pem
tenancy=ocid1.tenancy.oc1..aaaaaaaaba3pv6wkcr4jqae5f15p2b2m2yt2j6rx32uzr5vqstifsfdsq
region=us-ashburn-1

You can add other connection profiles manually by following this format or you can use the same command to add a new profile.  If you re-run the command, it will ask you for a name to use for the new profile which will be added to the config file.

[DEFAULT]
user=ocid1.user.oc1..aaaaaaaat5nvwcna5j6aqzjcaty5eqbb6qt2jvpkanghtgdaqedqw3rynjq
fingerprint=20:3b:97:13:55:1c:5b:0d:d3:37:d8:50:4e:c5:3a:34
key_file=~/.oci/oci_api_key.pem
tenancy=ocid1.tenancy.oc1..aaaaaaaaba3pv6wkcr4jqae5f15p2b2m2yt2j6rx32uzr5vqstifsfdsq
region=us-ashburn-1

[ACCOUNT2]
user=ocid1.user.oc1..aaaaaaaa65vwl7zut55hiavppn4nbfwyccuecuch5tewwm32rgqvm6i34unq
fingerprint=72:00:22:7f:d3:8b:47:a4:58:05:b8:95:84:31:dd:0e
key_file=~/.ssh/other_key.pem
tenancy=ocid1.tenancy.oc1..aaaaaaaaba3pv6wkcr4jqae5f15p2b2m2yt2j6rx32uzr5vqstifsfdsq
region=us-ashburn-1

Quick Test

Enter the following command.

oci iam availability-domain list

If everything is working, you should receive a response similar to this.

{
  "data": [
    {
      "compartment-id": "ocid1.tenancy.oc1..biglongguid",
      "id": "ocid1.availabilitydomain.oc1..biglongguid",
      "name": "qVbG:US-ASHBURN-AD-1"
    },
    {
      "compartment-id": "ocid1.tenancy.oc1..biglongguid",
      "id": "ocid1.availabilitydomain.oc1..biglongguid",
      "name": "qVbG:US-ASHBURN-AD-2"
    }
  ]
}

Now that your OCI-CLI is installed and configured, you should familiarize yourself with the OCI-CLI documentation to learn about the many, many commands you can use to automate the control of your Oracle Cloud resources.

You can use these same commands from any system with the OCI-CLI installed, including Oracle Cloud Compute instances.