Terraform Environment Variables – How to Use Them

In this article, we will look at what Terraform environment variables are, when and why you would use them, and how to set them with examples of each! Let’s jump straight in!

We will cover:

1. What is a Terraform environment variable?
2. How to use different Terraform Environment Variables

Terraform refers to a number of environment variables to customize various aspects of its behavior. These variables are set within the environment in which Terraform is running. They provide configuration information to Terraform without having to hardcode it into the configuration files.

Environment variables can be set on the command line, within scripts, or by using the operating system’s environment variable settings.

For reference, using the GUI in a Windows OS, they can be set Under System Properties → Advanced → Environment Variables → New system variable.

On the command line in a Windows system, you can use the SET command as an equivalent to the export on Linux based system, and view the current value using %<variable name>%:

In Spacelift, environment variables can be defined directly on stacks and modules, as well as on contexts attached to those. Read more about using environment variables in our documentation.

The following examples in this article use the export command which is native to Linux of MacOS (but is not available on a Windows OS).

1) TF_VAR_name

As well as defining variables using a .tfvars files and directly on the command line, this environment variable can be used to values for variables in your Terraform configuration.

Note that defining variables this way is a fallback if variable values are not found elsewhere.

The variable name you want to set the value for should be in the format _name, e.g., for a variable named region, you would specify TF_VAR_region as the variable name. This can be useful when running Terraform in automation, or when running a sequence of Terraform commands in succession with the same variables.

2) TF_LOG

For debugging purposes, this variable enables detailed logs in stderr.

You can set TF_LOG to one of the log levels (in order of decreasing verbosity) TRACE, DEBUG, INFO, WARN or ERROR to change the verbosity of the logs.

Setting TF_LOG to JSON outputs logs at the TRACE level or higher, and uses a parseable JSON encoding as the formatting.

You can turn off logging when you have finished debugging:

3) TF_LOG_PATH

When TF_LOG is set, you can also use the TF_LOG_PATH variable to set the location where the log should persist its output to. The below example logs to a file called terraform.log in the local directory.

4) TF_INPUT

This is useful when you want to replicate the -input=false flag behavior from the command line in an environment variable by specifying a value of 0 or FALSE. This disables prompts for input for variables that have not been specified.

5) TF_CLI_ARGS and TF_CLI_ARGS_name

TF_CLI_ARGS is used to specify additional arguments to the command line. Arguments are inserted directly after the subcommand (such as plan) and before any flags specified directly on the command line. This behavior ensures that flags on the command line take precedence over environment variables.

For example, to run Terraform plan with the debug mode enabled and specify the location of the state file, you can set the TF_CLI_ARGS variable to -state=terraform.tfstate -debug, which will pass the -state and -debug options to Terraform CLI.

When the terraform plan command is run, Terraform will use the state file specified and output additional debugging information to the console.

A named command can also be specified, which will only affect that command. This is done using the TF_CLI_ARGS_name variable.

For example, to specify that only plans never refresh:

6) TF_DATA_DIR

By default, Terraform working data is written into a .terraform subdirectory of the current directory. To change the path that this data is held in, the TF_DATA_DIR can be used (useful in rare cases where the working directory is not writeable).

In automation, this must be set at each stage of the Terraform workflow for each command, e.g. terraform init , terraform plan , terraform apply — as each command will need to reference the working directory if it is changed from the default to find modules and configuration information.

7) TF_WORKSPACE

This is the environment variable equivalent of setting your workspace using:

This is useful in automation as it overrides any workspace selection but is not recommended when using Terraform interactively as it is easy to set and forget, which might cause inadvertent changes to the wrong Terraform state.

For example:

8) TF_IN_AUTOMATION

This is a variable used to set a purely cosmetic change to Terraform’s human-readable output, which prevents it from suggesting specific commands to run next after one command has been completed.

In automation, this wouldn’t be possible as the environment is non-interactive, so removing these suggestions makes the output less confusing. To use it, set it to any non-empty value.

9) TF_CLI_CONFIG_FILE

Used to specify the location of the Terraform CLI configuration file. This is a file specified as .terraformrc or terraform.rc which configures per-user settings for CLI behaviors, which apply across all Terraform working directories.

10) TF_IGNORE

When debugging large repositories with .terraformignore files, this variable can be used to get Terraform to output debug messages to display ignored files and folders. It should be set to trace .

Files listed in a .terraformignore plan are simply a list of files that should not be considered as part of the configuration to speed up deployments when a large number of file exist.

11) TF_REGISTRY_DISCOVERY_RETRY

Set TF_REGISTRY_DISCOVERY_RETRY to configure the max number of request retries, the remote registry client will attempt for client connection errors or 500-range responses that are safe to retry.

This example sets the value of TF_REGISTRY_DISCOVERY_RETRY to ten, which means that registry discovery operations will be retried up to ten times before failing.

12) TF_REGISTRY_CLIENT_TIMEOUT

This variable can be configured to increase the default client timeout to the remote registry during extraneous circumstances.

The default client timeout for requests to the remote registry is 10s.

Terraform environment variables provide a flexible and secure way to manage configuration information, making it easier to use Terraform in a variety of environments and scenarios.

No environment variables are required when using Terraform, but they can be helpful to change some of Terraform’s default behaviors in unusual situations.

We encourage you also to explore how Spacelift makes it easy to work with Terraform. If you need any help managing your Terraform infrastructure, building more complex workflows based on Terraform, and managing AWS credentials per run, instead of using a static pair on your local machine, Spacelift is a fantastic tool for this.

Note: New versions of Terraform will be placed under the BUSL license, but everything created before version 1.5.x stays open-source. OpenTofu is an open-source version of Terraform that will expand on Terraform’s existing concepts and offerings. It is a viable alternative to HashiCorp’s Terraform, being forked from Terraform version 1.5.6. OpenTofu retained all the features and functionalities that had made Terraform popular among developers while also introducing improvements and enhancements. OpenTofu works with your existing Terraform state file, so you won’t have any issues when you are migrating to it.