Skip to content

Updates to the "Migrate to HCP Terraform" overview page #904

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Sep 4, 2025
Merged

Updates to the "Migrate to HCP Terraform" overview page #904

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 8 additions & 10 deletions content/terraform-docs-common/docs/cloud-docs/migrate/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,7 @@
---
page_title: Migrate Terraform state to HCP Terraform or Terraform Enterprise
description: >-
Learn how to migrate existing Terraform state to HCP Terraform or Terraform Enterprise so that you can manage
existing infrastructure without de-provisioning.
Learn how to migrate existing Terraform state to HCP Terraform or Terraform Enterprise using the CLI, API, or tf-migrate.
---

# Migrate Terraform state to HCP Terraform or Terraform Enterprise
Expand All @@ -14,13 +13,13 @@ This topic describes how to migrate existing Terraform state files to HCP Terraf
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.
1. Migrate Terraform state files using either the Terraform CLI or the HCP Terraform or Terraform Enterprise API.
1. Migrate Terraform state files to HCP Terraform or Terraform Enterprise.

You have three options to migrate your state:

1. Manually using the Terraform CLI
1. Automatically using `tf-migrate`
1. Manually using the HCP Terraform API
1. Automatically using `tf-migrate`

## Requirements

Expand Down Expand Up @@ -60,10 +59,6 @@ Stop all Terraform operations associated with the state files. This may require

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

## 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](/terraform/migrate) for more information.

## 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:
Expand All @@ -89,6 +84,9 @@ You can use the Terraform migrate CLI tool to automatically migrate state to HCP
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](https://medium.com/hashicorp-engineering/migrating-a-lot-of-state-with-python-and-the-terraform-cloud-api-997ec798cd11). The example uses the [Workspaces API](/terraform/cloud-docs/api-docs/workspaces#create-a-workspace) to create the necessary workspaces in HCP Terraform and the [State Versions API](/terraform/cloud-docs/api-docs/state-versions) 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](/terraform/cloud-docs/migrate/tf-migrate) for more information.
## Migrate state using `tf-migrate`

> **Hands-on:** Complete the [Migrate to HCP Terraform in bulk](/terraform/tutorials/cloud/bulk-migrate-hcp) tutorial to get started with tf-migrate.

You can use the `tf-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 [`tf-migrate` documentation](/terraform/migrate) for more information.
Loading