Oracle Cloud Infrastructure Documentation

Using Resource Manager with the CLI

This topic provides guidance for using the Oracle Resource Manager using the Oracle Cloud Infrastructure CLI. For guidance using Resource Manager in the Console, see Using Resource Manager in the Console.

This topic assumes that you have installed and configured the CLI. For more information on setting up the CLI, see the Quickstart and Configuration.

Warning

Oracle recommends that you avoid using string values that include confidential information in the Oracle Cloud InfrastructureConsole, API, or CLI. Do not provide user credentials in your Terraform configurations.

Prepare Your Configuration

The technology that drives the Resource Manager is Terraform, and using Terraform begins by creating a Terraform configuration. A Terraform configuration is a collection of one or more configuration (.tf) files that use declarative code to describe your infrastructure configuration. For more information about Terraform configurations, see Writing Terraform Configurations. See also Terraform: Configuration.

For the purposes of this walkthrough, we use a single Terraform configuration file named vcn.tf. It is a very basic sample file that defines just one Terraform provider, one Oracle Cloud Infrastructure resource, and declares a set of variables.


variable "compartment_ocid" {}
variable "region" {}

provider "oci" {
  region = "${var.region}"
}

resource "oci_core_virtual_network" "vcn1" {
  cidr_block = "10.0.0.0/16"
  dns_label = "vcn1"
  compartment_id = "${var.compartment_ocid}"
  display_name = "vcn1"
}

Create a Stack

Use the stack create command and provide the compartment OCID where you intend to create the stack. Also, reference your Terraform configuration file (vcn.tf in the example that follows). Optionally, provide a user-friendly name for the stack, and also add a description, as shown.

To create a stack, run the following command:

oci resource-manager stack create –-compartment-id <compartment_OCID> 
    --config-source vcn.zip --variables file://variables.json
    --display-name "My Example Stack" 
    --description Tutorial to create a VCN

When creating a stack using the stack create command, the --config-source parameter takes the name of a single .zip file that contains one or more configuration files.

To expose the directory structure, use the optional --working-directory parameter to point to the root configuration file in the directory. If you do not use this parameter, the service assumes that the top-level file in the directory is the root configuration file.

Warning

Do not include the .terraform directory in the working directory in your configuration .zip file. Including .terraform in your working directory will cause an invalid parameter error when calling stack create or stack update.

Important

On Windows, be sure the .zip file and variables.json files are in the same directory from which you're running the CLI. The CLI currently has a limitation on Windows that prevents correct handling of the files if either one is in a subdirectory.

Example variables.json

Following is an example variables.json file:

{ 
  "compartment_ocid": "ocid1.compartment.oc1..example7lcdlihrvur7xq", 
  "region": "us-phoenix-1" 
}	

The Oracle Cloud Infrastructure Terraform provider requires additional parameters when running Terraform locally (unless you are using instance principals). For more information on using variables in Terraform, see Input Variables. See also Input Variable Configuration.

Example stack create Response

Following is an example response to the call to stack create:

{
  "data": {
    "config-source": {
      "working-directory": null,
      "config-source-type": "ZIP_UPLOAD"
    },
    "defined-tags": {},
    "description": "Tutorial to create a VCN",
    "display-name": "My Example Stack",
    "freeform-tags": {},
    "id": "ocid1.ormstack.oc1..examplej6whb4mluogzdv4xjma",
    "lifecycle-state": "ACTIVE",
    "time-created": "2018-04-03T18:26:56.299000+00:00",
    "variables": {
      "compartment_ocid": "ocid1.compartment.oc1..example7lcdlihrvur7xq", 
      "region": "us-phoenix-1"
    }
  }
}

List Stacks in a Compartment

To retrieve a list of the stacks in a given compartment, use the stack list command and provide the compartment OCID, as shown following.

oci resource-manager stack list –-compartment-id <stack_compartment_OCID>

List Full Details of a Stack

To retrieve the full details of a given stack, use the stack get command and provide the stack's OCID, as shown here:

oci resource-manager stack get –-stack-id <stack_OCID>

Delete a Stack

To delete a stack, use the stack delete command and provide the stack's OCID, as shown here:

oci resource-manager stack delete –-stack-id <stack_OCID>

Note

Before you delete a stack, first run a destroy job on the stack because stack delete does not clean up the stack's resources when it deletes the stack.

Run a Plan Job

After creating a stack and uploading your Terraform configuration, you can run jobs against the stack. First, run a plan job. During a plan job, Resource Manager parses the configuration files and creates an execution plan. The execution plan allows you to review the actions that will take place when you execute the configuration.

To run a plan job, use the job create command and pass in the appropriate stack OCID, then specify the operation, as shown here:

oci resource-manager job create --operation PLAN 
    --stack-id <stack_OCID> 
    --display-name "Example Plan Job"

This operation can take several minutes. At any time, you can check the current state of the plan job by calling job get and providing the job OCID., as shown:

oci resource-manager job get –-job-id <plan_job_OCID>

The call response includes a lifecycle-state value, which is SUCCEEDED once the job has completed. In the following example response, the lifecycle-state value is ACCEPTED, which means the API call was valid, but the job has not yet begun.

{
  "data": {
    "compartment-id": " ocid1.compartment.oc1..example3e6iindlsm5e4elqa ",
    "defined-tags": null,
    "display-name": "Example Plan Job",
    "freeform-tags": {},
    "id": "ocid1.ormjob.oc1..exampleog2iwhxafi2iilsn6d3p5",
    "lifecycle-state": "ACCEPTED",
    "operation": "PLAN",
    "stack-id": " ocid1.ormstack.oc1..examplej6whb4mluogzdv4xjma ",
    "time-created": "2018-03-09T20:52:13.922000+00:00",
    "time-finished": null,
    "variables": {
      "compartment_ocid": "ocid1.compartment.oc1..example7lcdlihrvur7xq", 
      "region": "us-phoenix-1"
    }P
  }
}

Review the Execution Plan

The content of the plan is viewable in the job's log file. To view log entries for a given job, use the job get-job-logs command and provide the job OCID, as shown here:

oci resource-manager job get-job-logs --job-id <plan_job_OCID>

The command returns JSON objects that describe log entries. Each object has a message member with a property that displays one line of the execution plan. In the example shown below, the plan creates a single virtual cloud network (VCN); the remaining members show details about the VCN.

...
 {
   "level": "INFO",
   "message": "Terraform will perform the following actions:",
   "timestamp": "2018-05-24T00:57:14.170000+00:00",
   "type": "TERRAFORM_CONSOLE"
 },
 {
   "level": "INFO",
   "message": "",
   "timestamp": "2018-05-24T00:57:14.170000+00:00",
   "type": "TERRAFORM_CONSOLE"
 },
 {
   "level": "INFO",
   "message": "+ oci_core_virtual_network.vcn1",
   "timestamp": "2018-05-24T00:57:14.170000+00:00",
   "type": "TERRAFORM_CONSOLE"
 },
 {
   "level": "INFO",
   "message": "id: <computed>",
   "timestamp": "2018-05-24T00:57:14.172000+00:00",
   "type": "TERRAFORM_CONSOLE"
 },
 {
   "level": "INFO",
   "message": "cidr_block:  \"10.0.0.0/16\",
   "timestamp": "2018-05-24T00:57:14.172000+00:00",
   "type": "TERRAFORM_CONSOLE"
 },
 {
   "level": "INFO",
   "message": "compartment_id:  \"ocid1.tenancy.oc1..exampleaqnpcpfqfmrf6dw5gcew7yqpirvarueirj2mv4jzn5goejsxma\",
   "timestamp": "2018-05-24T00:57:14.172000+00:00",
   "type": "TERRAFORM_CONSOLE"
 },
 {
   "level": "INFO",
   "message": "default_dhcp_options_id:  <computed_value>",
   "timestamp": "2018-05-24T00:57:14.172000+00:00",
   "type": "TERRAFORM_CONSOLE"
 },
 {
   "level": "INFO",
   "message": "      default_route_table_id: <computed_value>",
   "timestamp": "2018-05-24T00:57:14.172000+00:00",
   "type": "TERRAFORM_CONSOLE"
 },
 {
   "level": "INFO",
   "message": "      default_security_list_id: <computed_value>",
   "timestamp": "2018-05-24T00:57:14.172000+00:00",
   "type": "TERRAFORM_CONSOLE"
 },
...

Updating the Execution Plan

To update the execution plan, follow these steps:

  1. Open the Terraform configuration (.tf) file and update the configuration as desired.
  2. Update the stack to use the revised configuration file by using stack update (oci resource-manager stack update <options>).
  3. Run a new plan job against the stack.
  4. Review the resulting execution plan (log files) and confirm the output.

Run an Apply Job

Running an apply job takes the execution plan and runs (applies) it against the stack. To create and run the apply job, call the job create command and pass in the plan job OCID, the stack OCID, the operation type, and optionally a display name, as shown here:

oci resource-manager job create --operation APPLY
    –-apply-job-plan-resolution <JSON string>
    --stack-id <stack_OCID>
    --display-name "Example Apply Job"

It is strongly recommended that you run a plan job before you run an apply job, as you will need to provide a plan job OCID as an input parameter on your apply job command, --apply-job-plan-resolution. Note that --apply-job-plan-resolution is a complex type that takes a JSON string as input. This JSON string can take only one of three available parameters, isAutoApproved, isUseLatestJobId, or planJobId, as shown:

{
  "planJobId": "<plan_job_OCID>"
  "isAutoApproved": false,              
  "isUseLatestJobId": false,                          
}

Depending on which approach you use, do one of the following:

  • Set the planJobId parameter to the plan job OCID.
  • Set isAutoApproved to true to use the Terraform configuration directly without reference to an execution plan.
  • Set the isLatestJobId to true to use the most recently run plan job

Following is an example of JSON input when using the planJobId parameter:

oci resource-manager job create --stack-id <stack_OCID> --apply-job-plan-resolution '{"planJobId":"<plan_job_OCID>"}' --operation APPLY

Following is an example of JSON input when using the isAutoApproved parameter:

oci resource-manager job create --stack-id <stack_OCID> --apply-job-plan-resolution '{"isAutoApproved":true}' --operation APPLY

Periodically check the lifecycle state of your apply job to see when it switches from IN_PROGRESS to SUCCEEDED. To do so, use the job get command and provide a job OCID, as shown here:

oci resource-manager job get –-job-id <apply_job_OCID>

View State

When you run an apply job, Resource Manager creates a state file, which you can then download and inspect by calling job get-job-tf-state and passing in the job OCID, as shown:

oci resource-manager job get-job-tf-state --job-id <apply_job_OCID>

This call returns a JSON representation of the state file. Following is an example state file:

{
  "data": {
    "lineage": "57ef4f0c-c8cd-8a32-d45f-d2c40be7b915",
    "modules": [
      {
        "depends_on": [],
        "outputs": {},
        "path": [
          "root"
        ],
        "resources": {
          "oci_core_virtual_network.vcn1": {
            "depends_on": [],
            "deposed": [],
            "primary": {
              "attributes": {
                "cidr_block": "10.0.0.0/16",
                "compartment_id": "ocid1.tenancy.oc1..examplerueirj2mv4jzn5vkjgoejsxma",
                "default_dhcp_options_id": "ocid1.dhcpoptions.oc1.phx.exampletlwtdnjp5nuixopfwq",
                "default_route_table_id": "ocid1.routetable.oc1.phx.examplehttsmjqc6vgnq7dw75h6q6oq",
                "default_security_list_id": "ocid1.securitylist.oc1.phx.exampleztvxuauezzmz4qxsfg6e4c5l7dlq",
                "display_name": "My VCN display name",
                "dns_label": "myvcntest",
                "id": "ocid1.vcn.oc1.phx.examplegjih5mjjkb3g777aza",
                "state": "AVAILABLE",
                "time_created": "2018-05-24 01:13:05.855 +0000 UTC",
                "vcn_domain_name": "myvcntest.oraclevcn.com"
              },
              "id": "ocid1.vcn.oc1.phx. examplegjih5mjjkb3g777aza",
              "meta": {
                "e2bfb730-ecaa-11e6-8f88-34363bc7c4c0": {
                  "create": 300000000000,
                  "delete": 300000000000,
                  "update": 300000000000
                }
              },
              "tainted": false
            },
            "provider": "provider.oci",
            "type": "oci_core_virtual_network"
          }
        }
      }
    ],
    "serial": 4,
    "terraform_version": "0.11.7",
    "version": 3
  }
}

Inspect Resources on the Stack

After provisioning your stack with an apply job, you can inspect the cloud resources that you've provisioned by issuing the following command and specifying which resource you wish to inspect. In our example configuration, we are looking at list of VCNs in the compartment to confirm that the one you created is in the list.

oci network vcn list 
    --compartment-id <vcn_compartment_OCID>

Run a Destroy Job

You can tear down and clean up the resources you've created by running a destroy job and specifying the stack OCID, as shown here:

oci resource-manager job create --operation DESTROY --stack-id <stack_OCID> --apply-job-plan-resolution '{"isAutoApproved": true}'

To confirm that the cloud resources have been deleted, list the VCNs in the compartment to confirm that your VCN no longer appears in the list:

oci network vcn list 
    --compartment-id <vcn_compartment_OCID>