Terraform migrate

The Terraform migrate tf-migrate CLI automatically migrates your Terraform Community Edition state and variables to HCP Terraform or Terraform Enterprise. It also updates your local configuration with the new state storage location and optionally creates a pull request to update your code repository.

Hands-on: Complete the Migrate to HCP Terraform in bulk tutorial to get started with tf-migrate.

Overview

Complete the following steps to install and configure tf-migrate:

Download and install tf-migrate.
Configure tf-migrate to authenticate to HCP Terraform or Terraform Enterprise.
Enable logging so that you can troubleshoot potential issues that may occur during the migration process.

GitHub and GitLab connection requirements

The tf-migrate tool can optionally open a pull request to update your configuration in GitHub or GitLab.

If your Terraform files are stored in GitHub, you must configure an API token that meets the following requirements:

The token must be a classic token. Refer to the GitHub documentation for additional information.
The token must have the repo OAuth scope.

If your Terraform files are stored in GitLab Cloud, you must configure an API token that meets the following requirements:

The token must be a personal access token. Refer to the GitLab documentation for additional information.
The token must be have read_repository and write_repository scopes.

Install

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

After you download tf-migrate, unzip the archive.

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 tf-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 tf-migrate formula from the terminal.

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

$ brew tap hashicorp/tap

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

$ brew install hashicorp/tap/tf-migrate

Connect to HCP Terraform or Enterprise Terraform

The tf-migrate tool 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 sign in screen, where you can then 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.

tf-migrate can optionally create a pull request that updates the state storage location specified in your Terraform configuration. To do this, tf-migrate uses the GitHub or GitLab Cloud API, and requires an API token with permissions to modify your Git repository.

To configure your API token, set the TF_GIT_PAT_TOKEN environment variable

$ export TF_GIT_PAT_TOKEN=<TOKEN>

Supported backends

The tf-migrate tool supports migrating state from the following backends to HCP Terraform or Terraform Enterprise:

tf-migrate does not support migrating state from an existing cloud integration or remote backend.

Supported workspace workflows

Versions 1.1.0 and newer of tf-migrate can create CLI- or VCS-driven HCP Terraform workspaces.

The tf-migrate tool will only prompt you to create a VCS-driven workspace if you meet the following requirements:

Your local configuration is a Git repository.
Your local Git repository has either GitHub or GitLab configured as a remote.
Your HCP Terraform organization has at least one VCS OAuth connection configured for GitHub or GitLab.

If your HCP Terraform organization has more than one VCS connection configured, tf-migrate will ask you to choose which VCS connection to use.

If your local configuration does not meet all of the above requirements, tf-migrate automatically creates a CLI-driven workspace instead.

Enable logging

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

Platform	Location
macOS and 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:

Additional configuration

You can create an optional configuration file to modify the tf-migrate CLI behavior and specify the path to the configuration file when you run tf-migrate prepare. Any command-line flags you provide with these commands override the configuration file. Refer to the configuration reference for additional information.