Managing Variables

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.
• The tfe provider's tfe_variable resource, which can be more convenient for bulk management.

Permissions

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.

Run-Specific Variables

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:

• Specifying -var and -var-file arguments. For example:

  terraform apply -var="key=value" -var-file="testing.tfvars"
  

  Copy

• Creating local environment variables prefixed with TF_VAR_. For example, if you declare a variable called replicas in your configuration, you could create a local environment variable called TF_VAR_replicas and 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.

Workspace-Specific Variables

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.

Add a Variable

To add a variable:

1. Go to the workspace Variables page and click + Add variable in the Workspace Variables section.

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

3. Click Save variable. The variable now appears in the list of the workspace's variables and Terraform Cloud will apply it to runs.

Edit a Variable

To edit a variable:

1. Click the ellipses next to the variable you want to edit and select Edit.
2. Make any desired changes and click Save variable.

Delete a Variable

To delete a variable:

1. Click the ellipses next to the variable you want to delete and select Delete.
2. Click Yes, delete variable to confirm your action.

Loading Variables from Files

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 auto.tfvars; Terraform Cloud does not automatically load variables from terraform.tfvars. You can only apply other types of .tfvars files on the command line for each run.

Variable Sets

Hands On: Try the Manage Variable Sets in Terraform Cloud tutorial tutorial.

Only members of the Owners Team or members of a team with the Manage Workspaces permission can create, update, and delete variable sets.

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.

Create Variable Sets

To create a variable set:

1. Go to the Variable Sets page for your organization and click Create variable set. The Create a new variable set page appears.

2. Choose a descriptive Name for the variable set. You can use any combination of numbers, letters, and characters.

3. Write an optional Description that tells other users about the purpose of the variable set and what it contains.

4. Choose a variable set scope:

   • Apply to all workspaces in this organization: Terraform Cloud will automatically apply this global variable set to all existing and future workspaces.
   • Apply to specific workspaces: Use the text field to search for and select one or more workspaces to apply this variable set to. Users will also be able to add this variable set to their workspaces after creation.

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

6. Click Create variable set. Terraform Cloud adds the new variable set to any specified workspaces and displays it on the Variable Sets page.

Edit Variable Sets

To edit or remove a variable set:

1. Go to the organization's settings and then click Variable Sets. The Variable sets page appears.
2. 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.

Delete Variable Sets

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:

1. Click Settings, then click Variable Sets. The Variable sets page appears.
2. 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.

Apply or Remove Variable Sets From Inside a Workspace

To apply a variable set to a specific workspace:

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

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

1. 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.
2. Click the ellipses button next to the variable set and select Remove variable set.
3. 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.

Overwrite Variable Sets

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.

Variable Values and Format

The limits, allowable values, and required format are the same for both workspace-specific variables and variable sets.

Security

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

Character Limits

The following limits apply to variables:

Multi-Line Text

You can type or paste multi-line text into variable value text fields.

HashiCorp Configuration Language (HCL)

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"
}

Sensitive Values

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.

Variable Description

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.