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:
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>%
:
set TF_LOG=trace
%TF_LOG%
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.
export TF_VAR_region=uksouth
export TF_VAR_regionlist='[uksouth,ukwest,useast2]'
export TF_VAR_tagmap='{ Environment = "dev", Project = "demo" }'
2) TF_LOG
For debugging purposes, this variable enables detailed logs in stderr.
export TF_LOG=trace
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:
export TF_LOG=off
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.
export TF_LOG_PATH=./terraform.log
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.
export TF_INPUT=0
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.
export TF_CLI_ARGS="-state=terraform.tfstate -debug"
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:
export TF_CLI_ARGS_plan="-refresh=false"
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.
export TF_DATA_DIR=./mydirectory/terraform
7) TF_WORKSPACE
This is the environment variable equivalent of setting your workspace using:
terraform workspace select my_workspace_name
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:
export TF_WORKSPACE=my_workspace_name
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.
export TF_IN_AUTOMATION=true
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.
export TF_CLI_CONFIG_FILE=”./mydirectory/.terraformrc-custom”
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.
export TF_IGNORE=trace
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.
export TF_REGISTRY_DISCOVERY_RETRY=10
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.
export TF_REGISTRY_CLIENT_TIMEOUT=30
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.
Terraform Management Made Easy
Spacelift effectively manages Terraform state, more complex workflows, supports policy as code, programmatic configuration, context sharing, drift detection, resource visualization and includes many more features.