OCI #5 – CLI Setup

This recipe shows how to install and configure Oracle Cloud Infrastructure CLI on your client machine.

Before you start, it is recommended that you read API Signing Key recipe to understand the concept of request signing.

Oracle Cloud Infrastructure REST API

Oracle Cloud Infrastructure exposes a comprehensive REST API to manage OCI resources and configurations. Every API request must be signed with Oracle Cloud Infrastructure API Request Signature and sent using secure HTTPS protocol with TLS 1.2. Signing a request is a multi-step process that can be seen as non-trivial. This is why you usually use tools like CLI, Terraform or custom SDK-based programs that encapsulate API calls and sign the requests on your behalf. All these tools eventually make calls to OCI REST API, therefore OCI REST API is the ultimate gateway to the cloud management plane.

Oracle Cloud Infrastructure CLI

Oracle Cloud Infrastructure CLI is a python-based command line utility that encapsulates API calls to OCI REST API. This simplifies the way you consume the API, because OCI CLI takes the burden of request signing. Furthermore, you can script API consumption using mature ecosystem of Python libraries.

Installing OCI CLI

Oracle has prepared two installation scripts. One for Linux/macOs with bash and one for Windows with Powershell. The two scripts perform similar steps. They install Python and virtualenv, create an isolated Python environment, install the latest version of CLI and alter the PATH variable. Alternatively, you can perform all these steps manually.

Installing OCI CLI on Linux or macOS

  1. Execute the following commands and follow the console-based installation wizard:
    bash -c "$(curl -L https://raw.githubusercontent.com/oracle/oci-cli/master/scripts/install/install.sh)"

Installing OCI CLI on Windows

  1. Launch Powershell console with Run as Administrator option
  2. Execute the following commands and follow the console-based installation wizard:
    Set-ExecutionPolicy RemoteSigned
    powershell -NoProfile -ExecutionPolicy Bypass -Command "iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/oracle/oci-cli/master/scripts/install/install.ps1'))"

Configuring OCI CLI

CLI features with an embedded configuration wizard that generates API Signing key pair and creates CLI configuration file, based on the parameters given during configuration wizard run. You should identify a few Oracle Cloud Infrastructure Identifiers (OCIDs) before you launch the wizard.

  1. Sign in to OCI Console
  2. Go to Identity ➟ Users and copy the OCID of the user on whose behalf OCI CLI prepares, signs and sends OCI REST API requests.
  3. Go to Administration Tenancy Details and copy the OCID of the tenancy.
  4. Open a new command line window on your client machine and execute:
    oci setup config
  5. Provide the user OCID, the tenancy OCID and the region you are working with.
  6. Say Y(es) when asked if you want to generate a new RSA key pair, unless you prefer to use your own API Signing Key. To learn more on that topic, have a look at API Signing Key recipe.
  7. Say N(o) when asked if you want to write your private key passphrase to the config file, unless you do not mind storing in an open text.
  8. If you use default options for the remaining parameters, your config file will be generated as ~/.oci/config
  9. Finally, you should upload the generated public key to OCI and associate it with the user you’ve chosen in the second step. You can learn how to do it in API Signing Key recipe.

Majority, if not all, OCI REST API resource operations require Compartment OCID. You can define the default values for input parameters to OCI CLI commands, to avoid unnecessary typing, every time you invoke a CLI command. To add a default value for Compartment OCID, perform these steps:

  1. Sign in to OCI Console
  2. Go to Identity ➟ Compartments and copy the OCID of the compartment you would like to work with. If needed, create a new Compartment.
  3. Create a new file: ~/.oci/oci_cli_rc and place there the following lines:
    [DEFAULT]
    compartment-id = placeHereTheCompartmentOCID

Now, you should be ready to test OCI CLI. Let’s list the available CentOS Images:

oci compute image list --operating-system CentOS --output table --query "data [*].{Image:\"display-name\"}"
+--------------------------+
| Image                    |
+--------------------------+
| CentOS-7-2018.09.19-0    |
| CentOS-7-2018.08.15-0    |
| CentOS-7-2018.06.22-0    |
| CentOS-6.9-2018.06.22-0  |
| CentOS-6.10-2018.09.19-0 |
| CentOS-6.10-2018.08.15-0 |
+--------------------------+

You can find the complete reference of CLI commands here.

OCI #4 – API Signing Key

This guide shows how to create a new API Signing Key Pair that is required to use Oracle Cloud Infrastructure REST API.

Before you start, it is recommended that you create a dedicated service admin user for Oracle Cloud Infrastructure, instead of using your Oracle Cloud superuser. See: Service administrator account best practice, if needed.

Oracle Cloud Infrastructure exposes a comprehensive REST API to manage OCI resources and configurations. Every successful API call results in a management task being performed on behalf of a particular user defined in OCI. OCI must know how to associate an OCI REST API request with a particular user. This is done through signing the requests.

Signing a request is a multi-step process that can be seen as non-trivial. First, parts of the request are used to compose the signing string. Next, a private key is used to create the signature from the signing string. Finally, the signature is added together with some metadata to the Authorization header of the request. In order to authenticate the client and authorize the requested operation, the corresponding public key has to be uploaded and associated with the given OCI user.

Generating the key pair

We will use openssl program to generate the API Signing Key Pair. We are going to employ RSA algorithm, use the recommended 2048 bits and generate the keys in PEM format. You will be prompted to enter a new passphrase for the newly generated key twice. Remember to restrict the access to the private key.

$ openssl genrsa -out apiuser.pem -aes128 2048
Generating RSA private key, 2048 bit long modulus
.............+++
..+++
e is 65537 (0x10001)
Enter pass phrase for apiuser.pem:
Verifying - Enter pass phrase for apiuser.pem:
$ chmod go-r apiuser.pem
$ ls -l | grep pem
-rw-------    1 michal  staff     1766 Oct  3 21:24 apiuser.pem
$ openssl rsa -pubout -in apiuser.pem -out apiuser.pem.pub
Enter pass phrase for apiuser.pem:
writing RSA key
$ ls -l | grep pem
-rw-------    1 michal  staff     1766 Oct  3 21:24 apiuser.pem
-rw-r--r--    1 michal  staff      451 Oct  3 21:26 apiuser.pem.pub
$ cat apiuser.pem.pub
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA2UEWK5p5bX50/IyBsFke
VbhCLta42J5IgfMmLN7FRjOGT+CbL6aYHfRgNxvUgWqSYGbwgtNvOnp7Fre397Sa
qYVcH3w0R2O1WbQJJJmuqNhjQ01N48odN49nqeZQF9ED7SshBM+fAU7Dtt9XTuYG
5wnpK0DRlw4BFwfXoaLQJ4Gxhpsr2eA/JMCpJs4dFIEjTMshQBQ9JLYxBAo8cU6Z
s5kwRG7ZpygLVRGbpUiu4Iwu5fm2DhWNLQRHGBTjMFM9EfWRBawIoKHXBUMIQB4t
GMMqA7dFpKlJRhAPrM/Ai0k4fCNJOKfzLLTDOC3DGDcEZlljh17MiCApHWoHnewS
iQIDAQAB
-----END PUBLIC KEY-----

Uploading the public key

  1. Go to Identity ➟ Users and select the user you would like to be “api-enabled”.
  2. Click on Add Public Key and paste the newly generated public key.

oci-04-step1

You will also need the fingerprint of the key to sign the requests. The fingerprint for each associated public key can be found in API Keys tab.

oci-04-step2

OCI #3 – Service Admin user

This recipe shows how to create a new service admin user dedicated for Oracle Cloud Infrastructure.

Before you start, you must have an Oracle Cloud account. See: Cloud Account recipe, if needed.

Oracle Cloud Infrastructure uses a dedicated dashboard called OCI Console. There are two types of users that can sign in to OCI Console: federated and non-federated. The identity of federated users is asserted by a different system called an identity provider using Single Sign-on. Oracle Identity Cloud Service and Microsoft Active Directory Federation Services are two examples of an identity provider.

Superuser

The very first account that gets created for your Cloud Account becomes the super-user for all your Oracle Cloud PaaS and IaaS services. Using Unix naming, you can think of it as if it was the root user for your account. You can perform all tasks using this account and provision all kinds of available PaaS instances and IaaS resources. Furthermore, you will most probably use this account to access Oracle Support, in case you would like to read through the knowledge base or submit a service request. For a day-to-day job, this account is too powerful.

Service admin

It is recommended that you create a separate user admin account that is solely focused on Oracle Cloud Infrastructure. In order to create a new federated user to be your Oracle Cloud Infrastructure admin and use Oracle Cloud Single Sign-on powered by Oracle Identity Cloud Service follow these steps:

  1. Sign in to Oracle Cloud
  2. In My Services Console, in the top right corner, click on Users .
  3. Make sure you are in Users tab and click on Add
  4. Provide the details for the new user you are creating
  5. While in the Service Access step, scroll down to Compute and select OCI_Administrator Service Entitlement
    oci-03-step1
  6. Click Finish

You should soon get an activation link on the e-mail you used for the newly registered  user account. The link will lead you to password’s initial setup page. If you do not receive the link within a few minutes, just click on Can’t sign in link on the user login page and provide your login (usually the e-mail address).

What has just happened ? You’ve created a new federated user account managed in Oracle Identity Cloud Service (IDCS). IDCS is the default identity provider for federated users in Oracle Cloud Infrastructure. OCI_Administrator group members in IDCS are mapped to the Administrators group in OCI.

From now on, you can use this account to sign in to Oracle Cloud Infrastructure. To learn more, visit Accessing OCI Console recipe.

Fine-grained security model

Cloud Security Alliance’s Security Guidance says about the concept of “lower-level administrative accounts” called “service administrators” “that can only manage parts of the service”. You could imagine creating additional admin users that are allowed to manage only parts (selected types of resources inside particular compartments) of Oracle Cloud Infrastructure tenancy. This can be achieved with a blend of OCI Policies and non-federated user accounts that you define directly in Oracle Cloud Infrastructure. You will soon find a dedicated recipe that will tell more about it.

OCI #2 – Accessing OCI Console

This recipe shows how to access Oracle Cloud Infrastructure management dashboard.

Before you start, you must have an Oracle Cloud account. See: Cloud Account recipe, if needed.

Oracle Cloud offers a broad variety of SaaS, PaaS and IaaS services. Oracle Cloud Infrastructure (new generation IaaS) uses a dedicated dashboard called OCI Console. You can access it through My Services dashboard or bookmark a direct link to OCI Console.

There are two types of users that can sign in to OCI Console: federated and non-federated. The identity of federated users is asserted by a different system called an identity provider using Single Sign-on. Oracle Identity Cloud Service and Microsoft Active Directory Federation Services are two examples of an identity provider.

When you provision Oracle Cloud trial account, your cloud account superuser gets created in Oracle Identity Cloud Service (IDCS) and assigned to OCI_Administrators group. If you want to sign in as the superuser or any other user defined in Oracle Identity Cloud Service and assigned to a federated IDCS group, you should choose the SSO option.

oci-02-step1

As I mentioned before, there are two ways to access OCI Console.

Method I: Using a direct link

  1. Go to console.region.oraclecloud.com where region is the home region of your account. For example: https://console.uk-london-1.oraclecloud.com
  1. If you haven’t been already logged in, you will be asked to do so.

Method II: Using My Services dashboard

  1. Go to https://cloud.oracle.com/sign-in and sign in to My Services dashboard.
  2. Open the navigation drawer using the three-bar menu in the top left corner.
  3. Expand Services and click on Compute

This is Oracle Cloud Infrastructure Console:

oci-02-step2

OCI #1 – Cloud Account

This recipe shows how to create a new Oracle Cloud Account based on Universal Credits usage model.

Payment Models

The usage model based on Universal Credits applies to all IaaS and PaaS capabilities including Oracle Cloud Infrastructure. There are two payment models:

  • Pay as you Go – flexible; your credit card is charged every month only for the cloud resources you use.
  • Monthly Flex plan – cost-effective, because of the additional discounts that apply; you declare the estimated, monthly usage for at least one year; you are billed every month in advance and receive Universal Credits that can be spent on any IaaS and PaaS capabilities at discounted prices.

The best way to evaluate Oracle Cloud is to create a trial account first. Oracle Cloud trial let’s you use Oracle Cloud services for 30 days free of charge. In theory, there is a limit of $300 in Universal Credits that can be spent on any IaaS and PaaS resources, but it is rather difficult to use up all promotional credits, simply because the expensive services are additionally discounted during the trial.

A trial account can be upgraded to a standard, “Pay as you Go” account as soon as the trial period expires. To do so, you would need to click “Activate” button in “Account Management” page.

Create a Trial Account

  1. Go to http://cloud.oracle.com and click on Try for Free
    oci-01-step1
  2. Click on Create a Free Account
    oci-01-step2
  3. You will need to provide your company- or personal details and a mobile phone number that will be used to receive a verification code. Next, you need to provide the credit card details and agree to the terms and conditions.
    oci-01-step3

  4. The provisioning of your cloud account will begin and you should soon receive a first e-mail. The e-mail will include a link to the Identity Cloud Service Console where you have to change your cloud root user password.
    oci-01-step4

  5. The services will be gradually added to your account. You should now wait until you receive a second e-mail that announces the readiness of Oracle Cloud services.
    oci-01-step5

  6. From now on, you should always be able to access your Cloud Account My Services dashboard directly using this link:

    myservices-yourCloudAccountName.console.oraclecloud.com

    oci-01-step6