» Batch Migration

These instructions are for migrating TFE (Atlas) legacy environments to workspaces using the API and scripts to automate large batches. Using the UI is the easiest way to migrate a legacy environment to a workspace; however, if your organization has many environments in need of migration this process may be laborious to perform in the UI.

The TFE workspace creation API can be used to perform the migration, which automaticaly locks the legacy environment and migrates the data to the new workspace. This API can be called using standard tools like curl, tfe-cli tool, or community tools like the terraform-enterprise-client. These tools can be used to iterate over a list of legacy environments to make the API calls to perform the migration.

These instructions show how to automatically migrate a batch of legacy environments using tfe-cli, some basic scripting, and a file with legacy environments. You can follow the steps as written, or use them as an example for building your own automation.

» Prerequisites

This guide requires the tfe-cli tool.

» Step 1: Identify OAuth Token ID

To get the OAuth connection we assume you already have VCS integration set up in the new organization. You will need the OAuth ID of the connection. You can obtain this with the command line tool:

curl \
  --header "Authorization: Bearer $TOKEN" \

This will be the id value of the oauth-tokens.

» Step 2: Set Up Files and Script

» Data File: legacy-envs.txt

To prepare for migration, create a text file with all of the data you need.

skierkowski/training my-organization/training skierkowski/terraform-test-proj
skierkowski/migration-source my-organization/migration-desintation skierkowski/terraform-test-proj

Each line identifies a legacy environment, the new workspace to migrate to, and the VCS repo to use, formatted as:

<legacy_org>/<legacy_environment> <new_organization>/<new_workspace> <vcs_org>/<vcs_repo>

If we were omitting VCS connections from the new workspaces, we would omit the repo from each line.

» Script: migrate.sh

Next, create a bash script which:

  • Opens the file legacy-envs.txt.
  • Parses out the legacy workspaces, new workspaces, and VCS repo.
  • Calls tfe command line tool to trigger the migration.

Note: You'll need to specify the path to tfe command line tool.


regex="([a-zA-Z0-9_\-]+)\/([a-zA-Z0-9_\-]+) ([a-zA-Z0-9_\-]+)\/([a-zA-Z0-9_\-]+) ([a-zA-Z0-9_\-]+)\/([a-zA-Z0-9_\-]+)"
cat legacy-envs.txt | while read line
  if [[ $line =~ $regex ]]
    echo MIGRATING: $line
    tfe migrate \
      -legacy-name $legacy_org/$legacy_workspace \
      -name $new_org/$new_workspace \
      -vcs-id $vcs_org/$vcs_repo \
      -oauth-id $VCS_OAUTH_TOKEN_ID
    echo ERROR PARSING: $line

» Step 3: Run migration

Now you can run the batch migration:

chmod +x migrate.sh

The migrate.sh script does not perform any error handling. Review the logs to ensure all workspaces are migrated properly.