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 Authoring Configurations. For instructions on using configurations with stacks and jobs, see Managing Stacks and Jobs.

For Terraform configuration sources supported with Resource Manager, see Where to Store Your Terraform Configurations.

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 template.

Caution

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

Requirements

Terraform configuration files used with Resource Manager must meet the following requirements.

Terraform Provider

When using Resource Manager, the region field in the provider "oci" block is the only required field. For more information about defining providers, see Configuration File Requirements.

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 Authoring 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.

Variables

We recommend using a schema document with your Terraform configuration to facilitate user entry in the Oracle Cloud Infrastructure Console.

Resource Manager does not have requirements for variables in Terraform configurations. Resource Manager supports the native Terraform behavior for handling variables. Terraform sets variables from your variable definitions that use supported type constraints. When you run a job, the stack's variable values are added as environment variables in the Resource Manager Terraform host. For example, the VCN specified in a stack for a given VCN variable is added as an environment variable.

Note

When defined in the Terraform configuration, the following variables automatically prepopulate with values on the Console pages used to create and edit the stack. The stack's values are used when you select the Terraform actions Plan, Apply, and Destroy.

  • tenancy_ocid (tenancy OCID)
  • compartment_ocid (compartment OCID)
  • region (region)
  • current_user_ocid (OCID of the current user)

Third-party Provider Configuration

Reference third-party Terraform providers in Terraform configurations used with Resource Manager.

By default, new Resource Manager stacks fetch third-party providers from Terraform Registry. (Unless updated, certain older stacks fetch from Resource Manager). Custom providers are also available for new and updated stacks.

As with any provider configuration, we recommend specifying versions. Dependency lock files are automatically managed for new and updated stacks. Providers are updated within the version constraints of your Terraform configuration. For instructions, see Retrieving the Latest Providers.

For more information about adding providers to Terraform configurations, see Provider Configuration.

Example Terraform Configuration for Resource Manager

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 (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.

Where to Store Your Terraform Configurations

When creating a stack with Resource Manager, you can select your Terraform configuration from the following sources.

  • Local .zip file
  • Local folder
  • Object Storage bucket

    The most recent contents of the bucket are automatically used by any job running on the associated stack.

  • Source code control system, such as Git

    The latest version of your configuration is automatically used by any job running on the associated stack.

  • Template (pre-built Terraform configuration from Oracle or a private template)
  • Existing compartment (Resource Discovery)