» Upgrading From Terraform Enterprise (Legacy)

If you used the legacy version of Terraform Enterprise (TFE), you probably have some older environments that aren't available in the new version. You can transfer control of that infrastructure to the new Terraform Enterprise without having to re-provision anything.

Follow these steps to migrate your old TFE environments to new TFE workspaces.

» 1. Create a new organization

You can't use the new TFE with a legacy organization because the internals are too different. If you don't already have an organization in the new TFE, create an organization and configure version control access now. Organization names must be globally unique, so you must choose a new organization name.

» 2. Create new workspaces

TFE can't automatically import legacy environments, so start by creating a new workspace for each legacy environment. Workspace names are unique to the organization, so you can re-use the same names for the new workspaces.

When you create these workspaces: do link them to the same VCS repo as the corresponding environment, but don't allow any applies to occur yet. If other people are likely to commit to the repo before you've finished, you might want to lock the workspace so it doesn't create a bunch of inaccurate plans.

» 3. Migrate state

Each TFE workspace has its own remote backend, and TFE overrides the configuration to use that backend whenever it does a run. To transfer control of your infrastructure, you must migrate state from the legacy environment to the new workspace.

» 3.a. Authenticate the CLI

From User Settings > Tokens obtain the API key and set the environment variable ATLAS_TOKEN.


» 3.b. Configure the backend for the legacy environment

In most cases the backend is already configured to use the legacy environment. If the CLI commands push, plan, apply, or state were ever used, this block is already configured as needed.

If a remote backend is not already configured with the TFE legacy environment, add the backend configuration block.

terraform {
  backend "atlas" {

» 3.c. Reinitialize Terraform

Reinitialize Terraform to ensure your working directory is up to date, especially if you just added backend configuration.

terraform init

» 3.d. Reconfigure the backend for the new workspace

Update the name field of the backend block to reference the new workspace.

terraform {
  backend "atlas" {

» 3.e. Reinitialize Terraform again

Terraform's init command automatically migrates state from the legacy environment to the new workspace when the backend is reconfigured. Run the init command, and it will ask to migrate the state. Answer yes.

terraform init

» 4. Disable VCS integration in the legacy environment

Before committing and pushing the backend change to VCS, the legacy environment webhook must be disabled to prevent the configuration from running in both the legacy environment and the new workspace.

In legacy TFE, go to the Environment settings page and go to “Integrations”. In the “Version Control Integration” section click “Unlink”.

This will prevent the environment from performing a run on future commits.

» 5. Commit backend configuration changes and verify

Commit and push the changes to VCS. The following changes should occur.

  • The legacy environment will not trigger a new run because it was disabled in the previous step.
  • The new workspace will trigger a new run (plan & apply).

  • The plan logs should show no changes.

These changes verify the workspace was migrated successfully.

» 6. Delete legacy environment

Once the new workspace configuration is verified it is safe to delete the legacy environment.