Wednesday 1 December 2021

OAC - Using CLI to Automate Starting-Stopping of Instances

A couple of years ago I blogged on how to start and stop Oracle Analytics instances using the REST API. This enabled you to schedule scripts to manage the uptime of your instances so you can save those valuable oracle credits. This worked well for the old Autonomous instances but those scripts no longer work with the newer Gen2 OAC architecture. In this blog I’ll show how to use the Oracle CLI (Command Line Interface) to control your instances. 

The Oracle CLI is very simple to use, requires no coding skills and has the added bonus of being able to manage most of your Oracle Cloud Infrastructure tasks (e.g. managing DBaaS instances or virtual machines etc).

Pre-Requisites

You will require an IAM user account (non-IDCS) in your Oracle tenancy to run the CLI commands. You will need the OCID value for this user:


You also need the OCID value of your Oracle tenancy:


Installing the Oracle CLI on Windows


You can install on either Linux or Windows. I've chosen Windows as it's what most of our customers use. 

I followed the Oracle documentation on how to install CLI on Windows here: https://docs.oracle.com/en-us/iaas/Content/API/SDKDocs/cliinstall.htm 

Here is the process in a nutshell:
  • Download a powershell script
  • Run the powershell script. 
    • This will download the Python and install it.
    • It will also download the CLI and install it.

Initially, I installed Python manually but the auto-installer kept failing on the import ssl statement. I ended up deinstalling Python and getting the installation utility to install python for me.
This version of python is older (3.6) than the one I installed (failed with both 3.9 and 3.8).

Here are the commands you need to run:

Start Powershell as an administrator.

Set-ExecutionPolicy RemoteSigned 
(allow the script to run).

[Net.ServicePointManager]::SecurityProtocol = "tls12, tls11, tls" 
(enable tls otherwise it won’t be able to download the install files).

Invoke-WebRequest https://raw.githubusercontent.com/oracle/oci-cli/master/scripts/install/install.ps1 -OutFile install.ps1
(download the script).


iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/oracle/oci-cli/master/scripts/install/install.ps1'))
(run the installer with prompts)


Here is the rest of  the input/output:

===> In what directory would you like to place the install? (leave blank to use 'C:\Users\Administrator\lib\oracle-cli')
: E:\oracle-cli
-- Creating directory 'E:\oracle-cli'.
-- We will install at 'E:\oracle-cli'.

===> In what directory would you like to place the 'oci.exe' executable? (leave blank to use 'C:\Users\Administrator\bin
'): E:\oracle-cli\bin
-- Creating directory 'E:\oracle-cli\bin'.
-- The executable will be in 'E:\oracle-cli\bin'.

===> In what directory would you like to place the OCI scripts? (leave blank to use 'C:\Users\Administrator\bin\oci-cli-
scripts'): E:\oracle-cli\scripts
-- Creating directory 'E:\oracle-cli\scripts'.
-- The scripts will be in 'E:\oracle-cli\scripts'.

===> Currently supported optional packages are: ['db (will install cx_Oracle)']
What optional CLI packages would you like to be installed (comma separated names; press enter if you don't need any opti
onal packages)?:
-- The optional packages installed will be ''.
-- Trying to use python3 venv.
-- Executing: ['C:\\Users\\Administrator\\Python\\python.exe', '-m', 'venv', 'E:\\oracle-cli']
-- Executing: ['E:\\oracle-cli\\Scripts\\python.exe', '-m', 'pip', 'install', '--upgrade', 'pip']
Collecting pip
  Downloading https://files.pythonhosted.org/packages/47/ca/f0d790b6e18b3a6f3bd5e80c2ee4edbb5807286c21cdd0862ca933f751dd
/pip-21.1.3-py3-none-any.whl (1.5MB)


There was an error at the end but it seemed to install successfully:


Test the oci.exe by running the oci –version command:



OCI CLI Setup

Run the oci setup config command to configure the OCI CLI. This will prompt you to input your User and Tenancy OCID values. It will also prompt whether you want to create the API RSA key pair which I will do in this example:



Here is the rest of the input/output:

Enter a user OCID:
Enter a user OCID: ocid1.user.oc1..xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Enter a tenancy OCID: ocid1.tenancy.oc1..xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Enter a region by index or name(e.g.
1: ap-chiyoda-1, 2: ap-chuncheon-1, 3: ap-hyderabad-1, 4: ap-melbourne-1, 5: ap-
mumbai-1,
6: ap-osaka-1, 7: ap-seoul-1, 8: ap-sydney-1, 9: ap-tokyo-1, 10: ca-montreal-1,
11: ca-toronto-1, 12: eu-amsterdam-1, 13: eu-frankfurt-1, 14: eu-zurich-1, 15: m
e-dubai-1,
16: me-jeddah-1, 17: sa-santiago-1, 18: sa-saopaulo-1, 19: sa-vinhedo-1, 20: uk-
cardiff-1,
21: uk-gov-cardiff-1, 22: uk-gov-london-1, 23: uk-london-1, 24: us-ashburn-1, 25
: us-gov-ashburn-1,
26: us-gov-chicago-1, 27: us-gov-phoenix-1, 28: us-langley-1, 29: us-luke-1, 30:
 us-phoenix-1,
31: us-sanjose-1): 23
Do you want to generate a new API Signing RSA key pair? (If you decline you will
 be asked to supply the path to an existing key.) [Y/n]: Y
Enter a directory for your keys to be created [C:\Users\Administrator\.oci]: E:\oracle-cli\keys
Enter a name for your key [oci_api_key]: oci_api_key
Public key written to: E:\oracle-cli\keys\oci_api_key_public.pem
Enter a passphrase for your private key (empty for no passphrase):
Private key written to: E:\oracle-cli\keys\oci_api_key.pem
Fingerprint: xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx
Config written to c:\oracle-cli\bin

    If you haven't already uploaded your API Signing public key through the
    console, follow the instructions on the page linked below in the section
    'How to upload the public key':

        https://docs.cloud.oracle.com/Content/API/Concepts/apisigningkey.htm#How
2


The keys were generated here:




Note that I got the config location wrong when I ran this first time (C:\oracle-cli\bin instead of E:). I'm not sure if the CLI doesn't let you use another folder than the default one but I had to create the config file in C:\Users\Administrator\.oci\config.

I just copied the contents of the file which got created by the config command earlier and created a new file called config in C:\Users\Administrator\.oci\config. I had to use the cmd mkdir command to create the folder because it starts with a full-stop.

Add the Keys to your IAM User Account

Next we need to associate the public key we created earlier with our IAM user account.

Open the oci_api_key_public.pem file and copy the entire contents (including the -----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY-----).

Login to OCI and go to your IAM user account.

In the bottom left of the screen click on API Keys and then Add API Key:



Copy the contents of the public key and paste into the box:



You should then see the fingerprint and the contents which should match the config file you have on the oracle-CLI install:



Stopping and Starting OAC using the CLI Command Line

Finally we get to the nitty gritty!

Once you have configured the Oracle CLI and you have imported the keys to your IAM user account you should be able to use CLI to manage your Oracle Analytics instances (and other OCI services).

To stop OAC using CLI you run this command: 
oci analytics analytics-instance stop --analytics-instance-id <OAC instance ID>


To start OAC you run this command:
oci analytics analytics-instance start --analytics-instance-id <OAC instance ID>



You can see the commands are successful in the OAC activity log:

You can also use the GET command to get the status of the instruction:

oci analytics analytics-instance get --analytics-instance-id <OAC instance ID>


Once it is complete the lifecycle-state changes:



All that remains is to save your script as a batch file and schedule it using the standard Windows scheduler.

Other Oracle CLI Commands

There are other useful commands such as scale which allows you to scale your instance up or down.

You can find all CLI commands in the OCI CLI Command Reference guide here:

No comments:

Post a Comment