In previous articles, we looked at creating and managing Oracle Cloud Infrastructure (OCI) database and compute instances through the web UI. The UI is ideal for a new user and occasional management of a cloud environment. When a cloud administrator is managing and automating dozens or hundreds of instances, manually clicking through the UI becomes untenable. Oracle supports and maintains a number of developer tools to solve this problem.
The most basic and intuitive of these developer tools is the command-line interface (CLI). The CLI is the ideal next step from the UI, as it’s easy to install, includes built-in help, and provides a solid understanding of the underlying infrastructure, which is important when progressing onto the more advanced developer tools.
Behind the web console, CLI, toolkits, and myriad software development kits (SDKs) is the API. Calling the API directly is usually unnecessary, but having a solid understanding of it is crucial for two reasons. One, every developer tool command executed and click in the web console is translated into a web service call through the API. Two, none of the developer tools are documented completely, so there are times when reading the API documentation is necessary. Using the API directly will not be covered in this article, but it is covered in detail in the OCI documentation.
The CLI is written in Python and can be installed and run from almost any system that can run Python code. The minimum required Python version is 2.7.5 or 3.5. Oracle provides installation instructions and scripts for MacOS, Linux, Unix, and Windows.
The install script provides a help menu, but executing it without parameters will start the installation process with default values. If the installer does not find a Python installation that meets the minimum requirements, it will attempt to install it. If the installer needs to install Python, it will first attempt to use YUM. If all of the required packages cannot be found using YUM, it will finally attempt to install Python from source.
Don’t bother trying to install this on an OCI database instance. Database instances are very lean and do not include the required packages or the YUM (Yellowdog Updater, Modified) repositories needed to install them. It will install just fine on an OCI compute instance.
The PowerShell installation requires PowerShell to be run with administrator privileges and enabling RemoteSigned Execution Policy. The PowerShell script has the same prompts as the Linux script. Accepting the default values will work for most installations.
Most of the functionality of the CLI requires credentials to access the OCI resources. Generate an API key pair by executing the command, oci setup keys. Copy the public key that is created from .oci/oci_api_key_public.pem and save it for the next step.
The public key needs to be added to an OCI user account. If the account you are using is from the Oracle Identity Cloud Service (IDCS), you will first need to create an OCI user account. To create an account, open the left pane and select Governance and Administration > Identity > Users. Select Create User and give it a name and description. Select the user you just created and select Add Public Key. Paste the public key text from the previous step.
The next step is to create the configuration file, which will require the OCID of the user you just created, the Tenancy OCID, and the region. While still in the user details screen copy the OCID from the User Information tab. Then, open the left pane, select Governance and Administration > Administration > Tenancy Details, and copy the OCID from the Tenancy Information tab. Take note of the region in the top right.
Create the configuration file by executing the command, oci setup config. This script will prompt for the two OCIDs (user and tenancy) and the region. When it prompts to generate a key pair, decline and give it the path to the private key file previously generated, .oci/oci_api_key.pem. This is not the public key from previous steps, this is the private key from another file in the same directory. Test the configuration by querying the namespace, oci os ns get. The default output format is JSON. To change the output to the more readable table format, add the parameter --output table.
The help included in the tool is very detailed and intuitive. To see the help text, execute the command without any options. The help menus are also contextual. If you need to know what parameters can be used with the os command, execute oci os. If you need to know what parameters can be used with the ns option of the os command, execute oci os ns.
Managing most OCI resources, such as compute and database instances, requires the compartment OCID in which they are contained to be added to commands. The compartment OCIDs can be found in the web console or by listing them with oci iam compartment list --all. I find it easiest to store the compartment OCID in a variable.
List the database systems in a compartment with oci db system list -c $comp. If the account you are using does not have the appropriate permissions to see the database systems, this command will return an error.
Authorization in OCI is managed by adding policy statements to a policy. Policy statements apply to a group. They cannot be applied to individual users, so a group must be created before creating a policy. To create a group, open the left pane and select Governance and Administration > Identity > Groups. Select Create Group and give it a name and description. Select the group you just created and add your user to the group. Create a policy by opening the left pane, select Governance and Administration > Identity > Policies, select Create Policy, give it a name and description, and add the policy statement Allow group <group name> to manage all-resources in compartment <compartment name>.
Policies take effect immediately so you should now be able to list the databases systems with oci db system list -c $comp. Show the database details of the database system using the value from the id field with oci db database list -c $comp --db-system-id <db system id>.
With the required configuration parameters and appropriate permissions set up, many of the other command-line and programming tools are available to use with little to no additional configuration. For example, the Python SDK is already installed and ready for use.
Activate the CLI virtual Python environment with source ./lib/oracle-cli/bin/activate. The OCI Python module can now be used in a Python interactive session or within a Python script. The same configuration file we created for the CLI can be used in Python. The following code can be used to show the identity information for the OCI user account.
>>> import oci
>>> config = oci.config.from_file()
>>> identity = oci.identity.IdentityClient(config)
>>> user = identity.get_user(config[“user”]).data
At a certain point, manually clicking through the web UI is not ideal for managing a large cloud environment. Automating tasks in OCI through scripting or using third-party tools requires the ability to use developer tools. At the time of this article, Oracle supports its own CLI, as well as SDKs for Java, Python, Ruby, and Go. There are also toolkits and plug-ins for Eclipse, HDFS, Terraform, Ansible, Chef, Jenkins, Grafana, and Kubernetes. At the core of all of these tools are the REST APIs that the user can execute against directly. The number of supported tools and their capabilities are continually expanding, giving cloud administrators infinite automation possibilities for managing their OCIs.