Backend initialization and migration in Terraform - Commands & Configuration

Introduction

When you use Terraform to manage infrastructure, it stores state information about your resources. Backend initialization sets up where this state is saved. Migration moves this state from one place to another safely.

When starting a new Terraform project and you want to save state remotely for team collaboration.

When switching from local state storage to a remote backend like AWS S3 or Terraform Cloud.

When you want to improve security by moving state files to a safer location.

When you need to share state files between multiple team members or automation systems.

When upgrading your Terraform setup to use a new backend provider.

Config File - main.tf

main.tf

terraform {
  required_version = ">= 1.5.0"
  backend "s3" {
    bucket = "example-terraform-state"
    key    = "project/terraform.tfstate"
    region = "us-east-1"
  }
}

provider "aws" {
  region = "us-east-1"
}

resource "aws_s3_bucket" "example" {
  bucket = "example-terraform-bucket"
  acl    = "private"
}

This file configures Terraform to use an AWS S3 bucket as the backend to store the state file remotely.

terraform block: Defines the backend type and its settings.

provider block: Sets AWS region for resource creation.

resource block: Creates an example S3 bucket to demonstrate resource management.

Commands

This command initializes Terraform in the current directory. It sets up the backend and downloads necessary provider plugins.

Terminal

terraform init

Expected Output

Initializing the backend...



Successfully configured the backend "s3"!



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.



If you ever set or change modules or backend configuration, rerun this command to reinitialize your working directory. If you forget, other commands will detect it and remind you to do so if necessary.

This command initializes Terraform and migrates the existing state file from the old backend to the new backend safely.

Terminal

terraform init -migrate-state

Expected Output

Initializing the backend...



Do you want to migrate all workspaces to the new backend?

  Both the existing and new backend support workspaces.



  Terraform will copy all workspaces from the existing backend to the new backend.



  Enter a value: yes



Successfully configured the backend "s3"!



Migrating state to the new backend...



Successfully migrated state to the new backend!



Terraform has been successfully initialized!

→

-migrate-state - Migrates existing state to the new backend during initialization

This command lists all resources tracked in the current Terraform state to verify the migration was successful.

Terminal

terraform state list

Expected Output

aws_s3_bucket.example

Key Concept

If you remember nothing else from this pattern, remember: backend initialization sets where Terraform saves state, and migration safely moves that state without losing track of your resources.

Common Mistakes

Running 'terraform init' without the '-migrate-state' flag when changing backends with existing state.

Terraform will not move your existing state file, causing potential loss of resource tracking or conflicts.

Use 'terraform init -migrate-state' to safely move your state to the new backend.

Changing backend configuration in the config file without re-running 'terraform init'.

Terraform will not apply the new backend settings, so state may still be saved locally or in the old backend.

Always run 'terraform init' after changing backend settings to apply them.

Manually copying state files between backends instead of using Terraform commands.

Manual copying can corrupt state or cause inconsistencies, leading to errors in resource management.

Use 'terraform init -migrate-state' to let Terraform handle state migration safely.

Summary

Use 'terraform init' to set up the backend where Terraform saves state.

Use 'terraform init -migrate-state' to move existing state safely to a new backend.

Verify the migration by listing resources with 'terraform state list'.