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:

  1. 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>"
    }
  }
}
  1. 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

  1. 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.
  2. In TFC/TFE, "Create an API token" from your User Profile > User Settings > Tokens. Save the token for the next step.
  3. Ensure the API token has the correct privileges. This typically means a User or Team token needs to be created, not an Organization token.
  4. In env0, create a new env0 environment (from VCS Environment)
    1. IaC Type: Terraform
    2. Under "Advanced" Select the same Terraform Version used with TFC. Select NEXT
    3. Under VCS: Select the same Git Repo, Branch (aka Revision), and Folder as configured for TFC/E. Select NEXT
    4. Under Variables: Add any variables used in your TFC/E workspace.
    5. Add an environment variable: TF_TOKEN_app_terraform_io or TF_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+
    6. Add an environment variable: ENV0_SKIP_WORKSPACE=true This setting will avoid the error workspaces not supported - when using TFC/E remote backend.
    7. Under Environment Details
    8. Workspace Name: Copy the existing workspace name you're using in TFC/E. e.g. my-prod-resource. Note; this is not the ws- ID, but the name you provided.
  1. Do NOT select the "Use env0 remote Backend" - we will do this later.
  2. Run the environment - You should expect to see no changes (assuming you've made no other changes to the code or variables); TFC/E
  3. Update the Remote Backend to use env0's remote backend and then push the code to Git. This may start a new deployment.
  4. 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"
    }
  }
  1. Under Environment > Settings: Check "Use env0 remote Backend" and "SAVE"

  1. Re-deploy with the following Environment Variables:
  • add TF_CLI_ARGS_init=-migrate-state -force-copy
  • delete ENV0_SKIP_WORKSPACE=true
  1. 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.

  1. (Optional) Redeploy and remove the TF_TOKEN_app_terraform_io/TF_TOKEN_your_tfe_host and TF_CLI_ARGS_init to clean up.
  2. (Optional) The backend "remote" block can be removed if you are not using the remote plan feature.
  3. Your migration is now complete! :tada:

Option 2: Migrating the workspace using a local terminal/script

See the code example here:
https://github.com/env0/customer-tools/tree/main/migrations/tfc-to-env0-migration/tfc-local-state

Migrating from env0 remote backend to a third-party bucket

  1. 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>"
    }
  }
}
  1. Remote login to env0.
    1. Run terraform login backend.api.env0.com
    2. Enter yes when prompted
    3. Insert your token (See Generating a Token)
  2. Run terraform plan and ensure you are working in the correct environment.
    1. You should see this trigger a plan in env0
  3. (Optional) Run terraform pull > backup.state to pull the state to a local file.
  4. Remove the remote backend code block from step 1.
  5. Add a backend code block for the bucket storage of your choosing (Terraform Backends).
  6. Run terraform init -migrate-state, Respond to the prompt with yes
  7. Run terraform plan and you should expect to see no or minimal changes.
  8. (If necessary, in conjunction with step 4) Run terraform state push backup.state to push your state to your bucket storage.
  9. The state has now been migrated to S3.
    1. If you are moving away from env0, then the environment can be marked as inactive.
    2. 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

:pencil2: Suggested Blog Content

Terraform Modules Guide

Terraform Plan Examples

Managing Terraform Variable Hierarchy

Manage Terraform Remote State with a Remote Backend