ResiLien
/
terraform
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
terraform/website/docs/cli/commands/state/replace-provider.mdx

53 lines
1.8 KiB
Plaintext
Raw Normal View History

website: Add docs for state replace-provider
2020-04-23 17:41:57 +02:00
---
migrate docs to mdx
2021-12-15 03:41:17 +01:00
page_title: 'Command: state replace-provider'
description: >-
The `terraform state replace-provider` command replaces the provider for
resources in the Terraform state.
website: Add docs for state replace-provider
2020-04-23 17:41:57 +02:00
---
# Command: state replace-provider
The `terraform state replace-provider` command is used to replace the provider
migrate docs to mdx
2021-12-15 03:41:17 +01:00
for resources in a [Terraform state](/language/state).
website: Add docs for state replace-provider
2020-04-23 17:41:57 +02:00
## Usage
Usage: `terraform state replace-provider [options] FROM_PROVIDER_FQN TO_PROVIDER_FQN`
This command will update all resources using the "from" provider, setting the
provider to the specified "to" provider. This allows changing the source of a
provider which currently has resources in state.
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.
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.
2021-05-11 20:37:32 +02:00
This command also accepts the following options:
website: Add docs for state replace-provider
2020-04-23 17:41:57 +02:00
* `-auto-approve` - Skip interactive approval.
command: use -lock=false consistently in -help output Previously the docs for this were rather confusing because they showed an option to turn _on_ state locking, even though it's on by default. Instead, we'll now show -lock=false in all cases and document it as _disabling_ the default locking. While working on this I also noticed that the equivalent docs on the website were differently inconsistent. I've not made them fully consistent here but at least moreso than they were before.
2021-05-12 18:05:03 +02:00
* `-lock=false` - Don't hold a state lock during the operation. This is
migrate docs to mdx
2021-12-15 03:41:17 +01:00
dangerous if others might concurrently run commands against the same
workspace.
website: Add docs for state replace-provider
2020-04-23 17:41:57 +02:00
* `-lock-timeout=0s` - Duration to retry a state lock.
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.
2021-05-11 20:37:32 +02:00
For configurations using
migrate docs to mdx
2021-12-15 03:41:17 +01:00
[the `remote` backend](/language/settings/backends/remote)
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.
2021-05-11 20:37:32 +02:00
only, `terraform state replace-provider`
also accepts the option
migrate docs to mdx
2021-12-15 03:41:17 +01:00
[`-ignore-remote-version`](/language/settings/backends/remote#command-line-arguments).
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.
2021-05-11 20:37:32 +02:00
For configurations using
migrate docs to mdx
2021-12-15 03:41:17 +01:00
[the `local` state rm](/language/settings/backends/local) only,
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.
2021-05-11 20:37:32 +02:00
`terraform state replace-provider` also accepts the legacy options
migrate docs to mdx
2021-12-15 03:41:17 +01:00
[`-state`, `-state-out`, and `-backup`](/language/settings/backends/local#command-line-arguments).
backend: Validate remote backend Terraform version When using the enhanced remote backend, a subset of all Terraform operations are supported. Of these, only plan and apply can be executed on the remote infrastructure (e.g. Terraform Cloud). Other operations run locally and use the remote backend for state storage. This causes problems when the local version of Terraform does not match the configured version from the remote workspace. If the two versions are incompatible, an `import` or `state mv` operation can cause the remote workspace to be unusable until a manual fix is applied. To prevent this from happening accidentally, this commit introduces a check that the local Terraform version and the configured remote workspace Terraform version are compatible. This check is skipped for commands which do not write state, and can also be disabled by the use of a new command-line flag, `-ignore-remote-version`. Terraform version compatibility is defined as: - For all releases before 0.14.0, local must exactly equal remote, as two different versions cannot share state; - 0.14.0 to 1.0.x are compatible, as we will not change the state version number until at least Terraform 1.1.0; - Versions after 1.1.0 must have the same major and minor versions, as we will not change the state version number in a patch release. If the two versions are incompatible, a diagnostic is displayed, advising that the error can be suppressed with `-ignore-remote-version`. When this flag is used, the diagnostic is still displayed, but as a warning instead of an error. Commands which will not write state can assert this fact by calling the helper `meta.ignoreRemoteBackendVersionConflict`, which will disable the checks. Those which can write state should instead call the helper `meta.remoteBackendVersionCheck`, which will return diagnostics for display. In addition to these explicit paths for managing the version check, we have an implicit check in the remote backend's state manager initialization method. Both of the above helpers will disable this check. This fallback is in place to ensure that future code paths which access state cannot accidentally skip the remote version check.
2020-11-13 22:43:56 +01:00
website: Add docs for state replace-provider
2020-04-23 17:41:57 +02:00
## Example
The example below replaces the `hashicorp/aws` provider with a fork by `acme`, hosted at a private registry at `registry.acme.corp`:
```shell
$ terraform state replace-provider hashicorp/aws registry.acme.corp/acme/aws
```