X

Best Practices from Oracle Development's A‑Team

Calling OCI CLI Using Instance Principal

Vivek Singh
Principal Solutions Architect

Instance Principal is the capability in the Oracle Cloud Infrastructure Identity and Access Management (IAM) service that allows you to make service calls from an instance. With instance principals, you no longer need to configure user credentials on the services running on your compute instances or rotate the credentials. Instances themselves are a new principal type in IAM. Each compute instance has its own identity, and it authenticates by using certificates that are added to the instance by the new instance principal’s capability. 

You use instance principals to authorize an instance to make API/CLI calls in Oracle Cloud Infrastructure services. After you set up the required resources and policies, an application running on an instance can call Oracle Cloud Infrastructure public services, removing the need to configure user credentials or a configuration file. You can read more details about calling services from an instance here

To use instance principals, you need to create a dynamic group and policy as given below.

Create Dynamic Group

Dynamic Groups use rules to define which instances are members of the group. The matching rule can be a simple rule where you provide the OCID of the compute instance that is used for CLI. There is a Rule Builder that you can use from the OCI console to make the rule. To create a dynamic group using OCI console the documentation is given here

To create a dynamic group, do the following:

  • Log into the Oracle OCI console.
  • Select the hamburger menu on the top left corner, select Identity, select Dynamic Groups, and click Create Dynamic Group.
  • In the Create Dynamic Group screen, enter its name, and a friendly description.
  • Enter a rule so your instance is qualified for the dynamic group.

Create Dynamic Group

 

If you are not sure how to define the rule you can use the Rule Builder to help you build the rule. Click the Rule Builder button. Enter the criteria for your rule. In this blog, I am using a very simple rule, where I specify the OCID of the compute VM where I will run the OCI CLI scripts.


Enter the matching rule and hit Add Rule button. In the Create Dynamic Group screen click Create button.

Create Policy

Once you have created the dynamic group, you need to create a policy that gives your group the privilege to stop, start, and update autonomous databases. Your group should have permission to manage autonomous-database-family. The documentation for writing policies is given here

To create a policy do the following:

  • Log into the Oracle console.
  • Select the hamburger menu on the top left corner, select Identity, select Policies, and click Create Policy.
  • In the Create Policy Screen enter its name, description, and policy statement. Your policy statement could be like:

Allow dynamic-group to manage autonomous-database-family in compartment < name of compartment >

 

Click Create button to create the policy.

 

Enabling Instance Principal Authorization for the CLI

Once you have created the Dynamic Group, the Matching Rule, and the Policy you are ready to use Instance Principals for authorizing OCI CLI calls. To enable Instance Principal authorization from the CLI, you can use the authorization option (--auth) for a command. For example:

oci ns get --auth instance_principal

 

Alternatively, you can set OCI_CLI_AUTH environment variable:

OCI_CLI_AUTH=instance_principal

Note that if both are set, the value set for --auth takes precedence over the environment variable.

For example, you can use the following OCI CLI command to start an ATP Database that uses Instance Principal for authorization.

oci db autonomous-database start –autonomous-database-id < adb OCID > --auth instance_principal

For more information about working with the CLI, click here.

 

References

  1. Calling Services from an Instance: https://docs.cloud.oracle.com/en-us/iaas/Content/Identity/Tasks/callingservicesfrominstances.htm
  2. Managing Dynamic Groups: https://docs.cloud.oracle.com/en-us/iaas/Content/Identity/Tasks/managingdynamicgroups.htm
  3. Writing authorization policies for Dynamic Groups: https://docs.cloud.oracle.com/en-us/iaas/Content/Identity/Tasks/callingservicesfrominstances.htm#Writing
  4. OCI Command Line Interface (CLI): https://docs.cloud.oracle.com/en-us/iaas/Content/API/Concepts/cliconcepts.htm
  5. CLI supported OS and Python versions:  https://docs.cloud.oracle.com/en-us/iaas/Content/API/Concepts/cliconcepts.htm#SupportedPythonVersionsandOperatingSystems
  6. OCI CLI Quick Start:  https://docs.cloud.oracle.com/en-us/iaas/Content/API/SDKDocs/cliinstall.htm
  7. Instance Principals:  https://blogs.oracle.com/cloud-infrastructure/announcing-instance-principals-for-identity-and-access-management

Be the first to comment

Comments ( 0 )
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.Captcha