Migrate Terraform State Between Different Backends

Last Updated on August 7, 2025 by Arnav Sharma

Migrating your Terraform state files is a critical task that ensures the stability and scalability of your infrastructure. Whether you’re moving to a new cloud provider, optimizing costs, or centralizing state management, understanding how to manage Terraform state effectively is crucial. This blog will guide you through the process of migrating Terraform state using Terraform commands and provide practical examples, particularly focusing on Azure and AWS S3 backends.

Why You Need to Migrate Terraform State

There are several reasons why you might need to migrate your Terraform state:

1. Moving to the Cloud: Migrating your local state file to a remote backend enhances security, scalability, and collaboration.
2. Switching Cloud Providers: When transitioning to a new cloud provider, such as from AWS to Azure, you need to migrate your Terraform state.
3. Centralizing State Management: Using a centralized backend like Terraform Cloud or an Azure storage account remote backend simplifies state management.
4. Cost Optimization: Migrating your state file to a more cost-effective storage solution can reduce infrastructure costs.

How to Migrate Terraform State

Using Terraform Commands

One of the most reliable ways to migrate Terraform state is by using built-in Terraform commands. The terraform init -migrate-state command is designed to safely migrate your state file from one backend to another. Here’s how to do it:

1. Set Up Backend Configuration: Update your main.tf file with the new backend configuration. For Azure, it might look like this:

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

2. Run terraform init -migrate-state: This command will initialize your Terraform configuration with the new backend and migrate the existing state file to the specified remote backend.

terraform init -migrate-state

3. Confirm the migration when prompted.

Using Terraform State Pull and Push Commands

Another method involves using the terraform state pull and terraform state push commands. Although not the best practice, it can be useful in specific scenarios.

Export State: Use terraform state pull to export your current state to a local file.

terraform state pull > terraform.tfstate

Configure New Backend: Update your backend configuration in main.tf.

Push State: Use terraform state push to push the exported state file to the new backend.

terraform state push terraform.tfstate

Practical Examples: Migrating Local State to Azure and AWS S3

Example 1: Azure Storage Account Remote Backend

1. Create Azure Storage Account: Set up a storage account and a container in Azure to hold the state files.
2. Configure Backend: Update main.tf with the Azure backend configuration.

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

3. Migrate State: Run the terraform init -migrate-state command to migrate the state file.

terraform init -migrate-state

Example 2: AWS S3 Backend

1. Create S3 Bucket: Set up an S3 bucket in AWS to store the state files.
2. Configure Backend: Update main.tf with the S3 backend configuration.

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

3. Migrate State: Run the terraform init -migrate-state command to migrate the state file to the S3 bucket.

terraform init -migrate-state

Managing Terraform State with Terraform Cloud

Terraform Cloud provides a robust remote backend for managing your state file, offering enhanced security and collaboration features. By using Terraform Cloud as your backend, you can leverage automated state management and integrate with various workflows.

1. Configure Terraform Cloud Backend: Update your main.tf to use Terraform Cloud.

terraform {
  backend "remote" {
    organization = "your-org"

    workspaces {
      name = "your-workspace"
    }
  }
}

2. Run terraform init: Initialize your configuration to use Terraform Cloud as the remote backend.

terraform init

3. Migrate State: Follow the prompts to migrate the state file to Terraform Cloud.

Migrating Terraform state is an essential part of maintaining a secure and scalable infrastructure. By understanding how to use Terraform commands and backends like Azure and AWS S3, you can effectively manage your state files and ensure smooth operations. Whether you’re using Terraform Cloud, Azure Storage Account, or AWS S3, the key is to follow best practices and carefully plan your state migration.