REST API to manage Database Cloud Service

Arguably agility is one of the primary advantage of Cloud. All major cloud platform offer a very neat UI to manage lifecycle of infrastructure such as Virtual Machine and Platform such as Database, Application server etc. UIs are good for one off tasks or projects where infrastructure or platform components are not rebuild from scratch with each iteration of code deployment. However, UIs are limited in functionalities when it comes to integrating Cloud with existing tool sets such as Enterprise service management (e.g. ServiceNow), Cloud Platform Management frameworks or with configuration management tool e.g. chef or puppet for automation. And this is where Web Services become such a critical piece of Cloud Technology. In fact, most of the UIs written for Cloud management makes call to the same set of Web Service APIs as available for end users/developers to embed in their own code.

Following on from my previous post on building database in Oracle Cloud using UI, this blog entry covers REST APIs provided by Oracle Database Cloud Services. Further, I have developed a python wrapper to highlight the usefulness and ease of use of these APIs, which I will discuss briefly at the end.

Oracle Database Cloud Service (DBCS) offers a rich set of REST APIs to carry out following tasks:

  1. Build, Modify (Scale up or Down) and Delete an instance.
  2. View status of instance and various jobs related to service management.
  3. Stop, start and restart a service instance.
  4. Patch management – apply, view and rollback.

Oracle documentation on DBCS REST API provides usage detail with example of JSON file and cURL command for each of these. List of end points for these actions can be found here.

Leveraging the REST API library, I have developed a python based command line tool for database management in Oracle Cloud. Documentation and code for this utility is available on github. The main script “”  offers  the following functionalities

  1. Build Oracle Database Cloud Service (Single Instance and RAC).
  2. View status of database service(s) in an identity domain.
  3. Scale UP and Scale DOWN resources allocated to a Database Cloud Service.
  4. Allocate more storage to Database Cloud Service.
  5. Manage Lifecycle (Stop, Start and Restart) Database Cloud Service.

Output of the execution is written to standard output (screen) as well as to a log file for auditing and review if necessary.

Usage of the main script is :

$./ -h
usage: [-h] [-i I] [-u U] [-o O] [-w W] [-l L] [-c C] [-d [D]]
                   [-n [N]] [-s [S]] [-j [J]]

optional arguments:
  -h, --help  show this help message and exit
  -i I        identity domain
  -u U        username
  -w W        web service ref file
  -l L        logfile (fullpath)
  -c C        certificate file (fullpath)
  -d [D]      json file for creating dbcs service
  -n [N]      dbcs service name
  -s [S]      compute shape
  -j [J]      job number

And an example to build database service instance is:

./ -i <identity domain name> \
              -u <cloud user name> \
              -o BUILD \
              -w <location of web services ref file> \
              -l <location of log file> \
              -c <location of cacert.pem file> \
              -d <location of service def json file>

./ -i gse00000379 \
              -u cloud.admin -o BUILD -w ../etc/opc-dbcs-ws.ref \
              -l ../log/opc_dbcs.log \
              -c /Users/bipul/keys/cacert.pem \
              -d ../etc/create_sidb.json

A sample JSON file for building a 12cR1 single instance database is below ( also a similar file available from git repository )

   "serviceName": "BKDB001",
   "version": "",
   "level": "PAAS",
   "edition": "EE_EP",
   "subscriptionType": "MONTHLY",
   "description": "DBCS Created via RESTful API",
   "shape": "oc3",
   "vmPublicKeyText": "YourPublicKey",
   "parameters": [
       "type": "db",
       "usableStorage": "25",
       "adminPassword": "YourDBPassword",
       "sid": "BKDB001",
       "pdb": "PDB1",
       "failoverDatabase": "no",
       "backupDestination": "NONE",
       "isRac": "no"

The code base makes use of Python module “request” for REST calls, processes response and polls the job status until completion. This script can be used as standalone or for integration with existing code base for database automation. The README file on git has more information and example call for other verbs such as scale up/down, delete instances etc.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s