Terraform Configurations for Resource Manager

This topic describes requirements and recommendations for Terraform configurations used with Resource Manager. For basic information about Terraform configurations, see Writing Terraform Configurations. For instructions on using configurations with stacks and jobs, see Managing Stacks and Jobs.

You can store your Terraform configuration file locally or remotely, using a source code control system. With remote storage, any job running on the associated stack automatically uses the latest version of your configuration. For more information about remotely storing your file, see Managing Configuration Source Providers (Console).

In addition to writing your own Terraform configuration file, you also have the option to generate a Terraform configuration from either an existing compartment using resource discovery or a sample solution.


Do not provide user credentials or other confidential information in your Terraform configurations.

Terraform Provider

When using Resource Manager, the region field in the provider "oci" block is the only required field.

File Structure

Resource Manager requires the following file structure for the Terraform configuration:

  • The working directory must contain at least one .tf file. The working directory cannot contain a .terraform directory.

    The working directory is the path from which to run Terraform. By default, the working directory is the root directory of your configuration (for an uploaded configuration, the root of your .zip file). When using the API, you can specify a different location for the working directory by setting the workingDirectory parameter.

  • The configuration must follow guidelines specified in Writing Terraform Configurations.
  • No Terraform state files (.tfstate) can exist in the configuration.
  • If you plan to upload the configuration locally, then bundle all files into a .zip file.

Modules: We recommend that all modules used by a Resource Manager stack are included locally in the configuration and referenced using a local path. To use a module for Oracle Cloud Infrastructure from the Terraform Module Registry, do the following.

  • Download the source from the Terraform Module Registry and include the relevant portion in a subdirectory within your Terraform configuration (for an uploaded configuration, make the subdirectory a part of your .zip file).
  • Reference the module using a local path. For more information, see Local Paths.


Resource Manager supports the native Terraform behavior for handling variables. You can include a terraform.tfvars file and files with the .auto.tfvars extension in the configuration .zip file. For more information about defining variables, see Define Variables and Input Variables.

Adding a Schema Document to Facilitate Variable Entry

You can make it easier for your users to enter variables when they create or update a stack in the Console using your Terraform configuration. A Resource Manager schema document clarifies the meaning and use of variables in the Console. The schema document allows you to: 

  • Validate and constrain variables to communicate permitted values more clearly.
  • Name, group, and order variables.
  • Require variables.
  • Control visibility of variables.
  • Dynamically prepopulate variable values.

Schema Document Requirements

The Resource Manager schema document has the following requirements:

  • YAML format.
  • Placement under the root folder of the Resource Manager Terraform configuration. (By default, the schema document assumes that the root folder is the working folder.)

For example schema documents and more information, see the example schema and meta schema.

Validating and Constraining Variable Entries

Terraform's configuration language supports a default value, a description, and three types for input variables: strings, lists, and maps. Because these three types are all strings, users can have difficulty understanding what values are permitted for each variable.

Use a schema document to define validations and constraints for your variables. These validations and constraints help users determine permitted values when creating and editing stacks using the Console.

Example 1: Enum type for validating and constraining entry in a variable field. The Console renders the num_nodes field as a selectable list, with available selections of 1 and 2. The default value is 2.

  type: enum
  - "1"
  - "2"
  default: "2"

Example 2: Pattern for validating entry in a variable field. The Console renders the url field as a free text entry field, validating the entered value against the provided URL pattern (and the type).

  type: string
  pattern: ^https?:\/\/(www\.)?[-a-zA-Z0-9@:%._\+~#=]{2,256}\.[a-z]{2,4}\b([-a-zA-Z0-9@:%_\+.~#?&//=]*)$

Naming and Requiring Variables

In your schema document, add a groupings node. In this node, add a title and list the variables you want in the group in the order you want. You can specify friendly names and descriptions for the variables and explicitly requiring variables. When a variable is required, the user must specify a value.

The following example defines a group titled "Create A VCN" that lists the region and compartment_ocid. Defining a variable by type (such as oci:identity:region:name for region) makes the fields selectable instead of free text input. Each field also includes a friendly name and description. Both variables are required.

schemaVersion: 1.0.0
version: "20190612"
locale: "en"
  - title: "Create A VCN"
    - region
    - compartment_ocid
    type: oci:identity:region:name
    title: Region
    description: The region in which to create all resources
    required: true
    type: oci:identity:compartment:id
    title: Target Compartment
    description: The target compartment for all of the provisioned resources
    required: true

The Console renders the "Create A VCN" variable group as follows.

This screenshot shows the result of the "Create A VCN" variable group from the sample schema

Controlling Visibility of Variables

In more complex stack launches, you sometimes specify input variables for certain configurations of the stack only. Use the schema to control visibility of groups and variables based on the values of other variables. Supported operations include "eq", "and", "or", and "not".

In the following example, the "Equality Conditional Section" is visible if the value of the variable "objectStorageTier" is equal to "standard":

- title: "Equality Conditional Section"
  - ${myVcn}
      - ${objectStorageTier}
      - standard

In the next example, the "mySubnet" variable is visible if the value of the variable "useExistingVcn" is true:

  type: oci:core:subnet:id
    compartmentId: ${subnetCompartment}
    vcnId: ${myVcn}
  visible: ${useExistingVcn}

Groups have higher priority than the groups' constituent variables. For example, if a variable is visible within a group that is not visible, then the entire group is not visible.

Dynamically Prepopulating Variable Values

Use the schema to define variables that can be dynamically prepopulated in the Console.

Type (dynamic dropdown variable unless otherwise noted) Resource identifier Comments
oci:core:image:id Image OCID
oci:core:instanceshape:name Instance shape name
oci:core:ssh:publickey -- Surfaces a control for adding one or more public SSH keys by dropping files or pasting key values.
oci:core:subnet:id Subnet OCID
oci:core:vcn:id VCN OCID
oci:database:autonomouscontainerdatabase:id Autonomous container database OCID
oci:database:autonomousdatabase:id Autonomous database OCID
oci:database:database:id Database OCID
oci:database:dbhome:id DB home OCID
oci:database:dbsystem:id DB system OCID
oci:identity:availabilitydomain:name Availability domain name
oci:identity:compartment:id Compartment OCID
oci:identity:faultdomain:name Fault domain name
oci:identity:region:name Region name
oci:kms:vault:id Vault OCID

Dynamic prepopulation has two requirements to find the elements to prepopulate with: type and dependencies. Type describes the entity you're listing. Dependencies describe what is needed to be able to find the list.

The following example shows variables that can be prepopulated based on the VCN and compartment IDs:

   type: oci:identity:compartment:id
   type: oci:core:vcn:id
     compartmentId: ${vcnCompartment}
   type: oci:identity:compartment:id
   type: oci:core:subnet:id
     compartmentId: ${subnetCompartment}
     vcnId: ${myVcn}

The Console renders the dynamically prepopulated variables from this schema as follows.

This screenshot shows the result of dynamically pre-populated variables from the sample schema.

Example Configuration

The following example shows a Terraform configuration that is contained in a single file. This basic sample defines just one Terraform provider, one Oracle Cloud Infrastructure resource, and a set of variables.

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

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

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

More often, Terraform configurations consist of two or more files bundled together (for an uploaded configuration, the files would be bundled in a .zip file). To see more complex, multi-file Terraform configurations, explore the examples at the Oracle Cloud Infrastructure GitHub: terraform-provider-oci/docs/examples.