cli+website: -ignore-remote-version docs and other cleanup
We previously had only very short descriptions of what -ignore-remote-version does due to having the documentation for it inline on many different command pages and -help output. Instead, we'll now centralize the documentation about this argument on the remote backend page, and link to it or refer to it from all other locations. This then allows us to spend more words on discussing what Terraform normally does _without_ this option and warning about the consequences of using it. This continues earlier precedent for some local-backend-specific options which we also don't recommend for typical use. While this does make these options a little more "buried" than before, that feels justified given that they are all "exceptional use only" sort of options where users ought to learn about various caveats before using them. While there I also took this opportunity to fix some earlier omissions with the local-backend-specific options and a few other minor consistency tweaks.
This commit is contained in:
parent
b6885923d0
commit
874f1abb2b
|
@ -307,9 +307,9 @@ Options:
|
||||||
|
|
||||||
-allow-missing-config Allow import when no resource configuration block exists.
|
-allow-missing-config Allow import when no resource configuration block exists.
|
||||||
|
|
||||||
-input=true Ask for input for variables if not directly set.
|
-input=false Disable interactive input prompts.
|
||||||
|
|
||||||
-lock=true Lock the state file when locking is supported.
|
-lock Lock the state file when locking is supported.
|
||||||
|
|
||||||
-lock-timeout=0s Duration to retry a state lock.
|
-lock-timeout=0s Duration to retry a state lock.
|
||||||
|
|
||||||
|
@ -323,9 +323,8 @@ Options:
|
||||||
a file. If "terraform.tfvars" or any ".auto.tfvars"
|
a file. If "terraform.tfvars" or any ".auto.tfvars"
|
||||||
files are present, they will be automatically loaded.
|
files are present, they will be automatically loaded.
|
||||||
|
|
||||||
-ignore-remote-version Continue even if remote and local Terraform versions
|
-ignore-remote-version A rare option used for the remote backend only. See
|
||||||
are incompatible. This may result in an unusable
|
the remote backend documentation for more information.
|
||||||
workspace, and should be used with extreme caution.
|
|
||||||
|
|
||||||
-state, state-out, and -backup are legacy options supported for the local
|
-state, state-out, and -backup are legacy options supported for the local
|
||||||
backend only. For more information, see the local backend's documentation.
|
backend only. For more information, see the local backend's documentation.
|
||||||
|
|
|
@ -477,32 +477,15 @@ Options:
|
||||||
-dry-run If set, prints out what would've been moved but doesn't
|
-dry-run If set, prints out what would've been moved but doesn't
|
||||||
actually move anything.
|
actually move anything.
|
||||||
|
|
||||||
-backup=PATH Path where Terraform should write the backup for the
|
-lock Lock the state files when locking is supported.
|
||||||
original state. This can't be disabled. If not set,
|
|
||||||
Terraform will write it to the same path as the
|
|
||||||
statefile with a ".backup" extension.
|
|
||||||
|
|
||||||
-backup-out=PATH Path where Terraform should write the backup for the
|
|
||||||
destination state. This can't be disabled. If not
|
|
||||||
set, Terraform will write it to the same path as the
|
|
||||||
destination state file with a backup extension. This
|
|
||||||
only needs to be specified if -state-out is set to a
|
|
||||||
different path than -state.
|
|
||||||
|
|
||||||
-lock=true Lock the state files when locking is supported.
|
|
||||||
|
|
||||||
-lock-timeout=0s Duration to retry a state lock.
|
-lock-timeout=0s Duration to retry a state lock.
|
||||||
|
|
||||||
-state=PATH Path to the source state file. Defaults to the
|
-ignore-remote-version A rare option used for the remote backend only. See
|
||||||
configured backend, or "terraform.tfstate"
|
the remote backend documentation for more information.
|
||||||
|
|
||||||
-state-out=PATH Path to the destination state file to write to. If
|
-state, state-out, and -backup are legacy options supported for the local
|
||||||
this isn't specified, the source state file will be
|
backend only. For more information, see the local backend's documentation.
|
||||||
used. This can be a new or existing path.
|
|
||||||
|
|
||||||
-ignore-remote-version Continue even if remote and local Terraform versions
|
|
||||||
are incompatible. This may result in an unusable
|
|
||||||
workspace, and should be used with extreme caution.
|
|
||||||
|
|
||||||
`
|
`
|
||||||
return strings.TrimSpace(helpText)
|
return strings.TrimSpace(helpText)
|
||||||
|
|
|
@ -179,21 +179,15 @@ Options:
|
||||||
|
|
||||||
-auto-approve Skip interactive approval.
|
-auto-approve Skip interactive approval.
|
||||||
|
|
||||||
-backup=PATH Path where Terraform should write the backup for the
|
-lock Lock the state files when locking is supported.
|
||||||
state file. This can't be disabled. If not set,
|
|
||||||
Terraform will write it to the same path as the state
|
|
||||||
file with a ".backup" extension.
|
|
||||||
|
|
||||||
-lock=true Lock the state files when locking is supported.
|
|
||||||
|
|
||||||
-lock-timeout=0s Duration to retry a state lock.
|
-lock-timeout=0s Duration to retry a state lock.
|
||||||
|
|
||||||
-state=PATH Path to the state file to update. Defaults to the
|
-ignore-remote-version A rare option used for the remote backend only. See
|
||||||
configured backend, or "terraform.tfstate"
|
the remote backend documentation for more information.
|
||||||
|
|
||||||
-ignore-remote-version Continue even if remote and local Terraform versions
|
-state, state-out, and -backup are legacy options supported for the local
|
||||||
are incompatible. This may result in an unusable
|
backend only. For more information, see the local backend's documentation.
|
||||||
workspace, and should be used with extreme caution.
|
|
||||||
|
|
||||||
`
|
`
|
||||||
return strings.TrimSpace(helpText)
|
return strings.TrimSpace(helpText)
|
||||||
|
|
|
@ -235,23 +235,15 @@ Options:
|
||||||
-allow-missing If specified, the command will succeed (exit code 0)
|
-allow-missing If specified, the command will succeed (exit code 0)
|
||||||
even if the resource is missing.
|
even if the resource is missing.
|
||||||
|
|
||||||
-backup=path Path to backup the existing state file before
|
-lock Lock the state file when locking is supported.
|
||||||
modifying. Defaults to the "-state-out" path with
|
|
||||||
".backup" extension. Set to "-" to disable backup.
|
|
||||||
|
|
||||||
-lock=true Lock the state file when locking is supported.
|
|
||||||
|
|
||||||
-lock-timeout=0s Duration to retry a state lock.
|
-lock-timeout=0s Duration to retry a state lock.
|
||||||
|
|
||||||
-state=path Path to read and save state (unless state-out
|
-ignore-remote-version A rare option used for the remote backend only. See
|
||||||
is specified). Defaults to "terraform.tfstate".
|
the remote backend documentation for more information.
|
||||||
|
|
||||||
-state-out=path Path to write updated state file. By default, the
|
-state, state-out, and -backup are legacy options supported for the local
|
||||||
"-state" path will be used.
|
backend only. For more information, see the local backend's documentation.
|
||||||
|
|
||||||
-ignore-remote-version Continue even if remote and local Terraform versions
|
|
||||||
are incompatible. This may result in an unusable
|
|
||||||
workspace, and should be used with extreme caution.
|
|
||||||
|
|
||||||
`
|
`
|
||||||
return strings.TrimSpace(helpText)
|
return strings.TrimSpace(helpText)
|
||||||
|
|
|
@ -200,23 +200,15 @@ Options:
|
||||||
-allow-missing If specified, the command will succeed (exit code 0)
|
-allow-missing If specified, the command will succeed (exit code 0)
|
||||||
even if the resource is missing.
|
even if the resource is missing.
|
||||||
|
|
||||||
-backup=path Path to backup the existing state file before
|
-lock Lock the state file when locking is supported.
|
||||||
modifying. Defaults to the "-state-out" path with
|
|
||||||
".backup" extension. Set to "-" to disable backup.
|
|
||||||
|
|
||||||
-lock=true Lock the state file when locking is supported.
|
|
||||||
|
|
||||||
-lock-timeout=0s Duration to retry a state lock.
|
-lock-timeout=0s Duration to retry a state lock.
|
||||||
|
|
||||||
-state=path Path to read and save state (unless state-out
|
-ignore-remote-version A rare option used for the remote backend only. See
|
||||||
is specified). Defaults to "terraform.tfstate".
|
the remote backend documentation for more information.
|
||||||
|
|
||||||
-state-out=path Path to write updated state file. By default, the
|
-state, state-out, and -backup are legacy options supported for the local
|
||||||
"-state" path will be used.
|
backend only. For more information, see the local backend's documentation.
|
||||||
|
|
||||||
-ignore-remote-version Continue even if remote and local Terraform versions
|
|
||||||
are incompatible. This may result in an unusable
|
|
||||||
workspace, and should be used with extreme caution.
|
|
||||||
|
|
||||||
`
|
`
|
||||||
return strings.TrimSpace(helpText)
|
return strings.TrimSpace(helpText)
|
||||||
|
|
|
@ -77,10 +77,11 @@ in the configuration for the target resource, and that is the best behavior in m
|
||||||
the working directory. This flag can be used multiple times. This is only
|
the working directory. This flag can be used multiple times. This is only
|
||||||
useful with the `-config` flag.
|
useful with the `-config` flag.
|
||||||
|
|
||||||
* `-ignore-remote-version` - When using the enhanced remote backend with
|
For configurations using
|
||||||
Terraform Cloud, continue even if remote and local Terraform versions differ.
|
[the `remote` backend](/docs/language/settings/backends/remote.html)
|
||||||
This may result in an unusable Terraform Cloud workspace, and should be used
|
only, `terraform import`
|
||||||
with extreme caution.
|
also accepts the option
|
||||||
|
[`-ignore-remote-version`](/docs/language/settings/backends/remote.html#command-line-arguments).
|
||||||
|
|
||||||
For configurations using
|
For configurations using
|
||||||
[the `local` backend](/docs/language/settings/backends/local.html) only,
|
[the `local` backend](/docs/language/settings/backends/local.html) only,
|
||||||
|
|
|
@ -38,29 +38,19 @@ This command requires a source and destination address of the item to move.
|
||||||
Addresses are
|
Addresses are
|
||||||
in [resource addressing format](/docs/cli/state/resource-addressing.html).
|
in [resource addressing format](/docs/cli/state/resource-addressing.html).
|
||||||
|
|
||||||
The command-line flags are all optional. The list of available flags are:
|
This command doesn't normally accept any command line options, except in
|
||||||
|
the special situations described in the following paragraphs.
|
||||||
|
|
||||||
* `-backup=path` - Path where Terraform should write the backup for the
|
For configurations using
|
||||||
original state. This can't be disabled. If not set, Terraform will write it
|
[the `remote` backend](/docs/language/settings/backends/remote.html)
|
||||||
to the same path as the statefile with a ".backup" extension.
|
only, `terraform state mv`
|
||||||
|
also accepts the option
|
||||||
|
[`-ignore-remote-version`](/docs/language/settings/backends/remote.html#command-line-arguments).
|
||||||
|
|
||||||
* `-backup-out=path` - Path where Terraform should write the backup for the
|
For configurations using
|
||||||
destination state. This can't be disabled. If not set, Terraform will write
|
[the `local` state mv](/docs/language/settings/backends/local.html) only,
|
||||||
it to the same path as the destination state file with a backup extension.
|
`terraform taint` also accepts the legacy options
|
||||||
This only needs to be specified if -state-out is set to a different path than
|
[`-state`, `-state-out`, and `-backup`](/docs/language/settings/backends/local.html#command-line-arguments).
|
||||||
-state.
|
|
||||||
|
|
||||||
* `-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.
|
|
||||||
|
|
||||||
* `-ignore-remote-version` - When using the enhanced remote backend with
|
|
||||||
Terraform Cloud, continue even if remote and local Terraform versions differ.
|
|
||||||
This may result in an unusable Terraform Cloud workspace, and should be used
|
|
||||||
with extreme caution.
|
|
||||||
|
|
||||||
## Example: Rename a Resource
|
## Example: Rename a Resource
|
||||||
|
|
||||||
|
|
|
@ -43,9 +43,8 @@ Both of these safety checks can be disabled with the `-force` flag.
|
||||||
**This is not recommended.** If you disable the safety checks and are
|
**This is not recommended.** If you disable the safety checks and are
|
||||||
pushing state, the destination state will be overwritten.
|
pushing state, the destination state will be overwritten.
|
||||||
|
|
||||||
Other available flags:
|
For configurations using
|
||||||
|
[the `remote` backend](/docs/language/settings/backends/remote.html)
|
||||||
* `-ignore-remote-version` - When using the enhanced remote backend with
|
only, `terraform state push`
|
||||||
Terraform Cloud, continue even if remote and local Terraform versions differ.
|
also accepts the option
|
||||||
This may result in an unusable Terraform Cloud workspace, and should be used
|
[`-ignore-remote-version`](/docs/language/settings/backends/remote.html#command-line-arguments).
|
||||||
with extreme caution.
|
|
||||||
|
|
|
@ -23,25 +23,25 @@ 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
|
changes. The backup cannot be disabled. Due to the destructive nature
|
||||||
of this command, backups are required.
|
of this command, backups are required.
|
||||||
|
|
||||||
The command-line flags are all optional. The list of available flags are:
|
This command also accepts the following options:
|
||||||
|
|
||||||
* `-auto-approve` - Skip interactive approval.
|
* `-auto-approve` - Skip interactive approval.
|
||||||
|
|
||||||
* `-backup=path` - Path where Terraform should write the backup for the
|
|
||||||
original state. This can't be disabled. If not set, Terraform will write it
|
|
||||||
to the same path as the statefile with a ".backup" extension.
|
|
||||||
|
|
||||||
* `-lock=true`- Lock the state files when locking is supported.
|
* `-lock=true`- Lock the state files when locking is supported.
|
||||||
|
|
||||||
* `-lock-timeout=0s` - Duration to retry a state lock.
|
* `-lock-timeout=0s` - Duration to retry a state lock.
|
||||||
|
|
||||||
* `-state=path` - Path to the source state file to read from. Defaults to the
|
For configurations using
|
||||||
configured backend, or "terraform.tfstate".
|
[the `remote` backend](/docs/language/settings/backends/remote.html)
|
||||||
|
only, `terraform state replace-provider`
|
||||||
|
also accepts the option
|
||||||
|
[`-ignore-remote-version`](/docs/language/settings/backends/remote.html#command-line-arguments).
|
||||||
|
|
||||||
|
For configurations using
|
||||||
|
[the `local` state rm](/docs/language/settings/backends/local.html) only,
|
||||||
|
`terraform state replace-provider` also accepts the legacy options
|
||||||
|
[`-state`, `-state-out`, and `-backup`](/docs/language/settings/backends/local.html#command-line-arguments).
|
||||||
|
|
||||||
* `-ignore-remote-version` - When using the enhanced remote backend with
|
|
||||||
Terraform Cloud, continue even if remote and local Terraform versions differ.
|
|
||||||
This may result in an unusable Terraform Cloud workspace, and should be used
|
|
||||||
with extreme caution.
|
|
||||||
|
|
||||||
## Example
|
## Example
|
||||||
|
|
||||||
|
|
|
@ -41,20 +41,19 @@ This command requires one or more addresses that point to a resources in the
|
||||||
state. Addresses are
|
state. Addresses are
|
||||||
in [resource addressing format](/docs/cli/state/resource-addressing.html).
|
in [resource addressing format](/docs/cli/state/resource-addressing.html).
|
||||||
|
|
||||||
The command-line flags are all optional. The list of available flags are:
|
This command doesn't normally accept any command line options, except in
|
||||||
|
the special situations described in the following paragraphs.
|
||||||
|
|
||||||
* `-backup=path` - Path where Terraform should write the backup state. This
|
For configurations using
|
||||||
can't be disabled. If not set, Terraform will write it to the same path as
|
[the `remote` backend](/docs/language/settings/backends/remote.html)
|
||||||
the statefile with a backup extension.
|
only, `terraform state rm`
|
||||||
|
also accepts the option
|
||||||
|
[`-ignore-remote-version`](/docs/language/settings/backends/remote.html#command-line-arguments).
|
||||||
|
|
||||||
* `-state=path` - Path to a Terraform state file to use to look up
|
For configurations using
|
||||||
Terraform-managed resources. By default it will use the configured backend,
|
[the `local` state rm](/docs/language/settings/backends/local.html) only,
|
||||||
or the default "terraform.tfstate" if it exists.
|
`terraform state rm` also accepts the legacy options
|
||||||
|
[`-state`, `-state-out`, and `-backup`](/docs/language/settings/backends/local.html#command-line-arguments).
|
||||||
* `-ignore-remote-version` - When using the enhanced remote backend with
|
|
||||||
Terraform Cloud, continue even if remote and local Terraform versions differ.
|
|
||||||
This may result in an unusable Terraform Cloud workspace, and should be used
|
|
||||||
with extreme caution.
|
|
||||||
|
|
||||||
## Example: Remove a Resource
|
## Example: Remove a Resource
|
||||||
|
|
||||||
|
|
|
@ -67,10 +67,11 @@ This command accepts the following options:
|
||||||
returning an error. The duration syntax is a number followed by a time
|
returning an error. The duration syntax is a number followed by a time
|
||||||
unit letter, such as "3s" for three seconds.
|
unit letter, such as "3s" for three seconds.
|
||||||
|
|
||||||
* `-ignore-remote-version` - When using the enhanced remote backend with
|
For configurations using
|
||||||
Terraform Cloud, continue even if remote and local Terraform versions differ.
|
[the `remote` backend](/docs/language/settings/backends/remote.html)
|
||||||
This may result in an unusable Terraform Cloud workspace, and should be used
|
only, `terraform taint`
|
||||||
with extreme caution.
|
also accepts the option
|
||||||
|
[`-ignore-remote-version`](/docs/language/settings/backends/remote.html#command-line-arguments).
|
||||||
|
|
||||||
For configurations using
|
For configurations using
|
||||||
[the `local` backend](/docs/language/settings/backends/local.html) only,
|
[the `local` backend](/docs/language/settings/backends/local.html) only,
|
||||||
|
|
|
@ -62,12 +62,13 @@ This command also accepts the following options:
|
||||||
if you are running Terraform in a context where its output will be
|
if you are running Terraform in a context where its output will be
|
||||||
rendered by a system that cannot interpret terminal formatting.
|
rendered by a system that cannot interpret terminal formatting.
|
||||||
|
|
||||||
* `-ignore-remote-version` - When using the enhanced remote backend with
|
For configurations using
|
||||||
Terraform Cloud, continue even if remote and local Terraform versions differ.
|
[the `remote` backend](/docs/language/settings/backends/remote.html)
|
||||||
This may result in an unusable Terraform Cloud workspace, and should be used
|
only, `terraform untaint`
|
||||||
with extreme caution.
|
also accepts the option
|
||||||
|
[`-ignore-remote-version`](/docs/language/settings/backends/remote.html#command-line-arguments).
|
||||||
|
|
||||||
For configurations using
|
For configurations using
|
||||||
[the `local` backend](/docs/language/settings/backends/local.html) only,
|
[the `local` backend](/docs/language/settings/backends/local.html) only,
|
||||||
`terraform taint` also accepts the legacy options
|
`terraform untaint` also accepts the legacy options
|
||||||
[`-state`, `-state-out`, and `-backup`](/docs/language/settings/backends/local.html#command-line-arguments).
|
[`-state`, `-state-out`, and `-backup`](/docs/language/settings/backends/local.html#command-line-arguments).
|
||||||
|
|
|
@ -195,6 +195,26 @@ The following configuration options are supported:
|
||||||
data source that retrieves state from another Terraform Cloud workspace. The `prefix` key is only
|
data source that retrieves state from another Terraform Cloud workspace. The `prefix` key is only
|
||||||
intended for use when configuring an instance of the remote backend.
|
intended for use when configuring an instance of the remote backend.
|
||||||
|
|
||||||
|
## Command Line Arguments
|
||||||
|
|
||||||
|
For configurations that include a `backend "remote"` block, commands that
|
||||||
|
make local modifications to Terraform state and then push them back up to
|
||||||
|
the remote workspace accept the following option to modify that behavior:
|
||||||
|
|
||||||
|
* `-ignore-remote-version` - Override checking that the local and remote
|
||||||
|
Terraform versions agree, making an operation proceed even when there is
|
||||||
|
a mismatch.
|
||||||
|
|
||||||
|
Normally state-modification operations require using a local version of
|
||||||
|
Terraform CLI which is compatible with the Terraform version selected
|
||||||
|
for the remote workspace as part of its settings. This is to avoid the
|
||||||
|
local operation creating a new state snapshot which the workspace's
|
||||||
|
remote execution environment would then be unable to decode.
|
||||||
|
|
||||||
|
Overriding this check can result in a Terraform Cloud workspace that is
|
||||||
|
no longer able to complete remote operations, so we recommend against
|
||||||
|
using this option.
|
||||||
|
|
||||||
## Excluding Files from Upload with .terraformignore
|
## Excluding Files from Upload with .terraformignore
|
||||||
|
|
||||||
-> **Version note:** `.terraformignore` support was added in Terraform 0.12.11.
|
-> **Version note:** `.terraformignore` support was added in Terraform 0.12.11.
|
||||||
|
|
Loading…
Reference in New Issue