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:

1. Download and install tf-migrate.
2. Configure tf-migrate to authenticate to HCP Terraform or Terraform Enterprise.
3. 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 GitHub documentation for additional information.
• The token must be have read_repository and write_repository scopes.

Install

$ brew tap hashicorp/tap

$ 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 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.

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:

• local
• azurerm
• consul
• cos
• gcs
• http
• Kubernetes
• oss
• pg
• s3

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

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:

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:

• TRACE
• DEBUG
• INFO
• WARN
• ERROR

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.