State Migration
For State Migration to work, please make sure the following conditions are met:
- if you're migrating the state from another Remote Backend, make sure you are logged in to the previous Remote Backend
- Terraform is configured to run with the current backend - this can be done by running
terraform init
(this is needed for Terraform to detect the changes in the Backend configuration) - You're logged in to the env0 Remote Backend
- You have your Organization ID and your Project ID
Migrating the state is fairly simple. All you have to do is:
- Configure the Remote Backend in your Terraform code:
terraform {
cloud {
hostname = "backend.api.env0.com"
organization = "<YOUR_ORGANIZATION_ID>.<YOUR_PROJECT_ID>"
workspaces {
name = "<YOUR_WORKSPACE_NAME>"
}
}
}
- Run
terraform init -migrate-state -force-copy
That's it!
The migration results with:
- A new Environment in the given Project, its name is as the given Workspace Name
- The Environment's current state will be exactly like the current state of your previous Backend
Insert Missing Definitions Into Your Generated Environment
Since Terraform sends limited data for creating the Environment, there are a few things the generated Environment and its matching Template are missing.
The Environment is missing Continuous Deployment configuration.
The Template is missing VCS configuration (repository, branch, terraform folder).
We recommend filling in those missing definitions so you can deploy your Environment remotely in env0 and fully leverage all of the env0 capabilities and features.
Migrating from env0 local to env0 remote state
Note: env0 local refers to Tofu/Terraform code which has been deployed in env0 without any backend configuration, and the env0 remote backend disabled.
- Find the environment in which you want to migrate
- Ensure your Terraform version is 1.x or above
- Navigate to Settings, enable Use env0 Remote Backend, and save
- Use the burger menu in the top right and select Run a task
- In the bash command section type
terraform init -migrate-state -force-copy
and click Run task. - Redeploy the Environment to ensure no changes are seen.
Migrating from TFC/TFE to env0 remote state
Option 1: Migrating the workspace using the env0 migration script
The env0 migration tool allows migrating states from TFC, as well as the workspaces themselves, and other configuration from your TFC account.
The tool is open source and can be found here: https://github.com/env0/env0-migration-tool/tree/main/TFC, to see the exact instructions.
Option 2: Migrating the workspace using env0
- Update your TFC/TFE workspace settings from Execution mode to Local mode, and Save settings. Note: Before you change this setting, make a quick note of your variable configurations in TFC/E.
- In TFC/TFE, go to User Profile and head over to User Settings. Select Tokens, then Create an API token and hit Save to save the token for the next step.
- Ensure the API token has the correct privileges. This typically means a User or Team token needs to be created, not an Organization token.
- In env0, create a new env0 environment (from VCS Environment)
- IaC Type: Terraform
- Under Advanced, Select the same Terraform Version used with TFC. Select NEXT
- Under VCS: Select the same Git Repo, Branch (aka Revision), and Folder as configured for TFC/E. Select NEXT
- Under Variables: Add any variables used in your TFC/E workspace.
- Add an environment variable:
TF_TOKEN_app_terraform_io
(orTF_TOKEN_your_tfe_host
if you are using a custom hostname) and add the token created in step 3. This variable can be saved at the Organization or Project level if you are planning on migrating more than one workspace manually.
Note: This configuration only works for TF v. 1.2+ - Add an environment variable:
ENV0_SKIP_WORKSPACE=true
This setting will avoid the errorworkspaces not supported
- when using TFC/E remote backend. - Copy the existing workspace name you're using in TFC/E. e.g. my-prod-resource to the Environment Details - Workspace Name. Note: this is not the ws- ID, but the name you provided.
- Do NOT select Use env0 remote Backend â we will do this later.
- Run the environment. You should expect to see no changes (assuming you've made no other changes to the code or variables); TFC/E
- Update the Remote Backend to use env0's remote backend and then push the code to Git. This may start a new deployment.
- Your Organization ID can be found under Organization Settings.
You may receive a Deploy Failed (Error: Backend configuration changed) error which is to be expected. We will fix this in the next step.
cloud {
hostname = "backend.api.env0.com"
organization = "<YOUR_ORGANIZATION_ID>.<YOUR_PROJECT_ID>"
workspaces {
name = "my-prod-resource"
}
}
- Under Environment > Settings: Check "Use env0 remote Backend" and "SAVE"
- Re-deploy with the following Environment Variables:
- Add
TF_CLI_ARGS_init=-migrate-state -force-copy
- Delete
ENV0_SKIP_WORKSPACE=true
- Your deployment logs under Terraform Init should show this or a similar message:
Backend configuration changed!
Terraform has detected that the configuration specified for the backend
has changed. Terraform will now check for existing state in the backends.Successfully configured the backend "remote"! Terraform will automatically
use this backend unless the backend configuration changes.
- (Optional) Redeploy and remove the
TF_TOKEN_app_terraform_io/TF_TOKEN_your_tfe_host
andTF_CLI_ARGS_init
to clean up. - (Optional) The
backend remote
block can be removed if you are not using the remote plan feature. - Your migration is now complete! đ
Option 2: Migrating the workspace using a local terminal/script
See tool here:
https://github.com/env0/env0-migration-tool
Migrating from env0 remote backend to a third-party bucket
- Add the remote backend code block to the environment you want to migrate.
terraform {
cloud {
hostname = "backend.api.env0.com"
organization = "<YOUR_ORGANIZATION_ID>.<YOUR_PROJECT_ID>"
workspaces {
name = "<YOUR_WORKSPACE_NAME>"
}
}
}
- Remote login to env0:
- Run
terraform login backend.api.env0.com
- Enter
yes
when prompted - Insert your
token
(See Generating a Token)
- Run
- Run
terraform plan
and ensure you are working in the correct environment.- You should see this trigger a plan in env0
- (Optional) Run
terraform pull > backup.state
to pull the state to a local file. - Remove the remote backend code block from step 1.
- Add a backend code block for the new remote backend of your choosing (Terraform Backends).
- Run
terraform init -migrate-state
, respond to the prompt withyes
- Run
terraform plan
. You should expect to see no or minimal changes. - (If necessary, in conjunction with step 4) Run
terraform state push backup.state
to push your state to your new remote backend. - The state has now been migrated to your configured backend.
- If you are moving away from env0, the environment can be marked as inactive.
- If you are moving states between env0, the old environment will need to be marked as inactive and a new environment will have to be created.
Troubleshooting
Error: Backend configuration changed â make sure that you add an Environment Variable withTF_CLI_ARGS_init=-migrate-state -force-copy
âī¸ Suggested Blog Content
Updated about 1 month ago