You can set variables specifically for each workspace or you can create variable sets to reuse the same variables across multiple workspaces. Refer to the variables overview documentation for more information about variable types, scope, and precedence. You can also set variable values specifically for each run on the command line.
You can create and edit workspace-specific variables through:
- The Terraform Cloud UI, as detailed below.
- The Variables API for workspace-specific variables and variable sets.
tfe_variableresource, which can be more convenient for bulk management.
You must have
read variables permission to view the variables for a particular workspace and to view the variable sets in your organization.
To create new variable sets and apply them to workspaces, you must be part of a team with manage workspaces permissions. To create and edit workspace-specific variables within a workspace, you must have read and write variables for that workspace.
Terraform 1.1 and later lets you set Terraform variable values for a particular plan or apply on the command line. These variable values will overwrite workspace-specific and variable set variables with the same key. Refer to the variable precedence documentation for more details.
You can set run-specific Terraform variable values by:
-var-filearguments. For example:
terraform apply -var="key=value" -var-file="testing.tfvars"
Creating local environment variables prefixed with
TF_VAR_. For example, if you declare a variable called
replicasin your configuration, you could create a local environment variable called
TF_VAR_replicasand set it to a particular value. When you use the CLI Workflow, Terraform automatically identifies these environment variables and applies their values to the run.
Refer to the variables on the command line documentation for more details and examples.
To view and manage a workspace's variables, go to the workspace and click the Variables tab.
The Variables page appears, showing all workspace-specific variables and variable sets applied to the workspace. This is where you can add, edit, and delete workspace-specific variables. You can also apply and remove variable sets from the workspace.
To add a variable:
Go to the workspace Variables page and click + Add variable in the Workspace Variables section.
Choose a variable category (Terraform or environment), optionally mark the variable as sensitive, and enter a variable key, value, and optional description. For Terraform variables only, you can check the HCL checkbox to enter a value in HashiCorp Configuration Language.
Refer to variable values and format for variable limits, allowable values, and formatting.
Click Save variable. The variable now appears in the list of the workspace's variables and Terraform Cloud will apply it to runs.
To edit a variable:
- Click the ellipses next to the variable you want to edit and select Edit.
- Make any desired changes and click Save variable.
To delete a variable:
- Click the ellipses next to the variable you want to delete and select Delete.
- Click Yes, delete variable to confirm your action.
You can set Terraform variable values by providing any number of files ending in
.auto.tfvars to workspaces that use Terraform 0.10.0 or later. When you trigger a run, Terraform automatically loads and uses the variables defined in these files. If any variable from the workspace has the same key as a variable in the file, the workspace variable overwrites variable from the file.
You can only do this with files ending in
terraform.tfvars. You can apply other types of
.tfvars files using the command line for each run.
Note: Terraform Cloud loads variables from files ending in
auto.tfvars for each Terraform run, but does not automatically persist those variables to the Terraform Cloud workspace or display them in the Variables section of the workspace UI.
Hands On: Try the Manage Variable Sets in Terraform Cloud tutorial tutorial.
To view variable sets for your organization, click Settings, then click Variable sets.
The Variable sets page appears, listing all of the organization's variable sets. Click on a variable set to open it and review details about its variables and scoping.
To create a variable set:
Go to the Variable Sets page for your organization and click Create variable set. The Create a new variable set page appears.
Choose a descriptive Name for the variable set. You can use any combination of numbers, letters, and characters.
Write an optional Description that tells other users about the purpose of the variable set and what it contains.
Choose a variable set scope:
- Apply globally: Terraform Cloud will automatically apply this global variable set to all existing and future workspaces.
- Apply to specific projects and workspaces: Use the text fields to search for and select workspaces and/or projects to apply this variable set to. This affects all current and future workspaces for any selected projects. After creation, users can also add this variable set to their workspaces.
Add one or more variables: Click + Add variable, choose a variable type (Terraform or environment), optionally mark the variable as sensitive, and enter a variable name, value, and optional description. Then, click Save variable.
Refer to variable values and format for variable limits, allowable values, and formatting.
Note: Terraform Cloud will error if you try to declare variables with the same key in multiple global variable sets.
Click Create variable set. Terraform Cloud adds the new variable set to any specified workspaces and displays it on the Variable Sets page.
To edit or remove a variable set:
- Go to the organization's settings and then click Variable Sets. The Variable sets page appears.
- Click the variable set you want to edit. That specific variable set page appears, where you can change the variable set settings. Refer to create variable sets for details.
Deleting a variable set can be a disruptive action, especially if the variables are required to execute runs. We recommend informing organization and workspace owners before removing a variable set.
To delete a variable set:
- Click Settings, then click Variable Sets. The Variable sets page appears.
- Select Delete variable set. Enter the variable set name and click Delete variable set to confirm this action. Terraform Cloud deletes the variable set and removes it from all workspaces. Runs within those workspaces will no longer use the variables from the variable set.
To apply a variable set to a specific workspace:
Navigate to the workspace and click the Variables tab. The Variables page appears, showing all workspace-specific variables and variable sets applied to the workspace.
In the Variable sets section, click Apply Variable Set. Select the variable set you want to apply to your workspace, and click Apply variable set. The variable set appears in the workspace's variable sets list and Terraform Cloud will now apply the variables to runs.
To remove a variable set from within a workspace:
- Navigate to the workspace and click the Variables tab. The Variables page appears, showing all workspace-specific variables and variable sets applied to the workspace.
- Click the ellipses button next to the variable set and select Remove variable set.
- Click Remove variable set in the dialog box. Terraform Cloud removes the variable set from this workspace, but it remains available to other workspaces in the organization.
You can overwrite variables defined in variable sets within a workspace. For example, you may want to use a different set of provider credentials in a specific workspace.
To overwrite a variable from a variable set, create a new workspace-specific variable of the same type with the same key. Terraform Cloud marks any variables that you overwrite with a yellow OVERWRITTEN flag. When you click the overwritten variable, Terraform Cloud highlights the variable it will use during runs.
Variables within a variable set can also automatically overwrite variables with the same key in other variable sets applied to the same workspace. Though variable sets are created for the organization, these overwrites occur within each workspace. Refer to variable precedence for more details.
The values in priority variable sets overwrite any variables with the same key set at more specific scopes. This includes variables set using command line flags, or through
It is still possible for a user to directly modify the Terraform configuration and remove usage of a variable and replace it with a hard coded value. For stricter enforcement, we recommend using policy checks or run tasks. Refer to variable precedence for more details.
The limits, allowable values, and required format are the same for both workspace-specific variables and variable sets.
Terraform Cloud encrypts all variable values securely using Vault's transit backend prior to saving them. This ensures that no out-of-band party can read these values without proper authorization. However, Terraform Cloud stores variable descriptions in plain text, so be careful with the information you save in a variable description.
We also recommend passing credentials to Terraform as environment variables instead of Terraform variables when possible, since Terraform runs receive the full text of all Terraform variable values, including sensitive ones. It may print the values in logs and state files if the configuration sends the value to an output or a resource parameter. Sentinel mocks downloaded from runs will also contain the sensitive values of Terraform variables.
Although Terraform cloud does not store environment variables in state, it can include them in log files if
TF_LOG is set to
An alternative to passing static credentials for some providers is to use dynamic credentials.
Dynamic credentials allows for using temporary per-run credentials and eliminates the need to manually rotate secrets.
The following limits apply to variables:
You can type or paste multi-line text into variable value text fields.
You can use HCL for Terraform variables, but not for environment variables. The same Terraform version that performs runs in the workspace will interpret the HCL.
Variable values are strings by default. To enter list or map values, click the variable’s HCL checkbox (visible when editing) and enter the value with the same HCL syntax you would use when writing Terraform code. For example:
us-east-1 = "image-1234"
us-west-2 = "image-4567"
Warning: There are some cases when even sensitive variables are included in logs and state files. Refer to security for more information.
Terraform often needs cloud provider credentials and other sensitive information that should not be widely available within your organization. To protect these secrets, you can mark any Terraform or environment variable as sensitive data by clicking its Sensitive checkbox that is visible during editing.
Marking a variable as sensitive makes it write-only and prevents all users (including you) from viewing its value in the Terraform Cloud UI or reading it through the Variables API endpoint.
Users with permission to read and write variables can set new values for sensitive variables, but other attributes of a sensitive variable cannot be modified. To update other attributes, delete the variable and create a new variable to replace it.
Warning: Variable descriptions are not encrypted, so do not include any sensitive information.
Variable descriptions are optional, and help distinguish between similarly named variables. They are only shown on the Variables page and are completely independent from any variable descriptions declared in Terraform CLI.