Oracle Cloud Infrastructure Documentation

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.

Warning

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. All other fields, such as userid or fingerprint, are optional.

File Structure

Resource Manager requires the following Terraform configuration file (.zip) structure for the 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 of the .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.

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 GitHub and include the relevant portion in a subdirectory in your .zip file.
  • Reference the module using a local path. For more information, see Local Paths.

Variables

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 (.zip) file. (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.

num_nodes:
  type: enum
  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).

url:
  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"
groupings:
  - title: "Create A VCN"
    variables:
    - region
    - compartment_ocid
 
variables:
  region:
    type: oci:identity:region:name
    title: Region
    description: The region in which to create all resources
    required: true
 
  compartment_ocid:
    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"
  variables:
  - ${myVcn}
  visible:
    eq:
      - ${objectStorageTier}
      - standard

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

mySubnet:
  type: oci:core:subnet:id
  dependsOn:
    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. 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:

vcnCompartment:
   type: oci:identity:compartment:id
 
myVcn:
   type: oci:core:vcn:id
   dependsOn:
     compartmentId: ${vcnCompartment}
 
subnetCompartment:
   type: oci:identity:compartment:id
 
mySubnet:
   type: oci:core:subnet:id
   dependsOn:
     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 = "10.0.0.0/16"
  dns_label = "vcn1"
  compartment_id = "${var.compartment_ocid}"
  display_name = "vcn1"
}

More often, Terraform configurations consist of two or more files bundled together and uploaded 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.