How to Migrate Terraform State Between Different Backends using init -migrate-state – HashiCorp Help Center

Introduction

The Terraform state file is a critical component that maps your Terraform configuration to the infrastructure it manages. By default, Terraform stores this state in a local file named terraform.tfstate. While suitable for individual use, local state is not recommended for team environments because it lacks features like access control, audit trails, and state locking.

To enable collaboration and enhance reliability, you should migrate your Terraform state to a remote backend, such as Azure Storage or Amazon S3. This guide provides step-by-step instructions to migrate your state file using the terraform init -migrate-state command.

Prerequisites

Before you begin, ensure you have the following:

The Terraform CLI installed on your local machine.
An existing Terraform project with a local terraform.tfstate file.
Configured credentials for your target cloud provider (e.g., authenticated via the Azure CLI or AWS CLI).
Permissions to create and manage storage resources (e.g., an Azure Storage Container or AWS S3 Bucket) in the target cloud account.

Procedure

Terraform provides a built-in mechanism to migrate state between backends using the -migrate-state flag with the init command. This process validates the new backend configuration and safely transfers the state file.

1. Update Backend Configuration

First, modify the backend block in your Terraform configuration to define the new remote backend. You must create the required storage resources, such as an S3 bucket or Azure container, before proceeding.

2. Initialize and Migrate State

Next, run the initialization command with the migration flag. Terraform will detect the configuration change and prompt you to confirm the state migration.

Execute the init command with the -migrate-state flag.

$ terraform init -migrate-state

When prompted, type yes to approve the migration. Terraform will then copy the existing state from your local terraform.tfstate file to the newly configured remote backend.

Example 1: Migrating to an Azure Storage Backend

To migrate your state to Azure, first create an Azure Storage Account and a container. Then, update your configuration with the azurerm backend block.

terraform {
  backend "azurerm" {
    resource_group_name  = "your-resource-group"
    storage_account_name = "your-storage-account"
    container_name       = "terraform-state"
    key                  = "terraform.tfstate"
  }
}

Run the migration command to upload the local state to Azure.

$ terraform init -migrate-state

Example 2: Migrating to an AWS S3 Backend

To migrate your state to AWS, first create an S3 bucket. Then, update your configuration with the s3 backend block.

terraform {
  backend "s3" {
    bucket = "your-bucket-name"
    key    = "environment/terraform.tfstate"
    region = "us-east-1"
  }
}

Run the migration command to upload the local state to the S3 bucket.

$ terraform init -migrate-state

Outcome

After completing these steps, your Terraform state is securely migrated from a local file to a remote backend. Your team can now benefit from enhanced collaboration features, including integrated state locking and versioning, while Terraform's automated process reduces the risk of manual errors.

Additional Information