How to Migrate Terraform State Between Different Backends using init -migrate-state

Introduction:

The Terraform state file contains the critical record of infrastructure managed by Terraform. It maps Terraform resources to actual infrastructure resources, making it essential for reliable operations. At times, you may need to migrate your 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 performing such 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 not ideal in collaborative environments because:

• It risks accidental corruption or deletion.
• It prevents multiple team members from safely working on shared infrastructure.
• It lacks enterprise‑level access control, audit trails, and locking mechanisms.

To solve these concerns, you must migrate the Terraform state to a remote backend such as Azure Storage or Amazon S3.

Solutions:

Terraform provides a built‑in mechanism to migrate state between backends using: terraform init -migrate-state

This command validates backend configuration, transfers the state file, and ensures Terraform operations continue seamlessly.

General Migration Steps :

1. Update your main.tf backend block with the new backend configuration.
2. Create the required storage resources in the destination backend (e.g., Azure container, AWS S3 bucket).
3. Apply proper Identity and Access Management (IAM/ACL) permissions.
4. Run: terraform init -migrate-state
5. Confirm the migration when prompted.

Example: Migrating to Azure Storage Account Backend

1. Create an Azure Storage Account and container for state storage.
2. Configure appropriate access controls for authorized users.

3. Update your main.tf backend configuration:

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

4. Run the command: terraform init -migrate-state
5. Approve migration when Terraform prompts. This uploads the local state to the Azure container.

Example: Migrating to AWS S3 Backend

1. Create an Amazon S3 bucket for Terraform state.
2. Configure IAM permissions for restricted access.

3. Update your main.tf backend block:

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

4. Run the command: terraform init -migrate-state
5. Approve migration when prompted. Terraform uploads your local state to the S3 bucket.
    

Outcome:

• Terraform state is securely migrated from local to remote backend.
• Teams gain collaboration capability with integrated state locking and versionin
• Backend migration is validated and automated by Terraform to reduce chances of errors.

Reference:
https://developer.hashicorp.com/terraform/cli/commands/init