REST APIs — easily Start and Stop a Cloud 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 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 compute 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 in 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.

So let’s get things started!

PART 1: Curl script and 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: START and STOP a cloud database

For us to Stop a cloud database we need to make a new file called startDBaaS.sh and paste this code in it:

#!/bin/bash
. ./oci-curl.sh
oci-curl database.eu-frankfurt-1.oraclecloud.com POST ./empty.json /20160918/dbNodes/$1?action=start

startDBaaS.sh

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
• ./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 would need to do when creating a DB for example). In the latest OCI API versions, the file has to be completely empty for it to work so I recommend you just create the file without adding anything in it. But if you have an older Autonomous database or in case it doesn’t work with it empty, you can add two brackets in the empty.json file like here:

{
}

• /20160918/dbNodes/$1?action=start : the first numbers are the version of the API you are using, for now all OCI APIs have this same version. dbNodes is the API to manage the node (virtual machine) that runs the database. $1 is an argument with the dbNode OCID that we will give directly in the command later. And action can be start;stop;softreset;reset.

A full list of APIs that you can use to manage the Node is found here: https://docs.cloud.oracle.com/iaas/api/#/en/database/20160918/DbNode/

Now don’t forget to make the empty.json file like above. Also we need to make the script executable:

chmod +x startDBaaS.sh

Now the last thing we need is the unique identifier of the database node, it’s OCID. You can get it from the cloud web console when you click on the DB System details and then on the Nodes link:

Now finally time to run the STOP API:

And the answer :

Yeees, we finally made it :)

Now to start the node, we create a new file called startDBaaS.sh and we add this to it:

Notice that I change the action to START and left everything the same. Make it executable and run it the same way as above.

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 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