» Variables

Terraform Cloud workspace variables let you customize configurations, customize Terraform's behavior, and store information like provider credentials. Variables apply to all workspace runs, and you must have read variables permission to view the variables for a particular workspace.

Once you have the proper read and write variables permission, you can create and edit workspace variables in the UI as shown below, with the Variables API, or with the tfe provider tfe_variable resource.

» Variable Types

You can set both Terraform variables and environment variables in Terraform Cloud.

Terraform variables refer to input variables that define parameters without hardcoding them into the configuration. For example, you could create a variable that lets users specify the number and type of AWS EC2 instances they want to provision with a Terraform module.

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 customize Terraform's behavior. For example, TF_LOG enables detailed logs for debugging.

Hands-on: This Create Infrastructure tutorial on HashiCorp Learn shows how to set both Terraform variables and provider credential environment variables.

» Loading Variables from Files

If a workspace is configured to use Terraform 0.10.0 or later, you can commit any number of *.auto.tfvars files to provide default variable values. Terraform will automatically load variables from those files.

If any automatically loaded variables have the same names as variables specified in the Terraform Cloud workspace, the workspace's values will override the automatic values.

You can also use the optional Terraform Cloud Provider to update a workspace's variables. This has the same effect as managing workspace variables manually or via the API, but can be more convenient for large numbers of complex variables.

» Variable Limits

The following limits apply to variables:

» Managing Variables in the UI

To view and manage a workspace's variables, navigate to that workspace and click the "Variables" navigation link at the top.

The variables page has separate lists of Terraform variables and environment variables:

To edit a variable, click one of its text fields or its pencil (edit) icon to reveal the editing controls. Make any desired changes to the variable's name, value, description, and settings, then click the "Save Variable" button.

To add a variable, click the "+ Add Variable" button, enter a name, value, optional description, and save.

To delete a variable, click its "🗑" (trash can) icon, then confirm your decision in the dialog box that appears.

You can edit one variable at a time, and must save or cancel your current edits before editing other variables in the list.

» Multi-line Values

The text fields for variable values can handle multi-line text (typed or pasted) without any special effort.

» HCL Values

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

HCL can be used for Terraform variables, but not for environment variables. The HCL code you enter for values is interpreted by the same Terraform version that performs runs in the workspace. (See How Terraform Cloud Uses Variables below.)

» Sensitive Values

Terraform often needs cloud provider credentials and other sensitive information that shouldn't 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 (visible when editing).

Marking a variable as sensitive prevents anybody (including you) from viewing its value in the variables section of the workspace in Terraform Cloud's UI or with its Variables API endpoint.

Users with permission to read and write variables can set new values for sensitive variables. No other attribute of a sensitive variable can be modified. To update other attributes, delete the variable and create a new variable to replace it.

» Looking Up Variable Names

Terraform Cloud can't automatically discover variable names from a workspace's Terraform code. You must discover the necessary variable names by reading code or documentation, then enter them manually.

If a required input variable is missing, Terraform plans in the workspace will fail and print an explanation in the log.

» Descriptions

Variable descriptions help distinguish between similarly named variables. These optional fields are only shown on this "Variables" page and are completely independent from any variable descriptions declared in Terraform CLI.

» How Terraform Cloud Uses Variables

» Terraform Variables

Terraform Cloud passes variables to Terraform by writing a terraform.tfvars file and passing the -var-file=terraform.tfvars option to the Terraform command.

Do not commit a file named terraform.tfvars to version control, since Terraform Cloud will overwrite it. (Note that you shouldn't check in terraform.tfvars even when running Terraform solely on the command line.)

» Environment Variables

Terraform Cloud performs Terraform runs on disposable Linux worker VMs using a POSIX-compatible shell. Before running Terraform, Terraform Cloud populates the shell with environment variables using the export command.

» Special Environment Variables

Terraform Cloud uses some special environment variables to control dangerous or rarely used run behaviors.

• TFE_PARALLELISM — If present, Terraform Cloud uses this to set terraform plan and terraform apply's -parallelism=<N> flag (more info). Valid values are between 1 and 256, inclusive; the default is 10. This is rarely necessary, but can fix problems with infrastructure providers that error on concurrent operations or use non-standard rate limiting. We recommend talking to HashiCorp support before using this.

» Secure Storage of Variables

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.

Descriptions are not encrypted. Please be careful with the information you save in a variable description.