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 thevariables overview for more information about variable types, scope, and precedence. You can also set variable values specifically for each workspace run on the command line.

You can create and edit workspace-specific variables through:

• The HCP Terraform UI, as detailed below.
• The Variables API forworkspace-specific variables andvariable sets.
• Thetfe provider'stfe_variable resource, which can be more convenient for bulk management.

Permissions

You must haveRead variables permission to view the variables for a particular workspace and to view the variable sets in your organization. To create or edit workspace-specific variables within a workspace, you must haveRead and write variables for that workspace.

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

• A member of theowners team
• A member of a team withManage all projects
• A member of a team withManage all workspaces

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 variable sets project permissions
• Manage all projects organization permissions

Workspace run-specific variables

Terraform 1.1 and later lets you setTerraform 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 thevariable 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 withTF_VAR_. For example, if you declare a variable calledreplicas in your configuration, you could create a local environment variable calledTF_VAR_replicas and set it to a particular value. When you use theCLI Workflow, Terraform automatically identifies these environment variables and applies their values to the run.

Refer to thevariables 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 theVariables tab.

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

TheVariables page is not available for workspaces configured withLocalexecution mode. HCP Terraform does not evaluate workspace variables or variable sets in local execution mode.

Add a variable

To add a variable to a workspace:

1. Sign in toHCP Terraform or Terraform Enterprise and select the workspace you want to define a variable for.

2. Go to the workspaceVariables page and click+ Add variable in theWorkspace Variables section.

3. Choose a variable category (Terraform or environment), optionally mark the variable assensitive, and enter a variable key, value, and optional description. For Terraform variables only, you can check theHCL checkbox to enter a value in HashiCorp Configuration Language.

   Refer tovariable values and format for variable limits, allowable values, and formatting.

4. ClickSave 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 on a workspace:

1. Click the ellipses next to the variable you want to edit and selectEdit.
2. Make any desired changes and clickSave variable.

Delete a variable

To delete a variable from a workspace:

1. Click the ellipses next to the variable you want to delete and selectDelete.
2. ClickYes, delete variable to confirm your action.

Loading variables from files

You can setTerraform variable values for a workspace by providing any number offiles 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 inauto.tfvars orterraform.tfvars. You can apply other types of.tfvars filesusing the command line for each run.

Variable sets

Hands On: Try theManage Variable Sets in HCP Terraform tutorial tutorial.

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

HCP Terraform does not evaluate variable sets during Terraform runs for workspaces configured withLocalexecution mode.

Organizations or projects can own variable sets. To view variable sets, clickSettings in your organization or project, then clickVariable sets.

TheVariable 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. Sign in toHCP Terraform or Terraform Enterprise and navigate to theSettings page for your organization or project.

2. ClickVariable Sets.

3. ClickCreate variable set.

4. Choose a descriptiveName for the variable set. You can use any combination of numbers, letters, and characters.

5. Write an optionalDescription that tells other users about the purpose of the variable set and what it contains.

6. 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 or 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 alsoadd 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 alsoadd this variable set to their workspaces.

7. Add one or more variables: Click+ Add variable, choose a variable type (Terraform or environment), optionally mark the variable assensitive, and enter a variable name, value, and optional description. Then, clickSave variable.

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

8. ClickCreate variable set. HCP Terraform adds the new variable set to any specified workspaces and displays it on theVariable Sets page.

Edit variable sets

To edit or remove a variable set:

1. Sign in toHCP Terraform or Terraform Enterprise and navigate to theSettings page for your organization or project.

2. ClickVariable Sets.

3. Select the variable set you want to edit. That specific variable set page appears, where you can change the variable set settings. Refer tocreate 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. Sign in toHCP Terraform or Terraform Enterprise and navigate to theSettings page for your organization or project.

2. ClickVariable Sets.

3. SelectDelete variable set. Enter the variable set name and clickDelete variable set to confirm this action. HCP Terraform deletes the variable set. Runs within those workspaces can 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 theVariables tab. TheVariables page appears, showing all workspace-specific variables and variable sets applied to the workspace.

2. In theVariable sets section, clickApply Variable Set. Select the variable set you want to apply to your workspace, and clickApply 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 theVariables tab. TheVariables 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 selectRemove variable set.
3. ClickRemove 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 yellowOVERWRITTEN 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 tovariable 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 andterraform.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 tovariable 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 usingVault'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 variabledescriptions 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, includingsensitive 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 ifTF_LOG is set toTRACE.

Dynamic credentials

An alternative to passing static credentials for some providers is to usedynamic 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’sHCL 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 itsSensitive 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 theVariables page and are completely independent from any variable descriptions declared in Terraform CLI.