REST APIs — to easily manage an Autonomous Database in Oracle Cloud

Oracle Cloud offers an easy to use tool that you can use to manage all cloud services via REST APIs without needing you to learn how to code or become an expert in other programming languages. If I managed to do it, trust me, you will too :)

First off, why would you need to use API calls when you can manage a autonomous database using the web console? Well, for most of Oracle customers, they want to be able to schedule the automatic start/stop of a database or data warehouse instance at specific times to reduce cost. And while such a functionality is not present in the web console yet, REST APIs are a great solution to get the job done.

There are many ways to use these APIs, one of them being Terraform. For this blog post I will show you how to use the oci-curl function made available by the OCI Infrastructure team. It’s an easy to use function that will sign and encrypt your APIs so they are not sent in clear over the Internet and make your life A LOT easier.

So to use this tool you will need a master Linux/Mac/Windows machine that will be running the scripts at your desired intervals to STOP/START or do many other interesting things with your cloud resources.

OCI-CURL can be used on Linux/Mac and Windows OS and also in C# Java NodeJS Perl PHP Python Ruby and Go.

I will be using the Bash version for Linux/Mac for this post.

So let’s get things started!

PART 1: Make a Curl script with account details

1. Copy the script from : https://docs.cloud.oracle.com/iaas/Content/Resources/Assets/signing_sample_bash.txt

And paste it in a new script file on your Linux, I will name my file oci-curl.sh and we need to change 4 lines in it with our own Oracle cloud account details:

1. a) TenancyID

You get the first parameter from your cloud account by clicking on the small icon at the top right and then on Tenancy : your_account :

This will take to your tenancy details and you can click on Copy OCID like here:

I’ll add this OCID to the oci-curl.sh line having the tenancyId :

1. b) AuthUserID

To get the user OCID the steps are almost the same as above, we go to the top left menu button and click on the burger button, then Identity and Users :

Then click on your username and copy the OCID:

Now add it to the oci-curl.sh file :

1. c) KeyFingerprint

This one will be a bit more tricky as we need to make a private/public key in PEM format and upload it your cloud account. This key is needed to encrypt and decrypt all future communication between you and the OCI instances. You can generate the key on any Linux/Mac using the built-in command line tools. On Windows tools like PuttyGen won’t work as it doesn’t support the PEM format, but you can use GIT Bash for Windows and run the below commands in it.

1.Generate the private key with no passphrase:
openssl genrsa -out oci_api_key.pem 2048
2.Change the ownership of the key so only you can use it:
chmod 700 oci_api_key.pem
3.Generate the public key from the private key :
openssl rsa -pubout -in oci_api_key.pem -out oci_api_key_public.pem

Now open and copy the public key contents (using vi or cat commands) and let’s add it to the OCI console. The place we put it is in the user account page we had earlier:

Click on Add Public Key and paste the public key contents inside:

Once imported we will get what we were searching for, the fingerprint of the key file:

Copy this fingerprint and add it to the oci-curl.sh file:

1. d) PrivateKeyPath

The last piece of the puzzle is to point the oci-curl.sh to the location of the private key oci_api_key.pem we made in step 1. c) :

To make a quick summary, thus far we created a function script called oci-curl.sh and we added inside it all the details of our cloud account. We are going to use this script to authenticate and sign all the jobs we want to run in the cloud.

Part 2: Create, START, STOP and SCALE an autonoumous database

Create a new ATP database

Let’s start by creating an ATP instance using the function from above, we do this by first creating a new file called createATP.sh (and don’t forget to make it executable afterwards with chmod +x createATP.sh) :

#!/bin/bash
. ./oci-curl.sh
oci-curl database.eu-frankfurt-1.oraclecloud.com POST ./requestATP.json "/20160918/autonomousDatabases"

To explain what this does:

• . ./oci-curl.sh: this will load and source the function with you tenant data
• database.eu-frankfurt-1.oraclecloud.com: the API that listens for database services from the Frankfurt datacenters. If your cloud database is located in Lodon or elsewhere you need to change it accordingly (full list here)
• POST : whether your request is a GET, DELETE, PUT or POST
• ./requestATP.json : this is configuration file containing information like number of name, OCPUs, password etc that we would need for the new service. We’ll create it below.
• /20160918/AutonomousDatabases: the first numbers are the version of the API you are using, for now all OCI APIs have this same version. The rest is the API to manage the ATP service.

Now we need to put the configuration details of the new ATP database in a new file, I’ll call it requestATP.json

{
"compartmentId" : "ocid1.compartment.oc1..aaaaaaaa24qo6imwxxxxxx",
  "dbName" : "orcl",
  "displayName" : "REST-ATP",
  "adminPassword" : "WelcomeTrials19",
  "cpuCoreCount" : 1,
  "dataStorageSizeInTBs" : 1,
  "licenseModel" : "LICENSE_INCLUDED"
}

So I’m creating a 1 OCPU with 1 TB ATP autonomous database and I specify that we don’t already own a license for it so we need to get a new license. All the rest of the script you can fill in as shown modifying it to your needs, including the compartment OCID. This piece of information is found on the cloud account under Identity and Compartments:

Click on your root compartment and there you’ll find the OCID — add it to the requestATP.json :

So let’s run ans spin up our first ATP database via REST :

And the result in the console is just magic :)

Stopping ATP

For us to Stop an autonomous database like ATP/ADW we need to make 2 new files, the first one is called stopATP.sh and you can paste this code in it:

#!/bin/bash
. ./oci-curl.sh
oci-curl database.eu-frankfurt-1.oraclecloud.com POST ./empty.json /20160918/autonomousDatabases/$1/actions/stop

See that we are changing a few things from before. First is the json file that is now pointing to a new empty.json . This is just an empty file for Start/Stop requests as we don’t change or pass configuration parameters to the cloud service (like number of OCPUs, storage, VCN etc that we needed earlier).It looks like this:

{
}

We are adding $1 as the argument placeholder for the ATP OCID. I’ll get back to this when we run the command.

And last is the actions/stop part that specifies what we want to do like STOP or START the service.

Don’t forget to make the empty.json file like above and to make the script executable:

chmod +x stopATP.sh

Now the last thing we need is the unique identifier of the ATP we want to stop, it’s OCID. You can get it from the cloud web console when you click on the menu button and then Autonomous Transaction Processing:

Now click on the name of the ATP machine and copy it’s OCID :

So let’s run the stopATP.sh script:

And the answer :

Starting ATP

Now to start the ATP database, we create a new file called startATP.sh and notice that I change the action to START and left everything the same.

#!/bin/bash
. ./oci-curl.sh
oci-curl database.eu-frankfurt-1.oraclecloud.com POST ./empty.json /20160918/autonomousDatabases/$1/actions/start

As always, remember to make this file executable with “chmod +x startATP.sh” and when you run it provide the OCID of the ATP instance.

Scale UP/DOWN ATP

The procedure for scaling is similar, we create a file called updateATP.sh :

#!/bin/bash
. ./oci-curl.sh
oci-curl database.eu-frankfurt-1.oraclecloud.com put ./scaleOCPU.json "/20160918/autonomousDatabases/$1"

Inside the scaleOCPU.sh we put a bigger/smaller number of OCPUs assigned to it, or the new storage size if we want:

And then we execute the script specifying the OCID of the ATP:

That it!

A full list of APIs that you can use to manage the Autonomous ATP and ADW can be found here: https://docs.cloud.oracle.com/iaas/api/#/en/database/20160918/AutonomousDatabase/

The last step that I won’t cover in this post is to add these two Start and Stop scripts to a CRON in Linux or a Task Scheduler in Windows so they run automatically at your desired points in time.

You can use everything you learned here to manage ALL the other services in Oracle Cloud, not just autonomous databases, with just a small amount of tweaking. All the information can be found here: https://docs.cloud.oracle.com/iaas/api/#/

I hope this helps and you found it useful.

Thank you,

Riadh