Command Line Interfaces (CLIs) in the Oracle Cloud

Introduction

Oracle offers the Cloud Console, which is an easy to use web-based interface to create and manage all Oracle cloud resources. However, in many use cases it is more efficient to do your tasks programmatically using command line tools instead of clicking on every button in the web browser manually:

1. Provision and terminate the same resource multiple times for testing purposes
2. Manage many resources at once, e.g. stop and start all virtual machines
3. Create reports including information about many resources at once
4. Take action automatically after a specific event
5. Schedule the execution time of your commands
6. Take advantage of some extended capabilities that are not available through the web console
7. And much more…

The CLIs are procedural tools. You have to define the execution order, take care of the dependencies (create the network first, get it’s OCID, then use this OCID to create a virtual machine in that network), and keep track of their status (get the information if the virtual machine is provisioned, if yes, do nothing, if not, then create it). Therefore, for creating and destroying complex architectures, Terraform is much more appropriate. Terraform is declarative. This means you describe your architecture once, and Terraform takes care of deploying all resources in the correct order considering the dependencies, only once, as it keeps track of their status.

For managing the resources, e.g. stopping, starting, scaling, backing up, restoring, patching, and upgrading, the CLIs are the tool of choice.

For all Cloud Resources

OCI CLI

The Oracle Cloud Infrastructure Command Line Interface, short OCI CLI, shorter CLI, is a small-footprint tool that makes calls to Oracle Cloud Infrastructure REST APIs using HTTPS requests. It is built with the SDK for Python.

Instead of OCI CLI, you could use the REST API, or the Python SDK. SDKs for Java, Ruby, and Go are also available.

The OCI CLI command line reference describes the available commands to use for every resource. For example:

oci network subnet list ...
oci compute instance launch ...
oci db autonomous-database stop ...

You get the response in JSON format, e.g., list all autonomous databases in a specific compartment:

oci db autonomous-database list <compartment-ocid>

{
  "data": [
    {
	  ...
      "cpu-core-count": 1,
      "data-safe-status": "NOT_REGISTERED",
      "data-storage-size-in-gbs": 1024,
      "data-storage-size-in-tbs": 1,
      "db-name": "ATP19C",
      "db-version": "19c",
      "db-workload": "OLTP",
      "id": "ocid1.autonomousdatabase.oc1.eu-frankfurt-1..........jlyxa",
      "infrastructure-type": null,
      "is-access-control-enabled": null,
      "is-auto-scaling-enabled": false,
      "is-data-guard-enabled": false,
	  ...
    }
  ]
}

When combined with Bash or PowerShell, OCI CLI provides powerful automation capabilities, like iterating through all resources and executing a specific action on them. For example, stop all autonomous databases in the test and development environments after working hours to save cost:

ALL_ADB_OCIDS=$(oci db autonomous-database list --compartment-id $C_ID | jq '.data[]."id"')
for ADB_OCID in $ALL_ADB_OCIDS
do 
   oci db autonomous-database stop --autonomous-database-id $ADB_OCID
done

At GitHub I provide OCI CLI scripts to stop compute VMs, autonomous databases, DBCS VM compute nodes, and OAC instances. Feel free to download and use them in your tenancy.

Installation and Configuration

OCI CLI can be installed and configured on a Mac, Windows, or Linux machine. This machine doesn’t have to be in the cloud, and it does not even need to have access to the resources (compute, databases, etc.) you are managing. It just needs HTTPS (TCP port 443) access to the Oracle Cloud Services network, e.g. via Internet, or via Service Gateway from within a VCN.

Cloud Shell

If you say “I don’t want to install and configure anything first, I just want to get started”. No problem! Use the Cloud Shell. The Cloud Shell is a web browser-based terminal accessible from the top right side of the web console. One click on this icon is everything you need:

It provides access to a Linux shell with a pre-authenticated OCI CLI. You have 5GB of storage for your home directory. However, it does not provide scheduling capabilities like crontab etc., but it is just perfect for a quick start:

For VM and BM DB Systems

dbcli

Database CLI, short dbcli, is a command line tool available on virtual machine and bare metal DB systems (not on Exadata DB systems). It is available locally on each DB system and must be run as the root user. It can only manage resources (databases, database homes) installed locally on that specific DB system, e.g.:

dbcli create-database ...

Now, this might raise a question in your mind: if some of the commands to do a specific task are available on both OCI CLI and dbcli, which tool should I use in this case? Answer: if the command is available on both tools, then the recommendation is to use the cloud tooling, which is OCI CLI.

If you are managing many db systems at once, let’s say patching tens of databases, then it is anyway easier to use the OCI CLI than to log-in into each DB system one by one to execute the local dbcli command.

dbcli provides further commands to look at the logs on the local system, or to create PDBs, which are not (yet) available via console or OCI CLI:

dbcli list-jobs
dbcli describe-job -i <job-id>
dbcli create-database ... -p <pdb>
dbcli update-tdekey -i <db_id> -p [-all] -n <pdb1,pdb2> ...

cliadm

CLI Admin Command, short cliadm, updates your dbcli tool to get the new commands that support new features added to the cloud services:

cliadm update-dbcli

For Exadata DB Systems

dbaasapi

Update 02.12.2022: dbaasapi is deprecated and replaced by dbaascli.

dbaasapi can be used to create and delete databases on Exadata DB systems. It requires a JSON input and produces a JSON output. dbaasapi must be run as the root user on the compute nodes.

If you want to create a multitenant container database with instances running across all Exadata compute nodes, then OCI CLI is the recommended tool to use. In case you want to create a non-CDB database or a database with instances running only on a subset of the compute nodes, you must use dbaasapi.

Non-CDB databases running on all nodes will be visible to the Cloud Tooling and can be managed via OCI CLI. However, databases running only on a subset of the nodes will not be visible in the OCI interfaces (Console, CLI, API), and hence, cannot be manged using these tools. Use dbaascli to manage these databases:

vi createdb.json

{
  "object": "db",
  "action": "start",
  "operation": "createdb",
  "params": {
    "nodelist": "node1",
    "dbname": "exadb",
    ...
  },
  "outputfile": "createdb.out"
}

/var/opt/oracle/dbaasapi/dbaasapi -i createdb.json

dbaascli

dbaascli is the command line tool for life-cycle and administration operations for Exadata databases. It must be run on the local Exadata compute node. Many dbaascli commands can be run as the oracle user. However, some commands require root administrator privileges.

Here again, you’ll find some commands that are also available via OCI CLI. dbaascli provides further commands, e.g. to download database software images from Object Storage and manage PDBs and database listeners:

dbaascli cswlib list #displays a list of available software images
dbaascli cswlib download ... #downloads a database software image
dbaascli listener start --dbname dbname
dbaascli pdb create --pdbname pdbname ...

As databases created using dbaasapi (dbaascli) on a subset of the nodes can not be managed using the OCI CLI, you’ll use the dbaascli to manage them (starting, stopping, patching, etc.).

bkup_api

Update 02.12.2022: bkup_api was replaced by dbaascli.

bkup_api is used for managing on-demand backups on Exadata DB systems in case you have specific backup configuration requirements that cannot be covered by the automatic backups. It must be run as the root user on a local compute node. For example, to create a backup:

bkup_api bkup_start --dbname=<database_name>

exacli

exacli is the command line for getting storage cell metrices and diagnostics information on Exadata DB systems. For example, the following command connects to a storage server, performs a LIST action, and exits the session (-e):

exacli -l cloud_user_clustername -c 192.168.136.7 --xml --cookie-jar -e list griddisk detail

Summary

• oci: the recommended tool for all OCI resources. If a command is available via OCI CLI, use this command. This is true for the majority (or even almost all) commands.
• dbcli: for VM and BM DB systems if the command is not available via OCI CLI, e.g. managing PDBs
• cliadm: for updating the dbcli with the latest commands for new released features
• dbaasapi dbaascli: for Exadata DB systems if the command is not available via OCI CLI, e.g.:
  • Creating and deleting non-CDBs (not recommended)
  • Creating and deleting databases on a subset of the nodes (not recommended)
• dbaascli: for Exadata DB systems if the command is not available via OCI CLI, e.g.
  • Scale up/down OCPUs in disconnected mode (ExaCC only)
  • Download and list available software images
  • Managing pluggable databases (PDBs) – use SQL alternatively
  • Rotating the TDE master encryption key – use SQL alternatively
  • Starting and stopping the Oracle Net listener – use lsnrctl alternatively
  • Managing databases created via dbaasapi (dbaascli) on a subset of the nodes (not recommended)
• bkup_api dbaascli: for managing on-demand backups on Exadata DB systems
• exacli: for getting storage cell metrics and diagnostics information on Exadata DB systems

Further Reading

• Stop and start your Autonomous Databases automatically and save 70% CPU cost
• Automate Data Pump Export in Autonomous Database for Archiving incl. Cross-region Copy