Install and configure the Oracle Cloud Command Line Interface
Tags: autonomous, database, cloud, tools
Published: 2020-06-23 19:00:03

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 <a href="https://www.oracle.com/cloud/free/" target="_blank" rel="noopener noreferrer">Always Free Services</a> 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 <a href="https://docs.cloud.oracle.com/en-us/iaas/Content/API/Concepts/cliconcepts.htm" target="_blank" rel="noopener noreferrer">Oracle Cloud Command Line Interface</a> (OCI-CLI) to access and control your Oracle Cloud resources.
<h3>CLI Overview</h3>
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.
<h3>Pre-requisits</h3>
<h5>Python 3.5+</h5>
The CLI is built with Python so make sure you have <a href="https://www.python.org/" target="_blank" rel="noopener noreferrer">Python version 3.5</a> or higher installed.
<h5>RSA Key Pair</h5>
You will need an <a href="https://docs.cloud.oracle.com/en-us/iaas/Content/API/Concepts/apisigningkey.htm" target="_blank" rel="noopener noreferrer">RSA key attached to your cloud user</a> 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 <a href="https://www.openssl.org/" target="_blank" rel="noopener noreferrer">openssl</a>.  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.
<pre class="lang:default decode:true">openssl genrsa -out myPrivateKey.pem 2048
openssl rsa -pubout -in myPrivateKey.pem -out myPublicKey.pem</pre>
The first command creates a <strong>PRIVATE KEY</strong> 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.<br><br>
 
The second command uses your private key to create a <strong>PUBLIC KEY</strong> 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.<br><br>

<u>Store these keys in a secure location.</u>  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.
<h5>Cloud Account</h5>
You need to have access to an Oracle Cloud account with a user that is <a href="https://docs.cloud.oracle.com/en-us/iaas/Content/API/Concepts/cliconcepts.htm#Requirements" target="_blank" rel="noopener noreferrer">authorized to preform the tasks you intend to automate</a>.  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.
<ol>
 	<li>Tenancy
<ol>
 	<li>In the menu, under Administration, click Tenancy Details.</li>
 	<li>Locate the OCID and click Copy.
<img class="alignnone wp-image-1735" src="https://learncodeshare.net/wp-content/uploads/2020/03/tenancyOcid.png" alt="" width="677" height="489" /></li>
 	<li>Save this value for later.</li>
</ol>
</li>
 	<li> User
<ol>
 	<li>In the menu under Identity click Users.</li>
 	<li>Select your user.</li>
 	<li>Near the bottom click 'API Keys' under the resource menu.</li>
 	<li>Click the 'Add Public Key' button.</li>
 	<li>Choose the PUBLIC key file you generated earlier.</li>
 	<li>Click the 'Add' button.</li>
 	<li>Your key should now show up in the 'API Keys' list.
<img class="alignnone wp-image-1736" src="https://learncodeshare.net/wp-content/uploads/2020/03/userMenu.png" alt="" width="848" height="503" /></li>
 	<li>Copy the fingerprint of your key and save it for later.</li>
 	<li>Near the top of the user page, locate the OCID and click Copy.  Save this value for later.
<img class="alignnone size-full wp-image-1737" src="https://learncodeshare.net/wp-content/uploads/2020/03/userOcid.png" alt="" width="417" height="181" /></li>
</ol>
</li>
</ol>
<h3>Quickstart Install</h3>
You can <a href="https://docs.cloud.oracle.com/en-us/iaas/Content/API/SDKDocs/cliinstall.htm" target="_blank" rel="noopener noreferrer">download an execute a script</a> that will ask you typical installation configuration questions, after which it will install and configure the OCI-CLI.<br><br>

The following is current as of the publish date for this post, but you may want to review the instructions in case things change.
<h5>Linux / Mac</h5>
Open a terminal and run the following command.
<pre class="lang:sh decode:true ">bash -c "$(curl -L https://raw.githubusercontent.com/oracle/oci-cli/master/scripts/install/install.sh)"</pre>
<h5>Windows</h5>
Open PowerShell as Administrator.
<pre class="lang:default decode:true ">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'))"</pre>
In either system, answer the questions to complete the install.
<h3>Install with Python</h3>
If you don't have the rights on your computer or you'd rather not execute the above scripts, you can <a href="https://docs.cloud.oracle.com/en-us/iaas/Content/API/SDKDocs/climanualinst.htm" target="_blank" rel="noopener noreferrer">install the OCI-CLI with Python</a>.<br><br>

I recommend using a virtual environment when working with python.  It helps keep all of your projects clean and isolated.
<pre class="lang:sh decode:true">python3 -m venv oci-cli-env

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

# Windows
oci-cli-env\Scripts\activate.bat</pre>
Once your virtual environment is active, install the OCI-CLI with pip.
<pre class="lang:default decode:true ">pip install oci-cli</pre>
You can see if the install was successful by checking the version.
<pre class="lang:default decode:true">oci -v
</pre>
<pre class="lang:sh decode:true">2.9.5</pre>
<h3>Configure the OCI-CLI</h3>
Using the values you saved from above, you can <a href="https://docs.cloud.oracle.com/en-us/iaas/Content/API/Concepts/sdkconfig.htm" target="_blank" rel="noopener noreferrer">create a config file</a> with this command.
<pre class="lang:sh decode:true ">oci setup config</pre>
You will be prompted for the following information.
<pre class="lang:sh decode:true">Enter a location for your config [/home/bcarter/.oci/config]:
Enter a user OCID: &lt;User OCID from above&gt;
Enter a tenancy OCID: &lt;Tenancy OCID from above&gt;
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: &lt;saved value&gt;</pre>
<ul>
 	<li>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.</li>
 	<li>Enter the user and tenancy OCIDs saved from your account.</li>
 	<li>Enter the region you want to work in.  The system will display some examples you can choose from.</li>
 	<li>You already generated an RSA key pair so enter 'n'.</li>
 	<li>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.</li>
 	<li>Enter the Fingerprint you saved when you uploaded your PUBLIC key.</li>
</ul>
Once it's complete, you should see a response similar to this.
<pre class="lang:sh decode:true ">Config written to /home/bcarter/.oci/config</pre>
Your OCI-CLI should now be configured.  If you open the config file it should look similar to this.
<pre class="lang:default decode:true">[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</pre>
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.
<pre class="lang:default decode:true ">[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</pre>
<h5>Quick Test</h5>
Enter the following command.
<pre class="lang:default decode:true ">oci iam availability-domain list</pre>
If everything is working, you should receive a response similar to this.
<pre class="lang:default decode:true ">{
  "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"
    }
  ]
}</pre>
Now that your OCI-CLI is installed and configured, you should familiarize yourself with the <a href="https://docs.cloud.oracle.com/en-us/iaas/tools/oci-cli/latest/oci_cli_docs/" target="_blank" rel="noopener noreferrer">OCI-CLI documentation</a> 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.