ResiLien
/
terraform
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

command: Reorganize docs of the local backend's legacy CLI options 

We have these funny extra options that date back to before Terraform even
had remote state, which we've preserved along the way by most recently
incorporating them as special-case overrides for the local backend.

The documentation we had for these has grown less accurate over time as
the details have shifted, and was in many cases missing the requisite
caveats that they are only for the local backend and that backend
configuration is the modern, preferred way to deal with the use-cases they
were intended for.

We always have a bit of a tension with this sort of legacy option because
we want to keep them documented just enough to be useful to someone who
finds an existing script/etc using them and wants to know what they do,
but not to take up so much space that they might distract users from
finding the modern alternative they should consider instead.

As a compromise in that vein here I've created a new section about these
options under the local backend documentation, which then gives us the
space to go into some detail about the various behaviors and interactions
and also to discuss their history and our recommended alternatives. I then
simplified all of the other mentions of these in command documentation
to just link to or refer to the local backend documentation. My hope then
is that folks who need to know what these do can still find the docs, but
that information can be kept out of the direct path of new users so they
can focus on learning about remote backends instead.

This is certainly not the most ideal thing ever, but it seemed like the
best compromise between the competing priorities I described above.
This commit is contained in:
Martin Atkins 2021-03-24 16:17:03 -07:00
parent 550de86135
commit 6f35c2847b
11 changed files with 93 additions and 87 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
command/apply.go
View File

@ -370,10 +370,6 @@ Usage: terraform [global options] destroy [options]
Options:
-backup=path Path to backup the existing state file before
modifying. Defaults to the "-state-out" path with
".backup" extension. Set to "-" to disable backup.
-auto-approve Skip interactive approval before destroying.
-lock=true Lock the state file when locking is supported.
@ -388,13 +384,6 @@ Options:
-refresh=true Update state prior to checking for differences. This
has no effect if a plan file is given to apply.
-state=path Path to read and save state (unless state-out
is specified). Defaults to "terraform.tfstate".
-state-out=path Path to write state to that is different than
"-state". This can be used to preserve the old
state.
-target=resource Resource to target. Operation will be limited to this
resource and its dependencies. This flag can be used
multiple times.
@ -406,7 +395,8 @@ Options:
a file. If "terraform.tfvars" or any ".auto.tfvars"
files are present, they will be automatically loaded.
-state, state-out, and -backup are legacy options supported for the local
backend only. For more information, see the local backend's documentation.
`
return strings.TrimSpace(helpText)
}

15
command/console.go
View File

@ -189,16 +189,15 @@ Usage: terraform [global options] console [options]
Options:
-state=path Path to read state. Defaults to "terraform.tfstate"
-var 'foo=bar' Set a variable in the Terraform configuration. This
flag can be set multiple times.
-var-file=foo Set variables in the Terraform configuration from
a file. If "terraform.tfvars" or any ".auto.tfvars"
files are present, they will be automatically loaded.
-state=path Legacy option for the local backend only. See the local
backend's documentation for more information.
-var 'foo=bar' Set a variable in the Terraform configuration. This
flag can be set multiple times.
-var-file=foo Set variables in the Terraform configuration from
a file. If "terraform.tfvars" or any ".auto.tfvars"
files are present, they will be automatically loaded.
`
return strings.TrimSpace(helpText)
}

14
command/import.go
View File

@ -300,10 +300,6 @@ Usage: terraform [global options] import [options] ADDR ID
Options:
-backup=path Path to backup the existing state file before
modifying. Defaults to the "-state-out" path with
".backup" extension. Set to "-" to disable backup.
-config=path Path to a directory of Terraform configuration files
to use to configure the provider. Defaults to pwd.
If no config files are present, they must be provided
@ -319,13 +315,6 @@ Options:
-no-color If specified, output won't contain any color.
-state=PATH Path to the source state file. Defaults to the configured
backend, or "terraform.tfstate"
-state-out=PATH Path to the destination state file to write to. If this
isn't specified, the source state file will be used. This
can be a new or existing path.
-var 'foo=bar' Set a variable in the Terraform configuration. This
flag can be set multiple times. This is only useful
with the "-config" flag.
@ -338,6 +327,9 @@ Options:
are incompatible. This may result in an unusable
workspace, and should be used with extreme caution.
-state, state-out, and -backup are legacy options supported for the local
backend only. For more information, see the local backend's documentation.
`
return strings.TrimSpace(helpText)
}

5
command/plan.go
View File

@ -221,9 +221,8 @@ Options:
-refresh=true Update state prior to checking for differences.
-state=statefile Path to a Terraform state file to use to look
up Terraform-managed resources. By default it will
use the state "terraform.tfstate" if it exists.
-state=statefile A legacy option used for the local backend only. See the
local backend's documentation for more information.
-target=resource Resource to target. Operation will be limited to this
resource and its dependencies. This flag can be used

12
command/refresh.go
View File

@ -181,10 +181,6 @@ Usage: terraform [global options] refresh [options]
Options:
-backup=path Path to backup the existing state file before
modifying. Defaults to the "-state-out" path with
".backup" extension. Set to "-" to disable backup.
-compact-warnings If Terraform produces any warnings that are not
accompanied by errors, show them in a more compact form
that includes only the summary messages.
@ -197,12 +193,6 @@ Options:
-no-color If specified, output won't contain any color.
-state=path Path to read and save state (unless state-out
is specified). Defaults to "terraform.tfstate".
-state-out=path Path to write updated state file. By default, the
"-state" path will be used.
-target=resource Resource to target. Operation will be limited to this
resource and its dependencies. This flag can be used
multiple times.
@ -214,6 +204,8 @@ Options:
a file. If "terraform.tfvars" or any ".auto.tfvars"
files are present, they will be automatically loaded.
-state, state-out, and -backup are legacy options supported for the local
backend only. For more information, see the local backend's documentation.
`
return strings.TrimSpace(helpText)
}

18
website/docs/cli/commands/apply.html.md
View File

@ -30,9 +30,6 @@ output values then `terraform apply` will exit immediately, without prompting.
The command-line flags are all optional. The list of available flags are:
* `-backup=path` - Path to the backup file. Defaults to `-state-out` with
the ".backup" extension. Disabled by setting to "-".
* `-compact-warnings` - If Terraform produces any warnings that are not
accompanied by errors, show them in a more compact form that includes only
the summary messages.
@ -55,16 +52,6 @@ The command-line flags are all optional. The list of available flags are:
and applying. This has no effect if a plan file is given directly to
apply.
* `-state=path` - Path to the state file. Defaults to "terraform.tfstate".
Ignored when [remote state](/docs/language/state/remote.html) is used. This setting
does not persist and other commands, such as init, may not be aware of the
alternate statefile. To configure an alternate statefile path which is
available to all terraform commands, use the [local backend](/docs/language/settings/backends/local.html).
* `-state-out=path` - Path to write updated state file. By default, the
`-state` path will be used. Ignored when
[remote state](/docs/language/state/remote.html) is used.
* `-target=resource` - A [Resource
Address](/docs/cli/state/resource-addressing.html) to target. For more
information, see
@ -83,6 +70,11 @@ The command-line flags are all optional. The list of available flags are:
specified by `-var-file` override any values set automatically from files in
the working directory. This flag can be used multiple times.
For configurations using
[the `local` backend](/docs/language/settings/backends/local.html) only,
`terraform apply` also accepts the legacy options
[`-state`, `-state-out`, and `-backup`](/docs/language/settings/backends/local.html#command-line-arguments).
## Passing a Different Configuration Directory
Terraform v0.13 and earlier also accepted a directory path in place of the

11
website/docs/cli/commands/console.html.md
View File

@ -26,15 +26,14 @@ If the current state is empty or has not yet been created, the console can be
used to experiment with the expression syntax and
[built-in functions](/docs/language/functions/index.html).
The supported options are:
* `-state=path` - Path to a local state file. Expressions will be evaluated
using values from this state file. If not specified, the state associated
with the current [workspace](/docs/language/state/workspaces.html) is used.
You can close the console with the `exit` command or by pressing Control-C
or Control-D.
For configurations using
[the `local` backend](/docs/language/settings/backends/local.html) only,
`terraform console` accepts the legacy command line option
[`-state`](/docs/language/settings/backends/local.html#command-line-arguments).
## Scripting
The `terraform console` command can be used in non-interactive scripts

16
website/docs/cli/commands/import.html.md
View File

@ -41,10 +41,6 @@ behavior. For more information on this assumption, see
The command-line flags are all optional. The list of available flags are:
* `-backup=path` - Path to backup the existing state file. Defaults to
the `-state-out` path with the ".backup" extension. Set to "-" to disable
backups.
* `-config=path` - Path to directory of Terraform configuration files that
configure the provider for import. This defaults to your working directory.
If this directory contains no Terraform configuration files, the provider
@ -66,13 +62,6 @@ The command-line flags are all optional. The list of available flags are:
use when importing the object. By default, Terraform uses the provider specified
in the configuration for the target resource, and that is the best behavior in most cases.
* `-state=path` - Path to the source state file to read from. Defaults to the
configured backend, or "terraform.tfstate".
* `-state-out=path` - Path to the destination state file to write to. If this
isn't specified the source state file will be used. This can be a new or
existing path.
* `-var 'foo=bar'` - Set a variable in the Terraform configuration. This flag
can be set multiple times. Variable values are interpreted as
[literal expressions](/docs/language/expressions/types.html) in the
@ -93,6 +82,11 @@ in the configuration for the target resource, and that is the best behavior in m
This may result in an unusable Terraform Cloud workspace, and should be used
with extreme caution.
For configurations using
[the `local` backend](/docs/language/settings/backends/local.html) only,
`terraform import` also accepts the legacy options
[`-state`, `-state-out`, and `-backup`](/docs/language/settings/backends/local.html#command-line-arguments).
## Provider Configuration
Terraform will attempt to load configuration files that configure the

8
website/docs/cli/commands/plan.html.md
View File

@ -69,9 +69,6 @@ The available options are:
* `-refresh=true` - Update the state prior to checking for differences.
* `-state=path` - Path to the state file. Defaults to "terraform.tfstate".
Ignored when [remote state](/docs/language/state/remote.html) is used.
* `-target=resource` - A [Resource
Address](/docs/cli/state/resource-addressing.html) to target. This flag can
be used multiple times. See below for more information.
@ -89,6 +86,11 @@ The available options are:
specified by `-var-file` override any values set automatically from files in
the working directory. This flag can be used multiple times.
For configurations using
[the `local` backend](/docs/language/settings/backends/local.html) only,
`terraform plan` accepts the legacy command line option
[`-state`](/docs/language/settings/backends/local.html#command-line-arguments).
## Resource Targeting
The `-target` option can be used to focus Terraform's attention on only a

15
website/docs/cli/commands/refresh.html.md
View File

@ -23,9 +23,6 @@ Usage: `terraform refresh [options]`
The `terraform refresh` command accepts the following options:
* `-backup=path` - Path to the backup file. Defaults to `-state-out` with
the ".backup" extension. Disabled by setting to "-".
* `-compact-warnings` - If Terraform produces any warnings that are not
accompanied by errors, show them in a more compact form that includes only
the summary messages.
@ -42,13 +39,6 @@ The `terraform refresh` command accepts the following options:
[walks the graph](/docs/internals/graph.html#walking-the-graph). Defaults
to 10.
* `-state=path` - Path to read and write the state file to. Defaults to "terraform.tfstate".
Ignored when [remote state](/docs/language/state/remote.html) is used.
* `-state-out=path` - Path to write updated state file. By default, the
`-state` path will be used. Ignored when
[remote state](/docs/language/state/remote.html) is used.
* `-target=resource` - A [Resource
Address](/docs/cli/state/resource-addressing.html) to target. Operation will
be limited to this resource and its dependencies. This flag can be used
@ -66,3 +56,8 @@ The `terraform refresh` command accepts the following options:
first and the `.auto.tfvars` files after in alphabetical order. Any files
specified by `-var-file` override any values set automatically from files in
the working directory. This flag can be used multiple times.
For configurations using
[the `local` backend](/docs/language/settings/backends/local.html) only,
`terraform refresh` also accepts the legacy options
[`-state`, `-state-out`, and `-backup`](/docs/language/settings/backends/local.html#command-line-arguments).

52
website/docs/language/settings/backends/local.html.md
View File

@ -42,3 +42,55 @@ The following configuration options are supported:
* `path` - (Optional) The path to the `tfstate` file. This defaults to
"terraform.tfstate" relative to the root module by default.
* `workspace_dir` - (Optional) The path to non-default workspaces.
## Command Line Arguments
~> This section describes legacy features that we've preserved for backward
compatibility but that we no longer recommend. See below for more details.
For configurations that include a `backend "local"` block or that default to
the local backend by not specifying a backend at all, most commands that either
read or write state snapshots from the backend accept the following
additional arguments:
* `-state=FILENAME` - overrides the state filename when _reading_ the prior
state snapshot.
* `-state-out=FILENAME` - overrides the state filename when _writing_ new state
snapshots.
If you use `-state` without also using `-state-out` then Terraform will
use the `-state` filename for both `-state` and `-state-out`, which means
Terraform will overwrite the input file if it creates a new state snapshot.
* `-backup=FILENAME` - overrides the default filename that the local backend
would normally choose dynamically to create backup files when it writes new
state.
If you use `-state` without also using `-backup` then Terraform will use
the `-state` filename as a filename prefix for generating a backup filename.
You can use `-backup=-` (that is, set the filename to just the ASCII
dash character) to disable the creation of backup files altogether.
These three options are preserved for backward-compatibility with earlier
workflows that predated the introduction of built-in remote state, where
users would write wrapper scripts that fetch prior state before running
Terraform and then save the new state after Terraform exits, in which case
the three arguments would typically all be paths within a temporary
directory used just for one operation.
Because these old workflows predate the introduction of the possibility of
[multiple workspaces](/docs/language/state/workspaces.html), setting them
overrides Terraform's usual behavior of selecting a different state filename
based on the selected workspace. If you use all three of these options then
the selected workspace has no effect on which filenames Terraform will select
for state files, and so you'll need to select different filenames yourself if
you wish to keep workspace state files distinct from one another.
These three options have no effect for configurations that have a different
backend type selected.
We do not recommend using these options in new systems, even if you are running
Terraform in automation. Instead,
[select a different backend which supports remote state](./) and configure it
within your root module, which ensures that everyone working on your
configuration will automatically retrieve and store state in the correct shared
location without any special command line options.