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.
You can create both environment variables and Terraform variables in HCP Terraform.
Environment variablesHands-on: Try the Create and Use a Variable Sets and Create Infrastructure tutorials to set environment and Terraform variables in HCP Terraform.
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.
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.
Warning: We recommend reading and understanding Terraform parallelism prior to setting TFE_PARALLELISM
. You can also contact HashiCorp support for direct advice.
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 variablesTerraform 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.
Each environment and Terraform variable can have one of the following scopes:
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.
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 setsIf 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 organizationIf 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 organizationIf 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 projectIf 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 projectIf 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 variablesWhen 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.
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.
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 projectVariables 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 projectVariables 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 organizationVariables 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.
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.
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
.
terraform.tfvars
variable file
Variables in the .auto.tfvars
files take precedence over variables in the terraform.tfvars
file.
Note
Although HCP Terraform uses variables from `terraform.tfvars`, Terraform Enterprise currently ignores this file.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.
Consider an example workspace that has the following different kinds of variables and variable sets:
Source Priority Ownership Scope Priority global variable set true organization global Priority organization-owned project-scoped variable set true organization project Priority organization-owned workspace-scoped variable set true organization workspace Priority project-owned project-scoped variable set true project project Priority project-owned workspace-scoped variable set true project workspace Command line argument N/A N/A run Local environment variable N/A N/A workspace Workspace-specific variable N/A N/A workspace Project-owned workspace-scoped variable set false project workspace Project-owned project-scoped variable set false project project Organization-owned workspace-scoped variable set false organization workspace Organization-owned project-scoped variable set false organization project Global variable set false organization globalIf these variables and variable sets had the following variables applied:
Source (priority/ownership/scope) Region Var1 Replicas Priority global variable setus-east-1
Priority organization-owned project-scoped variable set us-east-2
Priority organization-owned workspace-scoped variable set us-west-1
Priority project-owned project-scoped variable set eu-east-2
Priority project-owned workspace-scoped variable set eu-west-1
Command line argument us-west-2
9
Local environment variable 8
Workspace-specific variable h
1
Project-owned workspace-scoped variable set y
2
Project-owned project-scoped variable set 4
Organization-owned workspace-scoped variable set z
3
Organization-owned project-scoped variable set 5
Global variable set 6
When you trigger a run through the command line, these are the final values HCP Terraform assigns to each variable:
Variable Value Regionus-east-1
Var1 h
Replicas 9
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4