Safe Terraform Refactoring with Moved Blocks and Module Composition

The problem: reorganizing production infrastructure without downtime

Teams often start with a single root module that grows into a sprawling list of resources. When the time comes to split that configuration into reusable child modules — for example, a shared VPC module or an S3 bucket module — the naive approach is to delete the old resources and recreate them under the new module addresses. In a production environment that means service interruption, data loss risk, and a lengthy approval process.

Terraform’s moved block (stabilized in Terraform 1.2) solves this by telling the planner that a resource or module call has simply changed its address. The state is updated in‑place, so no destroy/create cycle occurs.

Why module composition matters

• Reusability – a child module can be versioned and consumed by multiple environments.
• Separation of concerns – networking, IAM, and application resources live in their own directories.
• Team autonomy – different squads can own separate modules while a root module orchestrates them.

Common composition patterns include a root module that calls environment‑specific child modules, a library of shared modules (VPC, IAM, S3), and a module‑per‑environment layout with distinct state files. The moved block works inside a single configuration, so it fits the first two patterns naturally.

Understanding the moved block

A moved block lives in the same module as the old address and maps it to the new address:

moved {
  from = aws_s3_bucket.example
  to   = module.s3_bucket.aws_s3_bucket.this
}

Key points:

• Works for resources, data sources, and module calls, including nested modules.
• Declarative and version‑controlled — survives plan/apply cycles and code reviews.
• Only affects plan and apply; ignored during destroy.
• Cannot move resources across separate state files or workspaces — use terraform state mv or import for that.

Worked example: extracting an S3 bucket into a child module

1. Starting state (monolithic root)

# root/main.tf
terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

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

resource "aws_s3_bucket" "example" {
  bucket = "my-app-logs-12345"
  tags = {
    Environment = "prod"
  }
}

Run the usual workflow (requires AWS credentials with s3:CreateBucket permission):

1. terraform init – initializes the provider.
2. terraform apply – creates the bucket; state now contains aws_s3_bucket.example.

2. Create the child module

# modules/s3/main.tf
variable "bucket_name" { type = string }
variable "tags" { type = map(string) }

resource "aws_s3_bucket" "this" {
  bucket = var.bucket_name
  tags   = var.tags
}

# modules/s3/outputs.tf
output "bucket_arn" {
  value = aws_s3_bucket.this.arn
}

3. Update the root module to call the child module and add a moved block

# root/main.tf (updated)
module "s3_bucket" {
  source      = "./modules/s3"
  bucket_name = "my-app-logs-12345"
  tags = {
    Environment = "prod"
  }
}

moved {
  from = aws_s3_bucket.example
  to   = module.s3_bucket.aws_s3_bucket.this
}

Now run:

1. terraform init – picks up the new module source.
2. terraform plan – should show no changes (the moved block tells Terraform the resource already exists at the new address).
3. terraform apply – updates the state mapping; the bucket is not recreated.

Verify the state mapping:

terraform state list
# before: aws_s3_bucket.example
# after:  module.s3_bucket.aws_s3_bucket.this

If the plan shows a destroy/create pair, double‑check that the from address exactly matches the current state entry (including module prefixes) and that the destination address does not already exist in state.

Trade‑offs and limitations

• State‑file scope – moved blocks only work within a single state file. Moving resources between environments that use separate state files still requires terraform state mv or a manual import.
• Destination conflicts – if the target address already exists in state, Terraform errors. Resolve by renaming or removing the conflicting resource first.
• Provider constraints – some providers (e.g., AWS provider v5+) enforce naming rules that may invalidate a move if the new address changes a required attribute.
• Clutter – leaving many moved blocks in the codebase adds noise. A common practice is to open a dedicated refactoring PR, apply the moves in all environments, then remove the blocks in a follow‑up PR.

Actionable closing checklist

1. Identify a cohesive group of resources to extract (e.g., all S3 buckets).
2. Create a child module with inputs/outputs that mirror the current resource arguments.
3. Add a module call in the root module and a matching moved block for each resource.
4. Run terraform init && terraform plan in a non‑production workspace; confirm zero changes.
5. Apply in staging, verify terraform state list reflects the new addresses.
6. Promote the same code to production; repeat the plan/apply verification.
7. After all environments are updated, remove the moved blocks in a cleanup PR.

By following this pattern you keep production resources running while gradually evolving a clean, modular codebase — exactly what Terraform’s moved block was designed for.