Manage variables and variable sets

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 HCP Terraform 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, edit, and apply organization-owned variable sets, you must be part of a team with Manage all workspaces or Manage all projects permissions. To create, edit, or apply project-owned variable sets, you must be part of a team with one of the following:

• Write project permissions
• Maintain project permissions
• Admin project permissions
• Manage all projects organization 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"

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

The Variables page is not available for workspaces configured with Local execution mode. HCP Terraform does not evaluate workspace variables or variable sets in local execution mode.

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 HCP Terraform 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 or terraform.tfvars. You can apply other types of .tfvars files using the command line for each run.

Variable Sets

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

Variable sets are reusable collections of variables that you can apply to multiple workspaces. You can be create variable sets under an organization or a project. Whether the variable set is owned by an organization or a project determines what permissions are required to manage the variable set.

To create, update, or delete organization-owned variable sets, you must be one of the following:

• A member of the owners Team
• A member of a team with Manage all projects
• A member of a team with Manage all workspaces

You can only apply project-owned variable sets to workspaces within the project. To create, update, apply, or delete project-owned variable sets, you must be part of a team with one of the following:

• Write project permissions
• Maintain project permissions
• Admin project permissions
• Manage all projects organization permissions

HCP Terraform does not evaluate variable sets during Terraform runs for workspaces configured with Local execution mode.

Organizations or projects can own variable sets. To view variable sets, click Settings in your organization or project, then click Variable sets.

The Variable sets page lists all of the organization's or project'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 or project 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:

   • Organization-owned
     • Apply globally: HCP Terraform automatically applies 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 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.
   • Project-owned
     • Apply to the entire project: HCP Terraform automatically applies this variable set to all existing and future workspaces in the project.
     • Apply to specific workspaces in the project: Use the text fields to search for and select workspaces to apply this variable set to. After creation, users can also add this variable set to their workspaces.

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: HCP Terraform will error if you try to declare variables with the same key in multiple global variable sets.

6. Click Create variable set. HCP Terraform 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 or project'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, project, 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. HCP Terraform 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 HCP Terraform 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. HCP Terraform 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. HCP Terraform marks any variables that you overwrite with a yellow OVERWRITTEN flag. When you click the overwritten variable, HCP Terraform 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 or project, these overwrites occur within each workspace. Refer to variable precedence for more details.

Priority Variable Sets

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.*auto.tfvars and terraform.tfvars files.

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.

Variable Values and Format

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

Security

HCP Terraform 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, HCP Terraform 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 HCP Terraform does not store environment variables in state, it can include them in log files if TF_LOG is set to TRACE.

Dynamic Credentials

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.

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