Migrate Terraform state to HCP Terraform or Terraform Enterprise

This topic describes how to migrate existing Terraform state files to HCP Terraform or Terraform Enterprise without first de-provisioning them. Refer to State in the Terraform configuration language reference for additional information about Terraform state.

Overview

Perform the following actions to migrate existing resources to one or more workspaces in HCP Terraform or Terraform Enterprise:

1. Stop all Terraform operations associated with the state files.
2. Migrate Terraform state files using either the Terraform CLI or the HCP Terraform or Terraform Enterprise API.

Hands-on: Complete the Migrate State to HCP Terraform tutorial for additional guidance on how to migrate Terraform state using the CLI.

Requirements

• Terraform v1.1 and later is required to configure the cloud block. For Terraform v1.0 and older, use the remote backend instead.
• You must present a token linked to appropriate permissions to use the API. Refer to the following topics for additional information:
  • HCP Terraform API overview
  • Terraform Enterprise API overview

Stop Terraform operations

Stop all Terraform operations associated with the state files. This may require locking or deleting CI jobs, restricting access to the state backend, and communicating with other teams. You should also only migrate state files into HCP Terraform or Terraform Enterprise workspaces that have never performed a run.

Migrate state using the CLI

1. Add the cloud block to your Terraform configuration and specify the following fields:

   1. hostname field: Specify either app.terraform.io for HCP Terraform or the hostname of your Terraform Enterprise deployment.
   2. organization field: Specify your HCP Terraform or Terraform Enterprise organization.
   3. workspaces block: Add a tags or name field and specify one or more destination workspaces as a list of strings.

   Refer to The cloud Block in the Terraform CLI documentation for additional information. The following example migrates the state associated with the configuration to the networking workspace on HCP Terraform:

   terraform {
     cloud {
       hostname = "app.terraform.io"
       organization = "my-org"
       workspaces {
         tags = ["networking"]
       }
     }
   }
   

2. Run terraform init. Terraform creates any workspaces specified in the configuration if they do not already exist in the organization.

Migrate state using the API

1. Encode your state files as a base64 string and generate an MD5 hash. The following example generates the string and hash file for a single terraform.tfstate file:

    $ cat terraform.tfstate | base64
    dGVycmFmb3JtLnRmc3RhdGUK
    $ md5sum terraform.tfstate
    690a3f8ae079c629494a52c68757d585  terraform.tfstate
   

2. If the workspace does not yet exist in your organization, send a POST request to the /organizations/:organization_name/workspaces endpoint to create it. Otherwise, proceed to the next step. Refer to the following topics for details:

   • Create a workspace in the HCP Terraform API reference documentation.
   • Create a workspace in the Terraform Enterprise API reference documentation.

3. Send a POST request to the /workspaces/:workspace_id/actions/lock endpoint to lock the workspace. Refer to the following topics for details:

   • Lock a workspace in the HCP Terraform API reference documentation.
   • Lock a workspace in the Terraform Enterprise API reference documentation.

4. To upload your state files to the workspace, send a POST request to the /workspaces/:workspace_id/state-versions endpoint. Specify the MD5 string in the data.attributes.md5 field and encoded state file in the data.attributes.state field of the request body. Refer to the following topics for details:

   • Create a state version in the HCP Terraform API reference documentation.
   • Create a state version in the Terraform Enterprise API reference documentation.

5. Send a POST request to the /workspaces/:workspace_id/actions/unlock endpoint to unlock the workspace.

Refer to the following external article for an example of how to create a script in Python to automate multiple state files: Migrating A Lot of State with Python and the HCP Terraform (previously Terraform Cloud) API. The example uses the Workspaces API to create the necessary workspaces in HCP Terraform and the State Versions API to migrate the state files to those workspaces.

Migrate state using Terraform migrate

You can use the Terraform migrate CLI tool to automatically migrate state to HCP Terraform and Terraform Enterprise. The tool does not ship with HCP Terraform. You must download and install the binary for the CLI tool separately. Refer to the Terraform migrate documentation for more information.