Terraform migrate

Terraform migrate automatically migrates your Terraform Community Edition state to HCP Terraform or Terraform Enterprise. It also updates your local configuration with any necessary changes and optionally creates a pull request to update your code repository.

Overview

Complete the following steps to migrate Terraform state using the CLI:

Download and install tf-migrate: You can manually download and install or use Homebrew if you are on macOS.
tf-migrate prepare: This step scans the current working directory and generates Terraform configuration to migrate your state. The generated migration plan depends on the structure of your configuration. For more information, refer to tf-migrate prepare.
tf-migrate execute: This step directs Terraform to run the init, plan, and apply commands to perform the migration to HCP Terraform or Terraform Enterprise. At the end of the migration, tf-migrate displays a summary of what it migrated, links to the workspaces it created, and, if configured, a link to the pull request it created. For more information, refer to tf-migrate execute.

Install

HashiCorp distributes Terraform migrate as a binary package. To install Terraform migrate, find the appropriate binary for your operating system and download it as a zip archive.

After you download Terraform migrate, unzip the archive. Terraform migrate runs as a single binary named tf-migrate.

Finally, make sure that the tf-migrate binary is available in a directory that is in your system's PATH.

Verify the installation

Every build of Terraform migrate includes a SHA256SUMS and a SHA256SUMS.sig file to validate your downloaded binary. Refer to the verify HashiCorp binary downloads tutorial for more information.

Homebrew is a free and open-source package management system for macOS. You can install the official Terraform migrate formula from the terminal.

First, install the HashiCorp tap, a repository of all our Homebrew packages.

$ brew tap hashicorp/tap

Now, install Terraform migrate with the hashicorp/tap/tf-migrate formula.

$ brew install hashicorp/tap/tf-migrate

Authentication

Terraform migrate uses your locally configured Terraform CLI API token. If you have not authenticated your local Terraform installation with HCP Terraform, use the terraform login command to create an authentication token.

$ terraform login

Terraform will request an API token for app.terraform.io using your browser.

If login is successful, Terraform will store the token in plain text in
the following file for use by subsequent commands:
   /Users/redacted/.terraform.d/credentials.tfrc.json

Do you want to proceed?
 Only 'yes' will be accepted to confirm.

 Enter a value: yes

Terraform opens a browser to the HCP Terraform login screen. Enter a token name in the web UI, or leave the default name. Click Create API token to generate the authentication token.

HCP Terraform only displays your token once. Copy this token, then when the Terraform CLI prompts you, paste the user token exactly once into your terminal. Press Enter to complete the authentication process.

Terraform migrate uses the GitHub API to create a pull request to update your configuration. Set the GITHUB_TOKEN environment variable to provide your GitHub API token. Your token must have the repo scope.

$ export GITHUB_TOKEN=<TOKEN>

Logging

You can enable detailed logging by setting the TF_MIGRATE_ENABLE_LOG environment variable to true. When you enable this setting, Terraform migrate writes the logs to the following locations, depending on your operating system:

Platform	Location
macOS/Linux	`/Users/<username>/.tf-migrate/logs/<commandName>/<date>.log`
Windows	`C:\Users\<username>\.tf-migrate\logs\<commandName>\<date>.log`

You can set the TF_MIGRATE_LOG_LEVEL environment variable to one of the following values to change the verbosity of the logs (in order of decreasing verbosity):