Demo Migrate Your State to a Remote State Configuration

When you initialize Terraform with a remote backend, Terraform stores and updates the state file in that backend automatically. But if you already have an existing local state file (for example, you developed locally and now want to move to a remote backend), you can migrate the current local state into a remote backend without losing your existing state. This guide shows how to migrate a local Terraform state to an S3 backend and how to move it back to local when needed. It preserves the original state and walks through validation and verification steps.

Prerequisites

Terraform installed (1.x or later recommended).
AWS credentials configured for the account that owns the target S3 bucket.
An S3 bucket created to hold Terraform state and appropriate permissions (PutObject, GetObject, ListBucket).
Working Terraform configuration with a local state (no active terraform { backend ... } block).

Example: Resources Managed Locally

Here is a simple example of Terraform resources that might currently be tracked by a local state:

resource "aws_vpc" "main" {
  cidr_block           = var.vpc_cidr
  enable_dns_support   = true
  enable_dns_hostnames = true

  tags = {
    Name        = "dev-main-vpc"
    Environment = "development"
  }
}

resource "aws_subnet" "private" {
  vpc_id = aws_vpc.main.id
  # ...
}

Step 1 — Add (or enable) a backend configuration

If your working directory does not currently have an active backend block (it may be commented out), add or uncomment the backend configuration that points to your S3 bucket. Example (commented version shown first for context):

# terraform {
#   backend "s3" {
#     bucket      = "krausen-terraform-state-bucket"
#     key         = "prd/terraform.tfstate"
#     region      = "us-east-2"
#   }
# }

Uncomment or create the active backend block:

terraform {
  backend "s3" {
    bucket       = "krausen-terraform-state-bucket"
    key          = "prd/terraform.tfstate"
    region       = "us-east-2"
  }
}

Step 2 — Initialize and migrate the state

Run terraform init with the -migrate-state flag to initialize the backend and instruct Terraform to migrate any existing local state to the newly configured backend.

# Initialize and migrate local state to the configured backend
terraform init -migrate-state

Terraform will detect the existing local state and prompt you to confirm copying that state to the S3 backend:

Initializing the backend...
Do you want to copy existing state to the new backend?
  Pre-existing state was found while migrating the previous "local" backend to the
  newly configured "s3" backend. No existing state was found in the newly
  configured "s3" backend. Do you want to copy this state to the new "s3"
  backend? Enter "yes" to copy and "no" to start with an empty state.

Enter a value:

If you want to continue managing the same resources with Terraform, answer yes to copy your existing local state to the S3 backend. Choose no only if you intentionally want to start with an empty remote state.

After you confirm yes, Terraform configures the backend and copies the state. You should see output similar to the following:

Successfully configured the backend "s3"! Terraform will automatically use this backend unless the backend configuration changes.

Initializing provider plugins...
- Reusing previous version of hashicorp/aws from the dependency lock file
- Using previously-installed hashicorp/aws v6.31.0

Terraform has been successfully initialized!

You may now begin working with Terraform. Try running "terraform plan" to see any changes that are required for your infrastructure. All Terraform commands should now work.

If you ever set or change modules or backend configuration for Terraform, rerun this command to reinitialize your working directory.

Step 3 — Verify the migration

After the migration completes, verify that your S3 bucket contains the state object at the path specified by the key (for example prd/terraform.tfstate). If the S3 backend previously had no state, Terraform creates the object during the copy. Below is a screenshot showing the prd/terraform.tfstate object in the S3 console after migration.

Screenshot of an Amazon S3 console showing the "prd/" folder in a terraform state bucket with a single object named "terraform.tfstate" (11.4 KB). The listing shows its last-modified timestamp and the usual S3 action buttons (Copy S3 URI, Download, Upload, etc.).

Now Terraform will read and write state directly to S3 for subsequent operations.

Migrating back to the local backend

If you later decide to move state back from S3 to local, reverse the change: comment out (or remove) the backend configuration and re-run terraform init -migrate-state. Example of commenting the block:

# terraform {
#   backend "s3" {
#     bucket       = "krausen-terraform-state-bucket"
#     key          = "prd/terraform.tfstate"
#     region       = "us-east-2"
#   }
# }

Then:

terraform init -migrate-state
# Enter "yes" when asked to copy state from the S3 backend back to the local backend.

After you confirm, Terraform copies the remote S3 state back into your local terraform.tfstate file. Note that Terraform copies state content to the currently configured backend; it does not automatically delete the source object (the S3 object remains unless you remove it manually).

Be careful when migrating state: copying state into a new backend replaces the destination backend’s state (if any) with the source state’s content. Make backups if you are unsure and ensure access controls are correct for remote state files because they can contain sensitive data.

Example: Truncated state file JSON

A portion of a Terraform state file (truncated for brevity):

{
  "version": 4,
  "terraform_version": "1.12.2",
  "serial": 1,
  "lineage": "d010f298-6128-653c-2eca-d54d0e33594d",
  "outputs": {},
  "resources": [
    {
      ...
    }
  ]
}

Quick reference: Commands and common actions

Action	Command / Example
Initialize and migrate to backend	`terraform init -migrate-state`
Add an S3 backend block	See the `terraform { backend "s3" { ... } }` example above
Verify remote state file in S3	Check `prd/terraform.tfstate` in the bucket
Migrate back to local	Comment the backend block and run `terraform init -migrate-state`
Example S3 key path	`prd/terraform.tfstate`

Summary

To migrate Terraform state between backends:

Add or modify the terraform { backend "..." { } } block in your configuration.
Run terraform init -migrate-state to initialize the backend and copy state.
Confirm at the prompt whether to copy existing state to the destination backend.
Verify the state object exists in the remote backend (S3) or locally depending on the destination.

This process preserves your existing infrastructure management while moving where the state is stored.

Course Introduction

Preparing Your Environment

Terraform Foundations

The Core Terraform Workflow

Terraform CLI

Terraform File Structure and Organization

Terraform Configuration - Fundamentals

Understading and Managing Terraform State

Marking Code Reusable

Refactoring Terraform State

Terraform Modules

Managing Resource Behavior and Dependencies

Securing Terraform Configurations

Terraform Troubleshooting

HCP Terraform

Demo Migrate Your State to a Remote State Configuration

Prerequisites

Example: Resources Managed Locally

Step 1 — Add (or enable) a backend configuration

Step 2 — Initialize and migrate the state

Step 3 — Verify the migration

Migrating back to the local backend

Example: Truncated state file JSON

Quick reference: Commands and common actions

Summary

Links and references

Watch Video

​Prerequisites

​Example: Resources Managed Locally

​Step 1 — Add (or enable) a backend configuration

​Step 2 — Initialize and migrate the state

​Step 3 — Verify the migration

​Migrating back to the local backend

​Example: Truncated state file JSON

​Quick reference: Commands and common actions

​Summary

​Links and references

Watch Video

Prerequisites

Example: Resources Managed Locally

Step 1 — Add (or enable) a backend configuration

Step 2 — Initialize and migrate the state

Step 3 — Verify the migration

Migrating back to the local backend

Example: Truncated state file JSON

Quick reference: Commands and common actions

Summary

Links and references