Improve documentation around static evaluation (#1843)

Signed-off-by: Christian Mesh <christianmesh1@gmail.com>
Signed-off-by: ollevche <ollevche@gmail.com>
Co-authored-by: ollevche <ollevche@gmail.com>
This commit is contained in:
Christian Mesh 2024-07-23 09:31:50 -04:00 committed by GitHub
parent 89926cc97a
commit 3b3822d770
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
31 changed files with 640 additions and 12 deletions

View File

@ -28,6 +28,14 @@ For configurations using
`tofu console` accepts the legacy command line option
[`-state`](../../language/settings/backends/local.mdx#command-line-arguments).
:::note
Use of variables in [module sources](../../language/modules/sources.mdx#support-for-variable-and-local-evaluation),
[backend configuration](../../language/settings/backends/configuration.mdx#variables-and-locals),
or [encryption block](../../language/state/encryption.mdx#configuration)
requires [assigning values to root module variables](../../language/values/variables.mdx#assigning-values-to-root-module-variables)
when running `tofu console`.
:::
This command also accepts the following options for tofu console:
- `-var 'NAME=VALUE'` - Sets a value for a single
@ -42,6 +50,10 @@ This command also accepts the following options for tofu console:
["tfvars" file](/docs/language/values/variables#variable-definitions-tfvars-files).
Use this option multiple times to include values from more than one file.
There are several other ways to set values for input variables in the root
module, aside from the `-var` and `-var-file` options. Refer to
[Assigning Values to Root Module Variables](../../language/values/variables.mdx#assigning-values-to-root-module-variables) for more information.
## Scripting
The `tofu console` command can be used in non-interactive scripts

View File

@ -24,6 +24,29 @@ state for the current configuration. The behavior of this lock is dependent
on the backend being used. Local state files cannot be unlocked by another
process.
:::note
Use of variables in [backend configuration](../../language/settings/backends/configuration.mdx#variables-and-locals),
or [encryption block](../../language/state/encryption.mdx#configuration)
requires [assigning values to root module variables](../../language/values/variables.mdx#assigning-values-to-root-module-variables)
when running `tofu force-unlock`.
:::
Options:
* `-force` - Don't ask for input for unlock confirmation.
* `-var 'NAME=VALUE'` - Sets a value for a single
[input variable](../../language/values/variables.mdx) declared in the
root module of the configuration. Use this option multiple times to set
more than one variable. Refer to
[Input Variables on the Command Line](plan.mdx#input-variables-on-the-command-line) for more information.
* `-var-file=FILENAME` - Sets values for potentially many
[input variables](../../language/values/variables.mdx) declared in the
root module of the configuration, using definitions from a
["tfvars" file](../../language/values/variables.mdx#variable-definitions-tfvars-files).
Use this option multiple times to include values from more than one file.
There are several other ways to set values for input variables in the root
module, aside from the `-var` and `-var-file` options. Refer to
[Assigning Values to Root Module Variables](../../language/values/variables.mdx#assigning-values-to-root-module-variables) for more information.

View File

@ -15,6 +15,12 @@ The modules are downloaded into a `.terraform` subdirectory of the current
working directory. Don't commit this directory to your version control
repository.
:::note
Use of [variables in module sources](../../language/modules/sources.mdx#support-for-variable-and-local-evaluation)
requires [assigning values to root module variables](../../language/values/variables.mdx#assigning-values-to-root-module-variables)
when running `tofu get`.
:::
The `get` command supports the following option:
* `-update` - If specified, modules that are already downloaded will be
@ -24,3 +30,19 @@ The `get` command supports the following option:
* `-json` Produce output in a machine-readable JSON format, suitable for use
in text editor integrations and other automated systems. Always disables color.
* `-var 'NAME=VALUE'` - Sets a value for a single
[input variable](../../language/values/variables.mdx) declared in the
root module of the configuration. Use this option multiple times to set
more than one variable. Refer to
[Input Variables on the Command Line](plan.mdx#input-variables-on-the-command-line) for more information.
* `-var-file=FILENAME` - Sets values for potentially many
[input variables](../../language/values/variables.mdx) declared in the
root module of the configuration, using definitions from a
["tfvars" file](../../language/values/variables.mdx#variable-definitions-tfvars-files).
Use this option multiple times to include values from more than one file.
There are several other ways to set values for input variables in the root
module, aside from the `-var` and `-var-file` options. Refer to
[Assigning Values to Root Module Variables](../../language/values/variables.mdx#assigning-values-to-root-module-variables) for more information.

View File

@ -28,6 +28,14 @@ for the list of types supported. The default type is "plan" if a
configuration is given, and "apply" if a plan file is passed as an
argument.
:::note
Use of variables in [module sources](../../language/modules/sources.mdx#support-for-variable-and-local-evaluation),
[backend configuration](../../language/settings/backends/configuration.mdx#variables-and-locals),
or [encryption block](../../language/state/encryption.mdx#configuration)
requires [assigning values to root module variables](../../language/values/variables.mdx#assigning-values-to-root-module-variables)
when running `tofu graph`.
:::
Options:
* `-plan=tfplan` - Render graph using the specified plan file instead of the
@ -41,6 +49,22 @@ Options:
* `-module-depth=n` - (deprecated) In prior versions of OpenTofu, specified the
depth of modules to show in the output.
* `-var 'NAME=VALUE'` - Sets a value for a single
[input variable](../../language/values/variables.mdx) declared in the
root module of the configuration. Use this option multiple times to set
more than one variable. Refer to
[Input Variables on the Command Line](plan.mdx#input-variables-on-the-command-line) for more information.
* `-var-file=FILENAME` - Sets values for potentially many
[input variables](../../language/values/variables.mdx) declared in the
root module of the configuration, using definitions from a
["tfvars" file](../../language/values/variables.mdx#variable-definitions-tfvars-files).
Use this option multiple times to include values from more than one file.
There are several other ways to set values for input variables in the root
module, aside from the `-var` and `-var-file` options. Refer to
[Assigning Values to Root Module Variables](../../language/values/variables.mdx#assigning-values-to-root-module-variables) for more information.
## Generating Images
The output of `tofu graph` is in the DOT format, which can

View File

@ -34,6 +34,14 @@ behavior. For more information on this assumption, see
[the State section](../../language/state/index.mdx).
:::
:::note
Use of variables in [module sources](../../language/modules/sources.mdx#support-for-variable-and-local-evaluation),
[backend configuration](../../language/settings/backends/configuration.mdx#variables-and-locals),
or [encryption block](../../language/state/encryption.mdx#configuration)
requires [assigning values to root module variables](../../language/values/variables.mdx#assigning-values-to-root-module-variables)
when running `tofu import`.
:::
The command-line flags are all optional. The following flags are available:
- `-config=path` - Path to directory of OpenTofu configuration files that

View File

@ -25,6 +25,11 @@ directory up to date with changes in the configuration. Though subsequent runs
may give errors, this command will never delete your existing configuration or
state.
This command requires value assignment for variables used in [module sources](../../language/modules/sources.mdx#support-for-variable-and-local-evaluation)
and [backend configuration](../../language/settings/backends/configuration.mdx#variables-and-locals)
blocks. Refer to [Assigning Values to Root Module Variables](../../language/values/variables.mdx#assigning-values-to-root-module-variables)
for more information.
## General Options
The following options apply to all of (or several of) the initialization steps:
@ -46,6 +51,22 @@ The following options apply to all of (or several of) the initialization steps:
* `-json` Produce output in a machine-readable JSON format, suitable for use
in text editor integrations and other automated systems. Always disables color.
* `-var 'NAME=VALUE'` - Sets a value for a single
[input variable](../../language/values/variables.mdx) declared in the
root module of the configuration. Use this option multiple times to set
more than one variable. Refer to
[Input Variables on the Command Line](plan.mdx#input-variables-on-the-command-line) for more information.
* `-var-file=FILENAME` - Sets values for potentially many
[input variables](../../language/values/variables.mdx) declared in the
root module of the configuration, using definitions from a
["tfvars" file](../../language/values/variables.mdx#variable-definitions-tfvars-files).
Use this option multiple times to include values from more than one file.
There are several other ways to set values for input variables in the root
module, aside from the `-var` and `-var-file` options. Refer to
[Assigning Values to Root Module Variables](../../language/values/variables.mdx#assigning-values-to-root-module-variables) for more information.
## Copy a Source Module
By default, `tofu init` assumes that the working directory already
@ -77,6 +98,12 @@ During init, the root configuration directory is consulted for
[backend configuration](../../language/settings/backends/configuration.mdx) and the chosen backend
is initialized using the given configuration settings.
:::note
Use of [variables in the backend configuration](../../language/settings/backends/configuration.mdx#variables-and-locals)
block requires [assigning values to root module variables](../../language/values/variables.mdx#assigning-values-to-root-module-variables)
when running `tofu init`.
:::
Re-running init with an already-initialized backend will update the working
directory to use the new backend settings. Either `-reconfigure` or
`-migrate-state` must be supplied to update the backend configuration.

View File

@ -17,20 +17,46 @@ With no additional arguments, `output` will display all the outputs for
the root module. If an output `NAME` is specified, only the value of that
output is printed.
:::note
Use of variables in [backend configuration](../../language/settings/backends/configuration.mdx#variables-and-locals)
or [encryption block](../../language/state/encryption.mdx#configuration)
requires [assigning values to root module variables](../../language/values/variables.mdx#assigning-values-to-root-module-variables)
when running `tofu output`.
:::
The command-line flags are all optional. The following flags are available:
* `-json` - If specified, the outputs are formatted as a JSON object, with
a key per output. If `NAME` is specified, only the output specified will be
returned. This can be piped into tools such as `jq` for further processing.
* `-raw` - If specified, OpenTofu will convert the specified output value to a
string and print that string directly to the output, without any special
formatting. This can be convenient when working with shell scripts, but
it only supports string, number, and boolean values. Use `-json` instead
for processing complex data types.
* `-no-color` - If specified, output won't contain any color.
* `-state=path` - Path to the state file. Defaults to "terraform.tfstate".
Ignored when [remote state](../../language/state/remote.mdx) is used.
* `-var 'NAME=VALUE'` - Sets a value for a single
[input variable](../../language/values/variables.mdx) declared in the
root module of the configuration. Use this option multiple times to set
more than one variable. Refer to
[Input Variables on the Command Line](plan.mdx#input-variables-on-the-command-line) for more information.
* `-var-file=FILENAME` - Sets values for potentially many
[input variables](../../language/values/variables.mdx) declared in the
root module of the configuration, using definitions from a
["tfvars" file](../../language/values/variables.mdx#variable-definitions-tfvars-files).
Use this option multiple times to include values from more than one file.
There are several other ways to set values for input variables in the root
module, aside from the `-var` and `-var-file` options. Refer to
[Assigning Values to Root Module Variables](../../language/values/variables.mdx#assigning-values-to-root-module-variables) for more information.
:::note
When using the `-json` or `-raw` command-line flag, any sensitive
values in OpenTofu state will be displayed in plain text. For more information,

View File

@ -15,7 +15,8 @@ This command also has several subcommands with different purposes.
## Usage
Usage:
Usage: `tofu providers [options]`
```
$ tofu providers
@ -29,3 +30,29 @@ Providers required by state:
provider[registry.opentofu.org/hashicorp/tfcoremock]
```
:::note
Use of variables in [module sources](../../../language/modules/sources.mdx#support-for-variable-and-local-evaluation),
[backend configuration](../../../language/settings/backends/configuration.mdx#variables-and-locals),
or [encryption block](../../../language/state/encryption.mdx#configuration)
requires [assigning values to root module variables](../../../language/values/variables.mdx#assigning-values-to-root-module-variables)
when running `tofu providers`.
:::
This command accepts the following options:
* `-var 'NAME=VALUE'` - Sets a value for a single
[input variable](../../../language/values/variables.mdx) declared in the
root module of the configuration. Use this option multiple times to set
more than one variable. Refer to
[Input Variables on the Command Line](../plan.mdx#input-variables-on-the-command-line) for more information.
* `-var-file=FILENAME` - Sets values for potentially many
[input variables](../../../language/values/variables.mdx) declared in the
root module of the configuration, using definitions from a
["tfvars" file](../../../language/values/variables.mdx#variable-definitions-tfvars-files).
Use this option multiple times to include values from more than one file.
There are several other ways to set values for input variables in the root
module, aside from the `-var` and `-var-file` options. Refer to
[Assigning Values to Root Module Variables](../../../language/values/variables.mdx#assigning-values-to-root-module-variables) for more information.

View File

@ -40,6 +40,30 @@ automatic approach may not be sufficient:
Usage: `tofu providers lock [options] [providers...]`
:::note
Use of variables in [module sources](../../../language/modules/sources.mdx#support-for-variable-and-local-evaluation)
requires [assigning values to root module variables](../../../language/values/variables.mdx#assigning-values-to-root-module-variables)
when running `tofu providers lock`.
:::
This command accepts the following generic options:
* `-var 'NAME=VALUE'` - Sets a value for a single
[input variable](../../../language/values/variables.mdx) declared in the
root module of the configuration. Use this option multiple times to set
more than one variable. Refer to
[Input Variables on the Command Line](../plan.mdx#input-variables-on-the-command-line) for more information.
* `-var-file=FILENAME` - Sets values for potentially many
[input variables](../../../language/values/variables.mdx) declared in the
root module of the configuration, using definitions from a
["tfvars" file](../../../language/values/variables.mdx#variable-definitions-tfvars-files).
Use this option multiple times to include values from more than one file.
There are several other ways to set values for input variables in the root
module, aside from the `-var` and `-var-file` options. Refer to
[Assigning Values to Root Module Variables](../../../language/values/variables.mdx#assigning-values-to-root-module-variables) for more information.
With no additional command line arguments, `tofu providers lock` will
analyze the configuration in the current working directory to find all of
the providers it depends on, and it will fetch the necessary data about those

View File

@ -34,6 +34,30 @@ directory the path structure that is expected for filesystem-based provider
plugin mirrors, populating it with `.zip` files containing the plugins
themselves.
:::note
Use of variables in [module sources](../../../language/modules/sources.mdx#support-for-variable-and-local-evaluation)
requires [assigning values to root module variables](../../../language/values/variables.mdx#assigning-values-to-root-module-variables)
when running `tofu providers mirror`.
:::
This command accepts the following generic options:
* `-var 'NAME=VALUE'` - Sets a value for a single
[input variable](../../../language/values/variables.mdx) declared in the
root module of the configuration. Use this option multiple times to set
more than one variable. Refer to
[Input Variables on the Command Line](../plan.mdx#input-variables-on-the-command-line) for more information.
* `-var-file=FILENAME` - Sets values for potentially many
[input variables](../../../language/values/variables.mdx) declared in the
root module of the configuration, using definitions from a
["tfvars" file](../../../language/values/variables.mdx#variable-definitions-tfvars-files).
Use this option multiple times to include values from more than one file.
There are several other ways to set values for input variables in the root
module, aside from the `-var` and `-var-file` options. Refer to
[Assigning Values to Root Module Variables](../../../language/values/variables.mdx#assigning-values-to-root-module-variables) for more information.
OpenTofu will also generate various `.json` index files which contain suitable
responses to implement
[the network mirror protocol](../../../internals/provider-network-mirror-protocol.mdx),
@ -41,7 +65,7 @@ if you upload the resulting directory to a static website host. OpenTofu
ignores those index files when using the directory as a filesystem mirror,
because the directory entries themselves are authoritative in that case.
This command supports the following additional option:
This command supports the following additional options:
* `-platform=OS_ARCH` - Choose which target platform to build a mirror for.
By default OpenTofu will obtain plugin packages suitable for the platform

View File

@ -14,10 +14,34 @@ The `tofu providers schema` command is used to print detailed schemas for the pr
Usage: `tofu providers schema [options]`
:::note
Use of variables in [module sources](../../../language/modules/sources.mdx#support-for-variable-and-local-evaluation),
[backend configuration](../../../language/settings/backends/configuration.mdx#variables-and-locals),
or [encryption block](../../../language/state/encryption.mdx#configuration)
requires [assigning values to root module variables](../../../language/values/variables.mdx#assigning-values-to-root-module-variables)
when running `tofu providers schema`.
:::
The following flags are available:
- `-json` - Displays the schemas in a machine-readable, JSON format.
- `-var 'NAME=VALUE'` - Sets a value for a single
[input variable](../../../language/values/variables.mdx) declared in the
root module of the configuration. Use this option multiple times to set
more than one variable. Refer to
[Input Variables on the Command Line](../plan.mdx#input-variables-on-the-command-line) for more information.
- `-var-file=FILENAME` - Sets values for potentially many
[input variables](../../../language/values/variables.mdx) declared in the
root module of the configuration, using definitions from a
["tfvars" file](../../../language/values/variables.mdx#variable-definitions-tfvars-files).
Use this option multiple times to include values from more than one file.
There are several other ways to set values for input variables in the root
module, aside from the `-var` and `-var-file` options. Refer to
[Assigning Values to Root Module Variables](../../../language/values/variables.mdx#assigning-values-to-root-module-variables) for more information.
Please note that, at this time, the `-json` flag is a _required_ option. In future releases, this command will be extended to allow for additional options.
The output includes a `format_version` key, which has

View File

@ -43,6 +43,14 @@ Consequently, it supports all of the same options as
plan file, it doesn't allow selecting a planning mode other than "refresh only",
and `-auto-approve` is always enabled.
:::note
Use of variables in [module sources](../../language/modules/sources.mdx#support-for-variable-and-local-evaluation),
[backend configuration](../../language/settings/backends/configuration.mdx#variables-and-locals),
or [encryption block](../../language/state/encryption.mdx#configuration)
requires [assigning values to root module variables](../../language/values/variables.mdx#assigning-values-to-root-module-variables)
when running `tofu refresh`.
:::
Automatically applying the effect of a refresh is risky. If you have
misconfigured credentials for one or more providers, OpenTofu may
be misled into thinking that all of the managed objects have been deleted,

View File

@ -25,12 +25,36 @@ For complex infrastructures, the state can contain thousands of resources.
To filter these, provide one or more patterns to the command. Patterns are
in [resource addressing format](../../../cli/state/resource-addressing.mdx).
:::note
Use of variables in [backend configuration](../../../language/settings/backends/configuration.mdx#variables-and-locals)
or [encryption block](../../../language/state/encryption.mdx#configuration)
requires [assigning values to root module variables](../../../language/values/variables.mdx#assigning-values-to-root-module-variables)
when running `tofu state list`.
:::
The command-line flags are all optional. The following flags are available:
* `-state=path` - Path to the state file. Defaults to "terraform.tfstate".
Ignored when [remote state](../../../language/state/remote.mdx) is used.
* `-id=id` - ID of resources to show. Ignored when unset.
* `-var 'NAME=VALUE'` - Sets a value for a single
[input variable](../../../language/values/variables.mdx) declared in the
root module of the configuration. Use this option multiple times to set
more than one variable. Refer to
[Input Variables on the Command Line](../plan.mdx#input-variables-on-the-command-line) for more information.
* `-var-file=FILENAME` - Sets values for potentially many
[input variables](../../../language/values/variables.mdx) declared in the
root module of the configuration, using definitions from a
["tfvars" file](../../../language/values/variables.mdx#variable-definitions-tfvars-files).
Use this option multiple times to include values from more than one file.
There are several other ways to set values for input variables in the root
module, aside from the `-var` and `-var-file` options. Refer to
[Assigning Values to Root Module Variables](../../../language/values/variables.mdx#assigning-values-to-root-module-variables) for more information.
## Example: All Resources
This example will list all resources, including modules:

View File

@ -53,6 +53,14 @@ a plan that will destroy the old object and create a new object at the new
address.
:::
:::note
Use of variables in [module sources](../../../language/modules/sources.mdx#support-for-variable-and-local-evaluation),
[backend configuration](../../../language/settings/backends/configuration.mdx#variables-and-locals),
or [encryption block](../../../language/state/encryption.mdx#configuration)
requires [assigning values to root module variables](../../../language/values/variables.mdx#assigning-values-to-root-module-variables)
when running `tofu state mv`.
:::
This command also accepts the following options:
- `-dry-run` - Report all of the resource instances that match the given
@ -67,6 +75,22 @@ This command also accepts the following options:
returning an error. The duration syntax is a number followed by a time
unit letter, such as "3s" for three seconds.
* `-var 'NAME=VALUE'` - Sets a value for a single
[input variable](../../../language/values/variables.mdx) declared in the
root module of the configuration. Use this option multiple times to set
more than one variable. Refer to
[Input Variables on the Command Line](../plan.mdx#input-variables-on-the-command-line) for more information.
* `-var-file=FILENAME` - Sets values for potentially many
[input variables](../../../language/values/variables.mdx) declared in the
root module of the configuration, using definitions from a
["tfvars" file](../../../language/values/variables.mdx#variable-definitions-tfvars-files).
Use this option multiple times to include values from more than one file.
There are several other ways to set values for input variables in the root
module, aside from the `-var` and `-var-file` options. Refer to
[Assigning Values to Root Module Variables](../../../language/values/variables.mdx#assigning-values-to-root-module-variables) for more information.
For configurations using the [`cloud` backend](../../../cli/cloud/index.mdx) or the [`remote` backend](../../../language/settings/backends/remote.mdx)
only, `tofu state mv`
also accepts the option

View File

@ -29,3 +29,29 @@ version before output.
:::note
OpenTofu state files must be in UTF-8 format without a byte order mark (BOM). For PowerShell on Windows, use `Set-Content` to automatically encode files in UTF-8 format. For example, run `tofu state pull | sc terraform.tfstate`.
:::
:::note
Use of variables in [module sources](../../../language/modules/sources.mdx#support-for-variable-and-local-evaluation),
[backend configuration](../../../language/settings/backends/configuration.mdx#variables-and-locals),
or [encryption block](../../../language/state/encryption.mdx#configuration)
requires [assigning values to root module variables](../../../language/values/variables.mdx#assigning-values-to-root-module-variables)
when running `tofu state pull`.
:::
The command support the following command-line arguments:
* `-var 'NAME=VALUE'` - Sets a value for a single
[input variable](../../../language/values/variables.mdx) declared in the
root module of the configuration. Use this option multiple times to set
more than one variable. Refer to
[Input Variables on the Command Line](../plan.mdx#input-variables-on-the-command-line) for more information.
* `-var-file=FILENAME` - Sets values for potentially many
[input variables](../../../language/values/variables.mdx) declared in the
root module of the configuration, using definitions from a
["tfvars" file](../../../language/values/variables.mdx#variable-definitions-tfvars-files).
Use this option multiple times to include values from more than one file.
There are several other ways to set values for input variables in the root
module, aside from the `-var` and `-var-file` options. Refer to
[Assigning Values to Root Module Variables](../../../language/values/variables.mdx#assigning-values-to-root-module-variables) for more information.

View File

@ -44,10 +44,15 @@ Both of these safety checks can be disabled with the `-force` flag.
pushing state, the destination state will be overwritten.
For configurations using the [`cloud` backend](../../../cli/cloud/index.mdx) or the [`remote` backend](../../../language/settings/backends/remote.mdx)
only, `tofu state push`
also accepts the option
only, `tofu state push` also accepts the option [`-ignore-remote-version`](/docs/cli/cloud/command-line-arguments#ignore-remote-version).
[`-ignore-remote-version`](/docs/cli/cloud/command-line-arguments#ignore-remote-version).
:::note
Use of variables in [module sources](../../../language/modules/sources.mdx#support-for-variable-and-local-evaluation),
[backend configuration](../../../language/settings/backends/configuration.mdx#variables-and-locals),
or [encryption block](../../../language/state/encryption.mdx#configuration)
requires [assigning values to root module variables](../../../language/values/variables.mdx#assigning-values-to-root-module-variables)
when running `tofu state push`.
:::
This command also accepts the following options for tofu state push:
@ -60,5 +65,20 @@ This command also accepts the following options for tofu state push:
returning an error. The duration syntax is a number followed by a time
unit letter, such as "3s" for three seconds.
[`-ignore-remote-version`](../../../cli/cloud/command-line-arguments.mdx#ignore-remote-version).
- [`ignore-remote-version`](../../../cli/cloud/command-line-arguments.mdx#ignore-remote-version).
- `-var 'NAME=VALUE'` - Sets a value for a single
[input variable](../../../language/values/variables.mdx) declared in the
root module of the configuration. Use this option multiple times to set
more than one variable. Refer to
[Input Variables on the Command Line](../plan.mdx#input-variables-on-the-command-line) for more information.
- `-var-file=FILENAME` - Sets values for potentially many
[input variables](../../../language/values/variables.mdx) declared in the
root module of the configuration, using definitions from a
["tfvars" file](../../../language/values/variables.mdx#variable-definitions-tfvars-files).
Use this option multiple times to include values from more than one file.
There are several other ways to set values for input variables in the root
module, aside from the `-var` and `-var-file` options. Refer to
[Assigning Values to Root Module Variables](../../../language/values/variables.mdx#assigning-values-to-root-module-variables) for more information.

View File

@ -21,6 +21,14 @@ This command will output a backup copy of the state prior to saving any
changes. The backup cannot be disabled. Due to the destructive nature
of this command, backups are required.
:::note
Use of variables in [module sources](../../../language/modules/sources.mdx#support-for-variable-and-local-evaluation),
[backend configuration](../../../language/settings/backends/configuration.mdx#variables-and-locals),
or [encryption block](../../../language/state/encryption.mdx#configuration)
requires [assigning values to root module variables](../../../language/values/variables.mdx#assigning-values-to-root-module-variables)
when running `tofu state replace-providers`.
:::
This command also accepts the following options:
- `-auto-approve` - Skip interactive approval.
@ -31,6 +39,22 @@ This command also accepts the following options:
- `-lock-timeout=0s` - Duration to retry a state lock.
- `-var 'NAME=VALUE'` - Sets a value for a single
[input variable](../../../language/values/variables.mdx) declared in the
root module of the configuration. Use this option multiple times to set
more than one variable. Refer to
[Input Variables on the Command Line](../plan.mdx#input-variables-on-the-command-line) for more information.
- `-var-file=FILENAME` - Sets values for potentially many
[input variables](../../../language/values/variables.mdx) declared in the
root module of the configuration, using definitions from a
["tfvars" file](../../../language/values/variables.mdx#variable-definitions-tfvars-files).
Use this option multiple times to include values from more than one file.
There are several other ways to set values for input variables in the root
module, aside from the `-var` and `-var-file` options. Refer to
[Assigning Values to Root Module Variables](../../../language/values/variables.mdx#assigning-values-to-root-module-variables) for more information.
For configurations using the [`cloud` backend](../../../cli/cloud/index.mdx) or the [`remote` backend](../../../language/settings/backends/remote.mdx)
only, `tofu state replace-provider`
also accepts the option

View File

@ -34,6 +34,14 @@ instances. Depending on the constraints imposed by the remote system, creating
those objects might fail if their names or other identifiers conflict with
the old objects still present.
:::note
Use of variables in [module sources](../../../language/modules/sources.mdx#support-for-variable-and-local-evaluation),
[backend configuration](../../../language/settings/backends/configuration.mdx#variables-and-locals),
or [encryption block](../../../language/state/encryption.mdx#configuration)
requires [assigning values to root module variables](../../../language/values/variables.mdx#assigning-values-to-root-module-variables)
when running `tofu state rm`.
:::
This command also accepts the following options:
- `-dry-run` - Report all of the resource instances that match the given
@ -48,6 +56,22 @@ This command also accepts the following options:
returning an error. The duration syntax is a number followed by a time
unit letter, such as "3s" for three seconds.
- `-var 'NAME=VALUE'` - Sets a value for a single
[input variable](../../../language/values/variables.mdx) declared in the
root module of the configuration. Use this option multiple times to set
more than one variable. Refer to
[Input Variables on the Command Line](../plan.mdx#input-variables-on-the-command-line) for more information.
- `-var-file=FILENAME` - Sets values for potentially many
[input variables](../../../language/values/variables.mdx) declared in the
root module of the configuration, using definitions from a
["tfvars" file](../../../language/values/variables.mdx#variable-definitions-tfvars-files).
Use this option multiple times to include values from more than one file.
There are several other ways to set values for input variables in the root
module, aside from the `-var` and `-var-file` options. Refer to
[Assigning Values to Root Module Variables](../../../language/values/variables.mdx#assigning-values-to-root-module-variables) for more information.
For configurations using the [`cloud` backend](../../../cli/cloud/index.mdx) or the [`remote` backend](../../../language/settings/backends/remote.mdx)
only, `tofu state rm`
also accepts the option

View File

@ -21,11 +21,35 @@ This command requires an address that points to a single resource in the
state. Addresses are
in [resource addressing format](../../../cli/state/resource-addressing.mdx).
:::note
Use of variables in [module sources](../../../language/modules/sources.mdx#support-for-variable-and-local-evaluation),
[backend configuration](../../../language/settings/backends/configuration.mdx#variables-and-locals),
or [encryption block](../../../language/state/encryption.mdx#configuration)
requires [assigning values to root module variables](../../../language/values/variables.mdx#assigning-values-to-root-module-variables)
when running `tofu show`.
:::
The command-line flags are all optional. The following flags are available:
* `-state=path` - Path to the state file. Defaults to "terraform.tfstate".
Ignored when [remote state](../../../language/state/remote.mdx) is used.
* `-var 'NAME=VALUE'` - Sets a value for a single
[input variable](../../../language/values/variables.mdx) declared in the
root module of the configuration. Use this option multiple times to set
more than one variable. Refer to
[Input Variables on the Command Line](../plan.mdx#input-variables-on-the-command-line) for more information.
* `-var-file=FILENAME` - Sets values for potentially many
[input variables](../../../language/values/variables.mdx) declared in the
root module of the configuration, using definitions from a
["tfvars" file](../../../language/values/variables.mdx#variable-definitions-tfvars-files).
Use this option multiple times to include values from more than one file.
There are several other ways to set values for input variables in the root
module, aside from the `-var` and `-var-file` options. Refer to
[Assigning Values to Root Module Variables](../../../language/values/variables.mdx#assigning-values-to-root-module-variables) for more information.
The output of `tofu state show` is intended for human consumption, not
programmatic consumption. To extract state data for use in other software, use
[`tofu show -json`](../../../cli/commands/show.mdx#json-output) and decode the result

View File

@ -41,6 +41,14 @@ as shown in the output from other commands, such as:
- `aws_instance.baz[\"key\"]` (quotes in resource addresses must be escaped on the command line, so that they will not be interpreted by your shell)
- `module.foo.module.bar.aws_instance.qux`
:::note
Use of variables in [module sources](../../language/modules/sources.mdx#support-for-variable-and-local-evaluation),
[backend configuration](../../language/settings/backends/configuration.mdx#variables-and-locals),
or [encryption block](../../language/state/encryption.mdx#configuration)
requires [assigning values to root module variables](../../language/values/variables.mdx#assigning-values-to-root-module-variables)
when running `tofu taint`.
:::
This command accepts the following options:
- `-allow-missing` - If specified, the command will succeed (exit code 0)
@ -56,6 +64,22 @@ This command accepts the following options:
returning an error. The duration syntax is a number followed by a time
unit letter, such as "3s" for three seconds.
- `-var 'NAME=VALUE'` - Sets a value for a single
[input variable](../../language/values/variables.mdx) declared in the
root module of the configuration. Use this option multiple times to set
more than one variable. Refer to
[Input Variables on the Command Line](plan.mdx#input-variables-on-the-command-line) for more information.
- `-var-file=FILENAME` - Sets values for potentially many
[input variables](../../language/values/variables.mdx) declared in the
root module of the configuration, using definitions from a
["tfvars" file](../../language/values/variables.mdx#variable-definitions-tfvars-files).
Use this option multiple times to include values from more than one file.
There are several other ways to set values for input variables in the root
module, aside from the `-var` and `-var-file` options. Refer to
[Assigning Values to Root Module Variables](../../language/values/variables.mdx#assigning-values-to-root-module-variables) for more information.
For configurations using the [`cloud` backend](../../cli/cloud/index.mdx) or the [`remote` backend](../../language/settings/backends/remote.mdx) only, `tofu taint`
also accepts the option
[`-ignore-remote-version`](../../cli/cloud/command-line-arguments.mdx#ignore-remote-version).

View File

@ -98,6 +98,14 @@ only load `main.tofutest.json` and ignore `main.tftest.json`.
* `-no-color` Disable colorized output in the command output.
* `-verbose` Print the plan or state for each test run block as it executes.
:::note
Use of variables in [module sources](../../../language/modules/sources.mdx#support-for-variable-and-local-evaluation),
[backend configuration](../../../language/settings/backends/configuration.mdx#variables-and-locals),
or [encryption block](../../../language/state/encryption.mdx#configuration)
requires [assigning values to root module variables](../../../language/values/variables.mdx#assigning-values-to-root-module-variables)
when running `tofu test`.
:::
## Directory structure
The `tofu test` command supports two directory layouts, flat or nested:

View File

@ -40,6 +40,14 @@ Usage: `tofu untaint [options] address`
The `address` argument is a [resource address](../../cli/state/resource-addressing.mdx)
identifying a particular resource instance which is currently tainted.
:::note
Use of variables in [module sources](../../language/modules/sources.mdx#support-for-variable-and-local-evaluation),
[backend configuration](../../language/settings/backends/configuration.mdx#variables-and-locals),
or [encryption block](../../language/state/encryption.mdx#configuration)
requires [assigning values to root module variables](../../language/values/variables.mdx#assigning-values-to-root-module-variables)
when running `tofu untaint`.
:::
This command also accepts the following options:
- `-allow-missing` - If specified, the command will succeed (exit code 0)
@ -60,6 +68,22 @@ This command also accepts the following options:
if you are running OpenTofu in a context where its output will be
rendered by a system that cannot interpret terminal formatting.
- `-var 'NAME=VALUE'` - Sets a value for a single
[input variable](../../language/values/variables.mdx) declared in the
root module of the configuration. Use this option multiple times to set
more than one variable. Refer to
[Input Variables on the Command Line](plan.mdx#input-variables-on-the-command-line) for more information.
- `-var-file=FILENAME` - Sets values for potentially many
[input variables](../../language/values/variables.mdx) declared in the
root module of the configuration, using definitions from a
["tfvars" file](../../language/values/variables.mdx#variable-definitions-tfvars-files).
Use this option multiple times to include values from more than one file.
There are several other ways to set values for input variables in the root
module, aside from the `-var` and `-var-file` options. Refer to
[Assigning Values to Root Module Variables](../../language/values/variables.mdx#assigning-values-to-root-module-variables) for more information.
For configurations using the [`cloud` backend](../../cli/cloud/index.mdx) or the [`remote` backend](../../language/settings/backends/remote.mdx)
only, `tofu untaint`
also accepts the option

View File

@ -10,10 +10,16 @@ The `tofu validate` command validates the configuration files in a
directory, referring only to the configuration and not accessing any remote
services such as remote state, provider APIs, etc.
:::note
Use of [variables in module sources](../../language/modules/sources.mdx#support-for-variable-and-local-evaluation)
requires [assigning values to root module variables](../../language/values/variables.mdx#assigning-values-to-root-module-variables)
when running `tofu validate`.
:::
Validate runs checks that verify whether a configuration is syntactically
valid and internally consistent, regardless of any provided variables or
existing state. It is thus primarily useful for general verification of
reusable modules, including correctness of attribute names and value types.
valid and internally consistent, regardless of existing state. It is thus
primarily useful for general verification of reusable modules, including
correctness of attribute names and value types.
It is safe to run this command automatically, for example as a post-save
check in a text editor or as a test step for a re-usable module in a CI
@ -41,6 +47,23 @@ This command accepts the following options:
* `-no-color` - If specified, output won't contain any color.
* `-var 'NAME=VALUE'` - Sets a value for a single
[input variable](../../language/values/variables.mdx) declared in the
root module of the configuration. Use this option multiple times to set
more than one variable. Refer to
[Input Variables on the Command Line](plan.mdx#input-variables-on-the-command-line) for more information.
* `-var-file=FILENAME` - Sets values for potentially many
[input variables](../../language/values/variables.mdx) declared in the
root module of the configuration, using definitions from a
["tfvars" file](../../language/values/variables.mdx#variable-definitions-tfvars-files).
Use this option multiple times to include values from more than one file.
There are several other ways to set values for input variables in the root
module, aside from the `-var` and `-var-file` options. Refer to
[Assigning Values to Root Module Variables](../../language/values/variables.mdx#assigning-values-to-root-module-variables) for more information.
## JSON Output Format
When you use the `-json` option, OpenTofu will produce validation results

View File

@ -26,14 +26,40 @@ OpenTofu to stop managing resources, so they can be managed some other way.
Most of the time, however, this is not intended and so OpenTofu protects you
from getting into this situation.
:::note
Use of variables in [module sources](../../../language/modules/sources.mdx#support-for-variable-and-local-evaluation),
[backend configuration](../../../language/settings/backends/configuration.mdx#variables-and-locals),
or [encryption block](../../../language/state/encryption.mdx#configuration)
requires [assigning values to root module variables](../../../language/values/variables.mdx#assigning-values-to-root-module-variables)
when running `tofu workspace delete`.
:::
The command-line flags are all optional. The only supported flags are:
* `-force` - Delete the workspace even if it is tracking resources. After deletion, OpenTofu can no longer track or manage the workspace's infrastructure. Defaults to false.
* `-lock=false` - Don't hold a state lock during the operation. This is
dangerous if others might concurrently run commands against the same
workspace.
* `-lock-timeout=DURATION` - Duration to retry a state lock. Default 0s.
* `-var 'NAME=VALUE'` - Sets a value for a single
[input variable](../../../language/values/variables.mdx) declared in the
root module of the configuration. Use this option multiple times to set
more than one variable. Refer to
[Input Variables on the Command Line](../plan.mdx#input-variables-on-the-command-line) for more information.
* `-var-file=FILENAME` - Sets values for potentially many
[input variables](../../../language/values/variables.mdx) declared in the
root module of the configuration, using definitions from a
["tfvars" file](../../../language/values/variables.mdx#variable-definitions-tfvars-files).
Use this option multiple times to include values from more than one file.
There are several other ways to set values for input variables in the root
module, aside from the `-var` and `-var-file` options. Refer to
[Assigning Values to Root Module Variables](../../../language/values/variables.mdx#assigning-values-to-root-module-variables) for more information.
## Example
```

View File

@ -13,6 +13,32 @@ Usage: `tofu workspace list [DIR]`
The command will list all existing workspaces. The current workspace is
indicated using an asterisk (`*`) marker.
:::note
Use of variables in [module sources](../../../language/modules/sources.mdx#support-for-variable-and-local-evaluation),
[backend configuration](../../../language/settings/backends/configuration.mdx#variables-and-locals),
or [encryption block](../../../language/state/encryption.mdx#configuration)
requires [assigning values to root module variables](../../../language/values/variables.mdx#assigning-values-to-root-module-variables)
when running `tofu workspace list`.
:::
This command also accepts the following options:
- `-var 'NAME=VALUE'` - Sets a value for a single
[input variable](../../../language/values/variables.mdx) declared in the
root module of the configuration. Use this option multiple times to set
more than one variable. Refer to
[Input Variables on the Command Line](../plan.mdx#input-variables-on-the-command-line) for more information.
- `-var-file=FILENAME` - Sets values for potentially many
[input variables](../../../language/values/variables.mdx) declared in the
root module of the configuration, using definitions from a
["tfvars" file](../../../language/values/variables.mdx#variable-definitions-tfvars-files).
Use this option multiple times to include values from more than one file.
There are several other ways to set values for input variables in the root
module, aside from the `-var` and `-var-file` options. Refer to
[Assigning Values to Root Module Variables](../../../language/values/variables.mdx#assigning-values-to-root-module-variables) for more information.
## Example
```

View File

@ -16,14 +16,40 @@ this name must not already exist.
If the `-state` flag is given, the state specified by the given path
will be copied to initialize the state for this new workspace.
:::note
Use of variables in [module sources](../../../language/modules/sources.mdx#support-for-variable-and-local-evaluation),
[backend configuration](../../../language/settings/backends/configuration.mdx#variables-and-locals),
or [encryption block](../../../language/state/encryption.mdx#configuration)
requires [assigning values to root module variables](../../../language/values/variables.mdx#assigning-values-to-root-module-variables)
when running `tofu workspace new`.
:::
The command-line flags are all optional. The supported flags are:
* `-lock=false` - Don't hold a state lock during the operation. This is
dangerous if others might concurrently run commands against the same
workspace.
* `-lock-timeout=DURATION` - Duration to retry a state lock. Default 0s.
* `-state=path` - Path to an existing state file to initialize the state of this environment.
* `-var 'NAME=VALUE'` - Sets a value for a single
[input variable](../../../language/values/variables.mdx) declared in the
root module of the configuration. Use this option multiple times to set
more than one variable. Refer to
[Input Variables on the Command Line](../plan.mdx#input-variables-on-the-command-line) for more information.
* `-var-file=FILENAME` - Sets values for potentially many
[input variables](../../../language/values/variables.mdx) declared in the
root module of the configuration, using definitions from a
["tfvars" file](../../../language/values/variables.mdx#variable-definitions-tfvars-files).
Use this option multiple times to include values from more than one file.
There are several other ways to set values for input variables in the root
module, aside from the `-var` and `-var-file` options. Refer to
[Assigning Values to Root Module Variables](../../../language/values/variables.mdx#assigning-values-to-root-module-variables) for more information.
## Example: Create
```

View File

@ -14,10 +14,34 @@ Usage: `tofu workspace select NAME [DIR]`
This command will select another workspace. The named workspace must already
exist.
:::note
Use of variables in [module sources](../../../language/modules/sources.mdx#support-for-variable-and-local-evaluation),
[backend configuration](../../../language/settings/backends/configuration.mdx#variables-and-locals),
or [encryption block](../../../language/state/encryption.mdx#configuration)
requires [assigning values to root module variables](../../../language/values/variables.mdx#assigning-values-to-root-module-variables)
when running `tofu workspace select`.
:::
The supported flags are:
* `-or-create` - If the workspace that is being selected does not exist, create it. Default is `false`.
* `-var 'NAME=VALUE'` - Sets a value for a single
[input variable](../../../language/values/variables.mdx) declared in the
root module of the configuration. Use this option multiple times to set
more than one variable. Refer to
[Input Variables on the Command Line](../plan.mdx#input-variables-on-the-command-line) for more information.
* `-var-file=FILENAME` - Sets values for potentially many
[input variables](../../../language/values/variables.mdx) declared in the
root module of the configuration, using definitions from a
["tfvars" file](../../../language/values/variables.mdx#variable-definitions-tfvars-files).
Use this option multiple times to include values from more than one file.
There are several other ways to set values for input variables in the root
module, aside from the `-var` and `-var-file` options. Refer to
[Assigning Values to Root Module Variables](../../../language/values/variables.mdx#assigning-values-to-root-module-variables) for more information.
## Example
```

View File

@ -464,7 +464,7 @@ the module from the subdirectory. As a result, it is safe for a module in
a sub-directory of a package to use [a local path](#local-paths) to another
module as long as it is in the _same_ package.
## Support for Variable and Local Interpolation
## Support for Variable and Local Evaluation
As projects grow in complexity and requirements, it is prudent to consider using locals and variables in the module source and version fields.
@ -486,5 +486,5 @@ module "compute" {
It is quite easy to then update the version for a patch release, or to switch to a fork of the repository.
:::note
The source and version fields may not contain any references to data in the state or provider defined functions. All value must be able to be resolved during `tofu init` before the state is available.
The source and version fields may not contain any references to data in the state or provider defined functions. All values must be able to be resolved during `tofu init` before the state is available.
:::

View File

@ -174,6 +174,26 @@ or `CONSUL_HTTP_AUTH` environment variables. See the documentation of your
chosen backend to learn how to provide credentials to it outside of its main
configuration.
## Variables and Locals
You may use variables and locals in backend configurations (with restrictions). Backend configuration may not contain any references to data in the state or provider defined functions. All values must be able to be resolved during `tofu init` before the state is available.
:::danger Warning
We recommend against using variables to specify secrets or other sensitive data in your backend configuration. This can leak sensitive credentials if improperly configured.
:::
```hcl
locals {
region = "us-east-1"
}
terraform {
backend "s3" {
region = local.region
}
}
```
## Changing Configuration
You can change your backend configuration at any time. You can change

View File

@ -15,9 +15,13 @@ To configure the cloud CLI integration, add a nested `cloud` block within the `t
Refer to [Using the Cloud Backend](../../cli/cloud/index.mdx) in the OpenTofu CLI documentation for full configuration details, migration instructions, and command line arguments.
```hcl
locals {
org = "example_corp"
}
terraform {
cloud {
organization = "example_corp"
organization = local.org
hostname = "app.example.io"
workspaces {
@ -26,3 +30,7 @@ terraform {
}
}
```
:::note
Cloud fields may not contain any references to data in the state or provider defined functions. All values must be able to be resolved during `tofu init` before the state is available.
:::

View File

@ -112,6 +112,10 @@ When you first configure encryption on an existing project, your state and plan
<CodeBlock language="hcl">{FallbackFromUnencrypted}</CodeBlock>
:::note
Variables and locals can be used in configuration, but may not contain any references to data in the state or provider defined functions. All values must be able to be resolved during `tofu init` before the state is available.
:::
## Rolling back encryption
Similar to the initial setup above, migrating to unencrypted state and plan files is also possible by using the `unencrypted` method as follows: