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)
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 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+
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. 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 and TF_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:
1. Run terraform login backend.api.env0.com
2. Enter yes when prompted
3. Insert your token (See Generating a Token)
Run terraform plan and ensure you are working in the correct environment.
1. 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 with yes
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.
1. If you are moving away from env0, 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.