mirror of
https://github.com/opentffoundation/opentf.git
synced 2026-02-15 13:00:32 -05:00
86 lines
4.4 KiB
Plaintext
86 lines
4.4 KiB
Plaintext
---
|
|
description: >-
|
|
Learn how to use the OpenTofu CLI to migrate local or remote state to a Cloud Backend.
|
|
---
|
|
|
|
# Initializing and Migrating
|
|
|
|
After [configuring cloud backend settings](settings.mdx) for a working directory, you must run `tofu init` to finish setting up. If the working directory has no existing OpenTofu state, you can start using OpenTofu with a cloud backend right away.
|
|
|
|
When you run `tofu init` in the following scenarios, OpenTofu will ask you to choose whether or not to migrate state from any existing workspaces.
|
|
|
|
1. [**Migrating from local state or state backends:**](#migrating-from-local-state-or-state-backends) If the working directory already has state data in one or more workspaces, OpenTofu will ask if you would like to migrate that state to new cloud backend workspaces.
|
|
|
|
1. [**Migrating from the `remote` backend:**](#migrating-from-the-remote-backend) If the working directory was already connected to a cloud backend with the `remote` backend, OpenTofu can continue using the same cloud backend workspaces. You will need to switch the `remote` backend block to the `cloud` block.
|
|
|
|
## Migrating from Local State or State Backends
|
|
|
|
If the working directory already has state data available (using either local state or a [state backend](../../language/settings/backends/configuration.mdx)), OpenTofu asks your approval to migrate
|
|
that state to the cloud backend. You will need permission to manage workspaces in the destination cloud backend organization. This process is interactive and self-documenting, and resembles
|
|
moving between state backends.
|
|
|
|
OpenTofu may also prompt you to rename your workspaces during the migration, to either give a name to
|
|
the unnamed `default` workspace (the cloud backend requires all workspaces to have a name) or give
|
|
your workspace names more contextual information. Unlike OpenTofu CLI-only workspaces, which represent
|
|
multiple environments associated with the same configuration (e.g. production, staging, development),
|
|
cloud backend workspaces can represent totally independent configurations, and must have unique names within the cloud backend organization.
|
|
|
|
Because of this, OpenTofu will prompt you to rename the working directory's workspaces
|
|
according to a pattern relative to their existing names. This can indicate the fact that these specific workspaces share configuration. A typical strategy is
|
|
`<COMPONENT>-<ENVIRONMENT>-<REGION>` (e.g., `networking-prod-us-east`,
|
|
`networking-staging-us-east`).
|
|
|
|
## Migrating from the `remote` Backend
|
|
|
|
If the working directory was already connected to a cloud backend with the `remote` backend, OpenTofu can continue using the same cloud backend workspaces. The local names shown for those workspaces will change to match their remote names.
|
|
|
|
The [`remote` backend](../../language/settings/backends/remote.mdx) was the primary implementation for cloud backends for Terraform versions 0.11.13 through 1.0.x. We recommend using the native `cloud` integration for OpenTofu and Terraform versions 1.1 or later, as it provides an improved user experience and various enhancements.
|
|
|
|
### Block Replacement
|
|
|
|
When switching from the `remote` backend to a `cloud` block, OpenTofu will continue using the same
|
|
set of cloud backend workspaces. Replace your `backend "remote"` block with an equivalent `cloud`
|
|
block.
|
|
|
|
#### Single Workspace
|
|
|
|
If you were using a single workspace with the `name` argument, change the block
|
|
label to `cloud`.
|
|
|
|
```diff
|
|
terraform {
|
|
- backend "remote" {
|
|
+ cloud {
|
|
organization = "my-org"
|
|
|
|
workspaces {
|
|
name = "my-app-prod"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Multiple Workspaces
|
|
|
|
If you were using multiple workspaces with the `prefix` argument, replace it with a `cloud` block that uses the `tags` argument. You may specify any number of tags to distinguish the workspaces for your working directory, but a good starting point may be to use whatever the prefix was before.
|
|
|
|
The tags you configure do not need to be present on the existing workspaces. When you initialize, OpenTofu will add the specified tags to the workspaces if necessary.
|
|
|
|
```diff
|
|
terraform {
|
|
- backend "remote" {
|
|
+ cloud {
|
|
organization = "my-org"
|
|
|
|
workspaces {
|
|
- prefix = "my-app-"
|
|
+ tags = ["app:mine"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
:::warning
|
|
Because the `cloud` block does not support the `prefix` argument, once you migrate, you must refer to workspaces by their full name when using the OpenTofu CLI. For example, rather than `tofu workspace select prod`, you must run the command `tofu workspace select my-app-prod`.
|
|
:::
|