Terraform Enterprise: Automated Migration for Legacy Environments

Terraform Enterprise: Automated Migration for Legacy Environments

Apr 03 2018    Maciej Skierkowski

We are pleased to announce an automated migration process in Terraform Enterprise to migrate Atlas legacy environments to the new workspaces. Based on the feedback we also extended the Atlas deprecation date from March 30th to May 31st. We hope this gives users an improved experience and more time to migrate.

In December 2017 we announced the General Availability release of Terraform Enterprise and the decommissioning of Atlas. Since then Terraform Enterprise legacy users have migrated legacy environments to new workspaces, but found the migration process laborious and error prone. The automated migrator will ease this process. We should have anticipated this pain and built the migrator early; we're sorry for the delay! We apologize for the inconvenience caused by the migration, but hope you find the new platform worth the upgrade.

» New automated migration process

The new automated migration process imports the data from a legacy environment to a newly created workspace.

The workspace creation page now includes an “Import from legacy (Atlas) environment” tab where a user can select a legacy environment to migrate data from. When the new workspace is created, data will be imported from the selected legacy environment to the new workspace.

Automted Migration to Workspaces

The entire process is documented in detail in the upgrade guide.

» What does and does not get migrated

The new workspace will immediately migrate the most recent state, settings, and variables from the old environment. Once the most recent state, settings, and variables are migrated the new workspace will be unlocked so you can start using it. In the background, the tool will continue to migrate the state, configuration, and run history. The upgrade guide includes a comprehensive list of migrated data.

Data associated with deprecated features will not be migrated — personal environment variables, collaborators, and periodic queuing. The Differences Between Current and Legacy Terraform Enterprise document covers more details about the legacy features which have been moved, renamed, or deprecated.

» Using the API to migrate

In addition to using the UI to migrate a legacy environment to a workspace, you can also use the API. The “Create a workspace which is migrated from a legacy environment” documentation provides details of the API call and parameters. Below is an example of migrating the legacy my-org-legacy/my-env environment to a new workspace my-org/my-workspace. The tfe-cli tool also provides convenient wrappers to make the API calls.

» Sample payload.json

  "data": {
    "attributes": {

» CURL API call

$ curl \
  --header "Authorization: Bearer $ATLAS_TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \

» Batch migration

Your organization may have more environments than can be easily migrated one-by-one via the new user interface. The Batch Migration guide shows how to use the workspace creation API via the HashiCorp supported tfe-cli tool to automate the migration.

» Conclusion

We hope the migration tool gives users an improved experience and postponing the deprecation from March 30th to May 31st provides more time to migrate. We appreciate your feedback in continuously improving Terraform Enterprise.

Your browser is out-of-date!

Update your browser to view this website correctly. Update my browser now