Migrating to HCP Terraform or Terraform Enterprise

You can begin using HCP Terraform to manage existing resources without de-provisioning them. This requires migrating the Terraform state files for those resources to one or more HCP Terraform workspaces. You can perform this migration with either the Terraform CLI or the HCP Terraform API.

Hands-on: Try the Migrate State to HCP Terraform tutorial to practice using the CLI method.

Requirements

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

CLI Migration

To migrate with the Terraform CLI, add the cloud block to your configuration, specify one or more HCP Terraform workspaces for the state files, and run terraform init. If the workspaces you choose do not yet exist, HCP Terraform creates them automatically in the specified organization.

The example below shows how you can map your CLI workspaces to HCP Terraform workspaces that have a specific tag.

terraform {
  cloud {
    organization = "my-org"
    workspaces {
      tags = ["networking"]
    }
  }
}

Refer to Using HCP Terraform in the Terraform CLI documentation for details about how to configure the cloud block and migrate state to one or more HCP Terraform workspaces.

API Migration

You can use the HCP Terraform API to automate migrating many state files at once.

This blog post contains an example of how to automate state migration with the API: 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.