mirror of
https://github.com/opentffoundation/opentf.git
synced 2026-03-04 08:03:40 -05:00
7e1a02cbb8
Signed-off-by: Alex Ott <alexott@gmail.com> Co-authored-by: Siddhartha Sonker <158144589+siddharthasonker95@users.noreply.github.com>
199 lines
8.1 KiB
Plaintext
199 lines
8.1 KiB
Plaintext
---
|
|
description: >-
|
|
Learn to use environment variables to change OpenTofu's default behavior.
|
|
Configure log content and output, set variables, and more.
|
|
---
|
|
|
|
# Environment Variables
|
|
|
|
OpenTofu refers to a number of environment variables to customize various
|
|
aspects of its behavior. None of these environment variables are required
|
|
when using OpenTofu, but they can be used to change some of OpenTofu's
|
|
default behaviors in unusual situations, or to increase output verbosity
|
|
for debugging.
|
|
|
|
## TF_LOG
|
|
|
|
Enables detailed logs to appear on stderr which is useful for debugging. For example:
|
|
|
|
```shell
|
|
export TF_LOG=trace
|
|
```
|
|
|
|
To disable, either unset it, or set it to `off`. For example:
|
|
|
|
```shell
|
|
export TF_LOG=off
|
|
```
|
|
|
|
For more on debugging OpenTofu, check out the section on [Debugging](../../internals/debugging.mdx).
|
|
|
|
## TF_LOG_PATH
|
|
|
|
This specifies where the log should persist its output to. Note that even when `TF_LOG_PATH` is set, `TF_LOG` must be set in order for any logging to be enabled. For example, to always write the log to the directory you're currently running tofu from:
|
|
|
|
```shell
|
|
export TF_LOG_PATH=./terraform.log
|
|
```
|
|
|
|
For more on debugging OpenTofu, check out the section on [Debugging](../../internals/debugging.mdx).
|
|
|
|
## TF_INPUT
|
|
|
|
If set to "false" or "0", causes tofu commands to behave as if the `-input=false` flag was specified. This is used when you want to disable prompts for variables that haven't had their values specified. For example:
|
|
|
|
```shell
|
|
export TF_INPUT=0
|
|
```
|
|
|
|
## TF_VAR_name
|
|
|
|
Environment variables can be used to set variables. The environment variables must be in the format `TF_VAR_name` and this will be checked last for a value. For example:
|
|
|
|
```shell
|
|
export TF_VAR_region=us-west-1
|
|
export TF_VAR_ami=ami-049d8641
|
|
export TF_VAR_alist='[1,2,3]'
|
|
export TF_VAR_amap='{ foo = "bar", baz = "qux" }'
|
|
```
|
|
|
|
For more on how to use `TF_VAR_name` in context, check out the section on [Variable Configuration](../../language/values/variables.mdx).
|
|
|
|
## TF_CLI_ARGS and TF_CLI_ARGS_name
|
|
|
|
<a id="tf-cli-args"></a>
|
|
|
|
The value of `TF_CLI_ARGS` will specify additional arguments to the
|
|
command-line. This allows easier automation in CI environments as well as
|
|
modifying default behavior of OpenTofu on your own system.
|
|
|
|
These 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, the following command: `TF_CLI_ARGS="-input=false" tofu apply -force`
|
|
is the equivalent to manually typing: `tofu apply -input=false -force`.
|
|
|
|
The flag `TF_CLI_ARGS` affects all OpenTofu commands. If you specify a
|
|
named command in the form of `TF_CLI_ARGS_name` then it will only affect
|
|
that command. As an example, to specify that only plans never refresh,
|
|
you can set `TF_CLI_ARGS_plan="-refresh=false"`.
|
|
|
|
The value of the flag is parsed as if you typed it directly to the shell.
|
|
Double and single quotes are allowed to capture strings and arguments will
|
|
be separated by spaces otherwise.
|
|
|
|
## TF_DATA_DIR
|
|
|
|
`TF_DATA_DIR` changes the location where OpenTofu keeps its
|
|
per-working-directory data, such as the current backend configuration.
|
|
|
|
By default this data is written into a `.terraform` subdirectory of the
|
|
current directory, but the path given in `TF_DATA_DIR` will be used instead
|
|
if non-empty.
|
|
|
|
In most cases it should not be necessary to set this variable, but it may
|
|
be useful to do so if e.g. the working directory is not writable.
|
|
|
|
The data directory is used to retain data that must persist from one command
|
|
to the next, so it's important to have this variable set consistently throughout
|
|
all of the OpenTofu workflow commands (starting with `tofu init`) or else
|
|
OpenTofu may be unable to find providers, modules, and other artifacts.
|
|
|
|
## TF_WORKSPACE
|
|
|
|
For multi-environment deployment, in order to select a workspace, instead of doing `tofu workspace select your_workspace`, it is possible to use this environment variable. Using TF_WORKSPACE allow and override workspace selection.
|
|
|
|
For example:
|
|
|
|
```shell
|
|
export TF_WORKSPACE=your_workspace
|
|
```
|
|
|
|
Using this environment variable is recommended only for non-interactive usage, since in a local shell environment it can be easy to forget the variable is set and apply changes to the wrong state.
|
|
|
|
For more information regarding workspaces, check out the section on [Using Workspaces](../../language/state/workspaces.mdx).
|
|
|
|
## TF_IN_AUTOMATION
|
|
|
|
If `TF_IN_AUTOMATION` is set to any non-empty value, OpenTofu adjusts its
|
|
output to avoid suggesting specific commands to run next. This can make the
|
|
output more consistent and less confusing in workflows where users don't
|
|
directly execute OpenTofu commands, like in CI systems or other wrapping
|
|
applications.
|
|
|
|
This is a purely cosmetic change to OpenTofu's human-readable output, and the
|
|
exact output differences can change between minor OpenTofu versions.
|
|
|
|
## 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.
|
|
|
|
## TF_REGISTRY_CLIENT_TIMEOUT
|
|
|
|
The default client timeout for requests to the remote registry is 10s. `TF_REGISTRY_CLIENT_TIMEOUT` can be configured and increased during exceptional circumstances.
|
|
|
|
```shell
|
|
export TF_REGISTRY_CLIENT_TIMEOUT=15
|
|
```
|
|
|
|
## TF_CLI_CONFIG_FILE
|
|
|
|
The location of the [OpenTofu CLI configuration file](../../cli/config/config-file.mdx).
|
|
|
|
```shell
|
|
export TF_CLI_CONFIG_FILE="$HOME/.tofurc-custom"
|
|
```
|
|
|
|
## TF_PLUGIN_CACHE_DIR
|
|
|
|
The `TF_PLUGIN_CACHE_DIR` environment variable is an alternative way to set [the `plugin_cache_dir` setting in the CLI configuration](../../cli/config/config-file.mdx#provider-plugin-cache).
|
|
|
|
You can also use `TF_PLUGIN_CACHE_MAY_BREAK_DEPENDENCY_LOCK_FILE` to activate [the transitional compatibility setting `plugin_cache_may_break_dependency_lock_file`](../../cli/config/config-file.mdx#allowing-the-provider-plugin-cache-to-break-the-dependency-lock-file).
|
|
|
|
## TF_IGNORE
|
|
|
|
If `TF_IGNORE` is set to "trace", OpenTofu will output debug messages to display ignored files and folders. This is useful when debugging large repositories with `.terraformignore` files.
|
|
|
|
```shell
|
|
export TF_IGNORE=trace
|
|
```
|
|
|
|
## TF_PROVIDER_DOWNLOAD_RETRY
|
|
|
|
Set `TF_PROVIDER_DOWNLOAD_RETRY` to configure the max number of request retries
|
|
the remote provider client will attempt for client connection errors or
|
|
500-range responses that are safe to retry.
|
|
|
|
```shell
|
|
export TF_PROVIDER_DOWNLOAD_RETRY=3
|
|
```
|
|
|
|
For more details on `.terraformignore`, please see [Excluding Files from Upload with .terraformignore](../../language/settings/backends/remote.mdx#excluding-files-from-upload-with-terraformignore).
|
|
|
|
## TF_STATE_PERSIST_INTERVAL
|
|
|
|
Set `TF_STATE_PERSIST_INTERVAL` to configure the interval (in seconds) between state persistence. Increased interval could be useful when working with huge states (> 100k resources) where upload to a cloud service could take a significant amount of time. Default persistence interval is 20 seconds (it also the lowest possible value for this parameter). The following command sets persistence interval to 5 minutes (300 seconds):
|
|
|
|
```shell
|
|
export TF_STATE_PERSIST_INTERVAL=300
|
|
```
|
|
|
|
## Cloud Backend CLI Integration
|
|
|
|
The CLI integration with cloud backends lets you use them on the command line. The integration requires including a `cloud` block in your OpenTofu configuration. You can define its arguments directly in your configuration file or supply them through environment variables, which can be useful for non-interactive workflows like Continuous Integration (CI).
|
|
|
|
Refer to [Cloud Backend Settings](../../cli/cloud/settings.mdx#environment-variables) for a full list of `cloud` block environment variables.
|
|
|
|
## TF_ENCRYPTION
|
|
|
|
The `TF_ENCRYPTION` environment variable is an alternate method of specifying the contents of the `terraform { encryption {} }` block. If provided, it will be parsed as either HCL or JSON and override configuration present in the .tf config files.
|
|
|
|
```shell
|
|
# Add/Override encryption key_provider.static.mykp
|
|
export TF_ENCRYPTION='key_provider "static" "mykp" { key = "6f6f706830656f67686f6834616872756f3751756165686565796f6f72653169" }'
|
|
```
|