Friday, 17 January 2020

Trimming down on OCI CLI output with a query in the RC file

Oracle Cloud Infrastructure has a command client, which leverages their REST API. One thing you can do to streamline your usage is to make use of an RC file. The RC file that would be automatically used is the one at the path: `~/.oci/oci_cli_rc`, but you can also point to an alternative file path if you have named it something different.

At the most basic level what you would typically want to do is provide some alias for arguments. A common argument being `--compartment-id`, but we can alias that to simply `-c` by specifying in our RC file:

[OCI_CLI_PARAM_ALIASES]
-c = --compartment-id


This is all good, but what I think is neat is that you can provide queries to manipulate the output that is returned to the screen.

What's a use case for this? Well one example, it's not uncommon to list the compartments so you can figure out the compartment ID, but by default there is a lot of information returned that I am almost never interested in. When your tenancy isn't very complex, it's not a problem, but when it starts to get more complex, the last thing you want to do is be scrolling pages of compartment properties you aren't interested in.

So, you define queries in a confiuration section named: [OCI_CLI_CANNED_QUERIES]. So, first lets look at the full output, so we can define which properties we want returned. What I want, and in this order is:

1. Parent compartment ID
2. Compartment ID
3. Name

So, I define my query like:

[OCI_CLI_CANNED_QUERIES]

simple_list=data[*].{"id": "id", "parent-id": "compartment-id", "name": "name"}


With that saved into my RC file, now I can run my list operation and point to by pre-defined query like so:

oci iam compartment list --query query://simple_list

And my output becomes:

[
  {
    "id": "ocid1.compartment.oc1..xxx",
    "name": "education",
    "parent-id": "ocid1.tenancy.oc1..xxx"
  },
  {
    "id": "ocid1.compartment.oc1..xxx",
    "name": "ManagedCompartmentForPaaS",
    "parent-id": "ocid1.tenancy.oc1..xxx"
  },
  {
    "id": "ocid1.compartment.oc1..xxx",
    "name": "terraform",
    "parent-id": "ocid1.tenancy.oc1..xxx"
  }
]


Much more easy to consume, right?

As you can see, the display order doesn't match the way in which I defined the query fields - it looks to come out in alphabetical order, if that matters to you.

This is just one example of what you can do. Other examples in the documentation include:

  • Returning data a simple comma separated list of values
  • Applying a filter - check out Christoph's blog with some advances examples:
  • Restricting output to a number of records

This query leverages the JMESPath technology. 

You can also see the Oracle provided query examples here: https://docs.cloud.oracle.com/iaas/Content/API/SDKDocs/cliconfigure.htm#SpecifyingNamedQueries