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
- Find the environment in which you want to migrate state.
- Navigate to Settings and enable "Use env0 Remote Backend" and save.
- Use the burger menu in the top right and "Run a task".
- In the bash command section type "terraform init -migrate-state -force-copy" and click "Run a task".
- Ensure the Terraform version is 1.x or above.
- Redeploy the environment to ensure no changes are seen.
Migrating from TFC/TFE to env0 remote state
Option 1: Migrating the workspace using env0
- Update your TFC/TFE workspace settings, "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, "Create an API token" from your User Profile > User Settings > Tokens. 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
and add the token created in step 3. This variable can be saved at the Org 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. - Under Environment Details
- Workspace Name: Copy the existing workspace name you're using in TFC/E. e.g.
my-prod-resource
. Note; this is not thews-
ID, but the name you provided.
- Do NOT select the "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 have a message like
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 bucket storage of your choosing (Terraform Backends).
- Run
terraform init -migrate-state
, Respond to the prompt withyes
- Run
terraform plan
and 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 bucket storage. - The state has now been migrated to S3.
- If you are moving away from env0, then 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 you add an Environment Variable with
TF_CLI_ARGS_init=-migrate-state -force-copy
âī¸ Suggested Blog Content
Updated 4 months ago