Variables

Terraform Cloud workspace variables let you customize configurations, modify Terraform's behavior, setup dynamic provider credentials, and store information like static 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.

Dynamic Credentials

You can configure dynamic credentials for certain providers using environment variables at the workspace level or using variable sets.

Dynamic credentials allows for using temporary per-run credentials and eliminates the need to manually rotate secrets.

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. Workspace-Scoped Variable Sets

Variables in workspace-scoped variable sets are only applied to a subset of workspaces in an organization.

When workspace-scoped 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 on the 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 is 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. Project-Scoped Variable Sets

Workspace-specific variables and workspace-scoped variable sets always take precedence over project-scoped variable sets that are applied to workspaces within a project.

Variables in project-scoped variable sets are only applied to the workspaces within the specified projects.

When project-scoped 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 project, Terraform Cloud uses any conflicting variables from A_Variable_Set. This is 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.

6. Global Variable Sets

Workspace and project-scoped 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.

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

8. 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: VAR1. For this run, VAR1 equals h, overwriting the value in A_Variable_Set.

• A_Variable_Set: KEY1. For this run, KEY1 equals x, overwriting the value in B_Variable_Set.

• B_Variable_Set: ACCESS_KEY, ACCESS_ID, and VAR2. For this run, VAR2 equals z, overwriting the value in C_Variable_Set.

• C_Variable_Set: KEY2. For this run, KEY2 equals c. This is a global variable set with no overwritten values.