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

Introduction:

The Terraform state file contains the critical record of infrastructure managed by Terraform and maps Terraform resources to actual infrastructure resources, making it essential for reliable operations. At times, a team may need to migrate this state file from one backend to another—for example, when moving from a local state file to a remote backend in a cloud provider. This article explains common scenarios for migrations and provides step-by-step instructions to safely move Terraform state files to Azure or AWS.

Problem:

By default, Terraform stores state locally in a file named terraform.tfstate. Local state storage is problematic in collaborative environments due to several reasons:

Risks of accidental corruption or deletion.
Inability for multiple team members to safely work on shared infrastructure.
Lack of enterprise-level access control, audit trails, and locking mechanisms.

To address these concerns, teams should migrate the Terraform state to a remote backend such as Azure Storage or Amazon S3.

Prerequisites:

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

Solutions:

Terraform offers a built-in mechanism to migrate state between backends using the -migrate-state flag with the init command. This command validates the new backend configuration, transfers the state file, and ensures Terraform operations continue seamlessly.

Update Backend Configuration: Modify the backend block in your main.tf or relevant configuration file to define the new remote backend.
Create Storage Resources: Ensure the necessary storage resources exist in the target backend (such as an Azure container or AWS S3 bucket).
Apply Permissions: Configure the required IAM or ACL permissions for Terraform to access the state file.
Run Migration Command: Execute the initialization command with the migration flag: terraform init -migrate-state
Confirm Migration: When prompted, type yes to approve the state migration.

Example: Migrating to Azure Storage

Create an Azure Storage Account and container for state storage, and assign proper access controls.

Update your main.tf with the azurerm backend configuration:

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 and approve the prompt to upload the local state to Azure:
```
terraform init -migrate-state
```

Example: Migrating to AWS S3

Create an Amazon S3 bucket for Terraform state and configure IAM permissions.

Update your main.tf with the s3 backend configuration:

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

Run the migration command and approve the prompt to upload your local state file to the S3 bucket:
```
terraform init -migrate-state
```

Outcome:

Terraform state is securely migrated from a local file to a remote backend.
Teams gain collaboration capabilities with integrated state locking and versioning.
Backend migration is validated and automated by Terraform, reducing the likelihood of errors.

Reference:
https://developer.hashicorp.com/terraform/cli/commands/init#backend-initialization
https://developer.hashicorp.com/terraform/language/settings/backends/azurerm
https://developer.hashicorp.com/terraform/language/settings/backends/s3