Use Oracle Cloud Infrastructure Command Line Interface to manage Oracle Exadata Database Service on Cloud@Customer

Introduction

Oracle Cloud Infrastructure Command Line Interface (OCI CLI) is a great tool for managing your resources in OCI, including Oracle Exadata Database Service on Cloud@Customer resources. OCI CLI lets you easily and efficiently orchestrate and automate OCI operations. As OCI CLI calls on the OCI REST API, this means OCI CLI and OCI REST API is compatible even though the syntax is different. You can use OCI CLI during your development of OCI REST API automations for trial and error and then deploy your automations with less effort.

This is a two part series, where in this first part we are introducing you to the basics of OCI CLI, while in the second part we are focusing more on the Oracle Exadata Database Service on Cloud@Customer specific commands and workflows.

Note: OCI CLI is also required when using Dynamic Scaling with the remote plugin, but Dynamic Scaling itself will not be covered in this tutorial.

Objectives

Prerequisites

Task 1: Install OCI CLI

The OCI CLI is built on the OCI Software Development Kit (SDK) for Python and runs on Mac, Windows, or Linux. The Python code makes calls to OCI APIs to provide the functionality implemented for the various services including Oracle Exadata Database Service on Cloud@Customer and Oracle Autonomous Database on Exadata Cloud@Customer.

  1. Download OCI CLI for your OS from here: OCI CLI GitHub repository.

  2. Follow the installation instructions as per your operating system.

  3. Run the following command to verify your installation.

    $ oci --version

  4. Set up a configuration using the setup dialog that contains the required credentials for working with OCI.

    $ oci setup config

  5. Verify your configuration file.

    For example:

    [DEFAULT]
user=ocid1.user.oc1..<unique_ID>
fingerprint=<your_fingerprint>
key_file=~/.oci/oci_api_key.pem
tenancy=ocid1.tenancy.oc1..<unique_ID>
# Some comment
region=us-ashburn-1

  6. Run the following command to check your connectivity, which will show the namespace of your tenancy.

    $ oci os ns get

  7. Run the following command to list your available compartments.

    $ oci iam compartment list

    This will generate the following JSON response:

    {
 "data": [
{
       "compartment-id": "ocid1.tenancy.oc1..xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx5xlq",
       "defined-tags": {
                 "Oracle-Tags": {
                                "CreatedBy": "default/some-email@oracle.com",
                                "CreatedOn": "2023-11-10T13:27:32.885Z"
}
},
"description": "Compartment for Exadata Infrastructure",
"freeform-tags": {},
"id": "ocid1.compartment.oc1..xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxdh7q",
"inactive-status": null,
"is-accessible": null,
"lifecycle-state": "ACTIVE",
"name": "ExaInfra",
"time-created": "2023-11-10T13:27:32.945000+00:00"
     }
     ]
}

    Note: Note that the output has been truncated to show only the first compartment.

  8. Run the following command to list all work requests in a compartment.

    $ oci work-requests work-request list --compartment-id ocid1.compartment.oc1..xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxdh7q

Use Output Formatting to Filter and Format the Command Outputs for your Needs

As you have seen in the previous examples, the JSON response from OCI CLI commands can be extensive, hard to follow and not easy to read.

At the command prompt in Linux for example, you can always pipe the output to power tools like grep to filter your response.

Use the following command to list all the VM clusters in a specific compartment and filtering for id.

$ oci db vm-cluster list --compartment-id <OCID> | grep \"id\"

This will generate the following response:

"id":"ocid1.vmcluster.oc1.eu-frankfurt-1.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx2tkq"
"id":"ocid1.vmcluster.oc1.eu-frankfurt-1.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz5ra"

However, OCI CLI has built in query functionality with the --query parameter, where you can specify which fields you want to query for.

  1. Run the following command with the --query parameter.

    $ oci db vm-cluster list --compartment-id <OCID> --query "data[].[\"id\"]"

    The JSON response will be:

    [
     [
"ocid1.vmcluster.oc1.eu-frankfurt-1.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx2tkq"
     ],
     [
"ocid1.vmcluster.oc1.eu-frankfurt-1.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz5ra"
      ]
]

  2. You can easily specify additional fields behind --query to build a more complex query.

    $ oci db vm-cluster list --compartment-id <OCID> --query "data[].[\"hostname\" , \"id\"]"

    The JSON response will be:

    [
     [
"fraexaclu1-uvlkz",
"ocid1.vmcluster.oc1.eu-frankfurt-1.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx2tkq"
     ],
     [
"fraexaclu2-2uyfk",
"ocid1.vmcluster.oc1.eu-frankfurt-1.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz5ra"
     ]
    ]

  3. You can get a more user-friendly output by using the --output table parameter.

    $oci db vm-cluster list --compartment-id <OCID> --query "data[].[\"hostname\" , \"id\"]" --output table

    The response will be:

    +----------------------------------------------------------------------------------------------------------------------+
| Column1          |  Column2                                                                                          |
+----------------------------------------------------------------------------------------------------------------------+
| fraexaclu1-uvlkz | ocid1.vmcluster.oc1.eu-frankfurt-1.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx2tkq |
| fraexaclu2-2uyfk | ocid1.vmcluster.oc1.eu-frankfurt-1.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz5ra |
+------------------+---------------------------------------------------------------------------------------------------+

  4. You can also specify the headings for the columns by using the --query parameter.

    $ oci db vm-cluster list --compartment-id <OCID> --query "data[].{\"Hostname\" : \"hostname\" , \"OCID\" : \"id\" }" --output table

    The response will be:

    +----------------------------------------------------------------------------------------------------------------------+
| Hostname          | OCID                                                                                             |
+----------------------------------------------------------------------------------------------------------------------+
| fraexaclu1-uvlkz | ocid1.vmcluster.oc1.eu-frankfurt-1.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx2tkq |
| fraexaclu2-2uyfk | ocid1.vmcluster.oc1.eu-frankfurt-1.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz5ra |
+------------------+---------------------------------------------------------------------------------------------------+

    Note: It is important to understand the correlation between the syntax used with the --query parameter and the JSON response. OCI CLI sub-commands like list typically returns many results, while OCI CLI sub-commands like get returns only one result.

    • Where the JSON response shows that the data is a list or array as specified by a [.

      [opc@jens-oci-1 ~]$ oci db vm-cluster list
{
     "data": [
          {

      Then the query syntax look like this:

      --query "data[].[ field1 , field2 ]"

    • Where the JSON response shows that the data is a single object.

      [opc@jens-oci-1 ~]$ oci db vm-cluster get
{
     "data": {

      Then the syntax for the get command look like this:

      --query "data.[ field1 , field2 ]"

Use Input Assistance to Simplify the Use of OCI CLI

There is a number of different ways to get input assistance with the OCI CLI for both ad-hoc and automated use cases.

Acknowledgments

More Learning Resources

Explore other labs on docs.oracle.com/learn or access more free learning content on the Oracle Learning YouTube channel. Additionally, visit education.oracle.com/learning-explorer to become an Oracle Learning Explorer.

For product documentation, visit Oracle Help Center.