Oracle Cloud Infrastructure (OCI) provides a command line interface (CLI) that provides the same core capabilities as the OCI Console, extends the Console functionality, and facilitates developers and other user groups to automating the entire process of controlling, managing, and reporting through scripts. This blog aims to highlight one of the powerful yet least used features of OCI CLI: search, query, and reporting capabilities. These capabilities become critical, especially for cloud architects and cloud operations, to manage your OCI footprint at scale and when you have to deal with large amounts of output.
OCI also offers a plethora of options for automation, configuration management, cloud analytics, and reporting. Oracle Resource Manager and Terraform using OCI providers great options for developing immutable infrastructure as code (Iac), while OCI CLI provides excellent custom scripting and reporting options.
While you can read the documentation for yourself, I will focus on exemplifying a few key features related to the blog’s core theme. OCI CLI can generate outputs in the following formats with the output flag.
|JSON||The output is formatted as JSON string and is the default format; JSON is program-friendly but not human-friendly.|
|Table||The output is formatted as a table using the characters +|- to form cell borders. It typically presents in an easier-to-read, human-friendly format.|
|--raw-output||You can supply this argument to the CLI if you know that the output is a single string value; surrounding quotes are removed for you in the output.|
Let’s start with a practical use case. You’re asked to list all the block volumes that exceed the size of 120 GB for a given compartment and region. You can use the SDK or the built-in features of OCI CLI with simple shell scripting. Compartments are foundational building blocks to organize and isolate your OCI resources.
for i in $(oci iam compartment list --compartment-id-in-subtree TRUE --all --query 'data[*].id' --profile us-ashburn-1|sed 's/\"//g;s/,//g'|egrep -v -e "\[" -e "\]")
This command gives you the following output:
Now, let’s dissect this script to understand the power that the CLI brings to the table.
oci iam compartment list --compartment-id-in-subtree TRUE --all --query 'data[*].id' --profile us-ashburn-1
This query lists all the parent compartments and their subtrees. With query ‘data[*].id’, we are filtering only the OCID of the compartment. To know more about OCIDs, see the Resource Identifier documentation.
Now that the compartment lists are available, let’s get the list of availability domain names.
oci iam availability-domain list --query 'data[*].name
Without the query arguments, the output has copious information about the availability domains, such as name, comparment_id, and OCID. We’re interested only in the availability domain name, and we get it by using JMESPath. JMESPath is the de facto query language for JSON. For details on JMESPath, see the documentation. Here, the argument query conforms to JMESPath query patterns. We select all data arrays and selectively displaying the required columns.
Now that we’ve seen the basics of selecting en masse, we can explore ways to filter and look for storage volumes greater than 120 GB with the following command.
oci bv boot-volume list --profile us-ashburn-1 --compartment-id $i --availability-domain $adomain \
Here, ?“size-in-gbs”> `120` refers to the filtering and outputs those tuples that exceed 120 GB only. The string [?” size-in-gbs”?>`120`] acts as a where clause and filters out the volumes that are less than the provided number. The possibilities are endless, and you can use them in script.
If you’re asked to list all the instances in stopped or terminated status, you need to identify all the compartments and recursively list the instances in the previous states. Or you can use the following command:
oci search resource structured-search --query-text "QUERY instance resources where lifeCycleState = 'TERMINATED'||lifeCycleState = 'STOPPED'"
Then, you get the following output:
The JSON output is more machine reader-friendly than human reader-friendly. We can make the display readable by using the following output option of “table”:
oci search resource structured-search \
Now, the following output is more human friendly:
Here, we’re using structured search. You can also use free-form search.
When using OCI CLI, you need to consider the following leading practices:
OCI CLI operations except get are not idempotent.
If subsequent operations depend on the completion of the current CLI command, use the appropriate wait-for-state flag with the required status, such as succeeded or failed.
Qualify at the appropriate compartment levels when you use recursive operations. Remember, compartments can be six levels deep.
For significant data retrievals, favor server-side filtering over client-side (JMESPath).
As shown in this posting, OCI CLI is not only powerful, but if used appropriately, it also provides great scripting and custom solutions capability for cloud architects and cloud operations. Happy scripting with Oracle Cloud Infrastructure CLI.