Variables

Terraform Cloud workspace variables let you customize configurations, modify Terraform's behavior, and store information like provider credentials.

You can set variables specifically for each workspace or you can create variable sets to reuse the same variables across multiple workspaces. For example, you could define a variable set of provider credentials and automatically apply it to all of the workspaces using that provider. You can use the command line to specify variable values for each plan or apply. Otherwise, Terraform Cloud applies workspace variables to all runs within that workspace.

Types

You can create both environment variables and Terraform variables in Terraform Cloud.

Hands-on: Try the Create and Use a Variable Sets and Create Infrastructure tutorials to set environment and Terraform variables in Terraform Cloud.

Environment Variables

Terraform Cloud performs Terraform runs on disposable Linux worker VMs using a POSIX-compatible shell. Before running Terraform operations, Terraform Cloud uses the export command to populate the shell with environment variables.

Environment variables can store provider credentials and other data. Refer to your provider's Terraform Registry documentation for a full list of supported shell environment variables (e.g., authentication variables for AWS, Google Cloud Platform, and Azure). Environment variables can also modify Terraform's behavior. For example, TF_LOG enables detailed logs for debugging.

Parallelism

You can use the TFE_PARALLELISM environment variable when your infrastructure providers produce errors on concurrent operations or use non-standard rate limiting. The TFE_PARALLELISM variable sets the -parallelism=<N> flag for terraform plan and terraform apply (more about parallelism). Valid values are between 1 and 256, inclusive, and the default is 10. Terraform Cloud Agents do not support TFE_PARALLELISM, but you can specify flags as environment variables directly via TF_CLI_ARGS_name. In these cases, use TF_CLI_ARGS_plan="-parallelism=<N>" or TF_CLI_ARGS_apply="-parallelism=<N>" instead.

Terraform Variables

Terraform variables refer to input variables that define parameters without hardcoding them into the configuration. For example, you could create variables that let users specify the number and type of Amazon Web Services EC2 instances they want to provision with a Terraform module.

variable "instance_count" {
  description = "Number of instances to provision."
  type        = number
  default     = 2
}

You can then reference this variable in your configuration.

module "ec2_instances" {
  source = "./modules/aws-instance"

 instance_count = var.instance_count
 ## ...
}

If a required input variable is missing, Terraform plans in the workspace will fail and print an explanation in the log.

Scope

Each environment and Terraform variable can have one of the following scopes:

Precedence

Hands On: The Manage Multiple Variable Sets in Terraform Cloud tutorial shows how to manage multiple variable sets and demonstrates variable precedence.

There may be cases when a workspace contains conflicting variables of the same type with the same key. Terraform Cloud marks overwritten variables in the UI.

Terraform Cloud prioritizes and overwrites conflicting variables according to the following precedence:

1. Command Line Argument Variables

When using a CLI workflow, variables applied to a run with either -var or -var-file overwrite workspace-specific and variable set variables that have the same key.

2. Local Environment Variables Prefixed with TF_VAR_

When using a CLI workflow, local environment variables prefixed with TF_VAR_ (e.g., TF_VAR_replicas) overwrite workspace-specific, variable set, and .auto.tfvars file variables that have the same key.

3. Workspace-Specific Variables

Workspace-specific variables always overwrite variables from variable sets that have the same key. Refer to overwrite variables from variable sets for details.

4. Non-Global Variable Sets

Non-global variables are only applied to a subset of workspaces in an organization.

When non-global variable sets have conflicting variables, Terraform Cloud compares the variable set names and uses values from the variable set with lexical precedence. Terraform and Terraform Cloud operate on UTF-8 strings, and Terraform Cloud sorts variable set names based the on lexical order of Unicode code points.

For example, if you apply A_Variable_Set and B_Variable_Set to the same workspace, Terraform Cloud will use any conflicting variables from A_Variable_Set. This will be the case regardless of which variable set has been edited most recently; Terraform Cloud only considers the lexical ordering of variable set names when determining precedence.

5. Global Variable Sets

Non-global variable sets always take precedence over global variable sets that are applied to all workspaces within an organization. Terraform does not allow global variable sets to contain variables with the same key, so they cannot conflict.

6. *.auto.tfvars Variable Files

Variables in the Terraform Cloud workspace and variables provided through the command line always overwrite variables with the same key from files ending in .auto.tfvars.

7. terraform.tfvars Variable File

Variables in the .auto.tfvars files take precedence over variables in the terraform.tfvars file.

Precedence Example

Consider an example workspace that has the following variables applied:

When you trigger a run through the command line, Terraform Cloud applies the following variables:

• Run-Specific: replicas from the command line. That means replicas equals 9 for this run. Variables set from the command line take precedence over all other values, including the run-specific TF_VAR_replicas value set in your local environment.

• Workspace-Specific: ACCESS_KEY, ACCESS_ID, and VAR1. That means VAR1 equals h for this run, overwriting the value in A_Variable_Set.

• Variable Set A: KEY1. That means KEY1 equals x for this run, overwriting the value in B_Variable_Set.

• B_Variable_Set: VAR2. This is a global variable set, so A_Variable_Set takes precedence.