»Migrating to Terraform Cloud

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

Hands-on: Try the Migrate State to Terraform Cloud tutorial on HashiCorp Learn for a walkthrough 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 Terraform Cloud 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 Terraform Cloud workspaces for the state files, and run terraform init. If the workspaces you choose do not yet exist, Terraform Cloud creates them automatically in the specified organization.

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

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

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

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

»API Migration

You can use the Terraform Cloud 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 Terraform Cloud API. The example uses the Workspaces API to create the necessary workspaces in Terraform Cloud and the State Versions API to migrate the state files to those workspaces.