Terraform Configurations for Resource Manager
Review requirements and recommendations for Terraform configurations used with Resource Manager. Use Terraform and Resource Manager to install, configure, and manage resources using the infrastructure-as-code model.
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.
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 theworkingDirectory
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.
Modules
Resource Manager supports the following Terraform module sources:
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.
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 the 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's contained in a single file. This basic sample defines only 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 Terraform configurations that include multiple files, explore the examples at Terraform Oracle Cloud Infrastructure Provider 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 (prebuilt Terraform configuration from Oracle or a private template)
- Existing compartment (Resource Discovery)
Schema Documents
Schema documents are recommended for Terraform configurations when using Resource Manager. See Extend Console Pages Using Schema Documents.