Workspace variables

HCP Terraform 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, HCP Terraform applies workspace variables to all runs within that workspace.

Types

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

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

Environment variables

HCP Terraform performs Terraform runs on disposable Linux worker VMs using a POSIX-compatible shell. Before running Terraform operations, HCP Terraform 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. HCP Terraform 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:

Variable set ownership

Projects and organizations can both own variable sets. The owner of a variable set can determine the precedence of that set.

Use organization-owned variable sets to share variables across multiple projects. Managing organization-owned variable sets requires a higher permission level because you can apply these sets to any project in your organization.

Use project-owned variable sets to share variables across multiple workspaces within a single project. Project-owned variable sets only require permissions on the project itself, rather than organization-level permissions.

Refer to Manage variable sets for more details on variable set permissions.

Precedence

Hands On: The Manage Multiple Variable Sets in HCP Terraform 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. HCP Terraform marks overwritten variables in the UI.

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

1. Priority global variable sets

If prioritized, variables in a global variable set have precedence over all other variables with the same key.

2. Priority project-scoped variable set owned by an organization

If prioritized, variables in a priority project-scoped variable set have precedence over variables with the same key set at a more specific scope. Prioritized variables sets owned by organizations take precedence over priority variable sets owned by projects.

3. Priority workspace-scoped variable set owned by an organization

If prioritized, variables in an organization-owned variable set scoped to a workspace have precedence over variables with the same key set at a more specific scope. Prioritized variables sets owned by organizations take precedence over sets owned by projects.

4. Priority project-scoped variable set owned by a project

If prioritized, variables in a priority project-scoped variable set have precedence over variables with the same key set at a more specific scope.

5. Priority workspace-scoped variable set owned by a project

If prioritized, variables in a priority workspace-scoped variable set have precedence over variables with the same key set at a more specific scope.

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

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

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

9. Workspace-scoped variable owned by a project

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

When workspace-scoped variable sets have conflicting variables, HCP Terraform compares the variable set names and uses values from the variable set with lexical precedence. Terraform and HCP Terraform operate on UTF-8 strings, and HCP Terraform 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, HCP Terraform will use any conflicting variables from A_Variable_Set. This is the case regardless of which variable set has been edited most recently. HCP Terraform only considers the lexical ordering of variable set names when determining precedence.

Variables sets scoped to workspaces that are owned by projects take precedence over sets with the same scope that are owned by organizations.

10. Project-scoped variable set owned by 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, HCP Terraform compares the variable set names and uses values from the variable set with lexical precedence. Terraform and HCP Terraform operate on UTF-8 strings, and HCP Terraform 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, HCP Terraform uses any conflicting variables from A_Variable_Set. This is the case regardless of which variable set has been edited most recently. HCP Terraform only considers the lexical ordering of variable set names when determining precedence.

Variables sets owned by projects take precedence over those owned by organizations.

11. Workspace-scoped variable set owned by an organization

Variables in workspace-scoped variable sets are only applied to the specified workspaces in an organization.

When workspace-scoped variable sets have conflicting variables, HCP Terraform compares the variable set names and uses values from the variable set with lexical precedence. Terraform and HCP Terraform operate on UTF-8 strings, and HCP Terraform 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, HCP Terraform will use any conflicting variables from A_Variable_Set. This is the case regardless of which variable set has been edited most recently. HCP Terraform only considers the lexical ordering of variable set names when determining precedence.

12. Project-scoped variable set owned by an organization

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

When project-scoped variable sets have conflicting variables, HCP Terraform compares the variable set names and uses values from the variable set with lexical precedence. Terraform and HCP Terraform operate on UTF-8 strings, and HCP Terraform 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, HCP Terraform uses any conflicting variables from A_Variable_Set. This is the case regardless of which variable set has been edited most recently. HCP Terraform only considers the lexical ordering of variable set names when determining precedence.

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

14. *.auto.tfvars variable files

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

15. terraform.tfvars variable file

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

Precedence with priority variable sets

You can select to prioritize all values of the variables in a variable set. When a variable set is priority, the values take precedence over any variables with the same key set at a more specific scope.

For example, variables in a priority global variable set would take precedence over all variables with the same key.

If two priority variable sets with the same scope and ownership include the same variable key, HCP Terraform will determine precedence by the alphabetical order of the variable sets' names.

While a priority variable set can enforce that Terraform variables use designated values, it does not guarantee that the configuration uses the variable. A user can still directly modify the Terraform configuration to remove usage of a variable and replace it with a hard-coded value. For stricter enforcement, we recommend using policy checks or run tasks.

Precedence example

Consider an example workspace that has the following different kinds of variables and variable sets:

If these variables and variable sets had the following variables applied:

When you trigger a run through the command line, these are the final values HCP Terraform assigns to each variable: