Zero-Downtime Refactoring with Moved & Import Blocks

In this module, you'll learn to:

• Rename and restructure resources with moved blocks, without destroying them
• Bring existing resources under Terraform with import blocks
• Stop managing a resource without deleting it, using removed blocks

Before you start: read Modern HCL. Its switch from count to for_each is a typical refactor that needs moved blocks.

Code refactoring must not cause resource recreation

In the early days of Terraform, renaming a resource or moving it into a child module meant running risky, manual CLI commands:

# DANGEROUS LEGACY APPROACH: Manual CLI state manipulation
terraform state mv aws_s3_bucket.logs module.logging.aws_s3_bucket.this

Modern Terraform fixes this by putting the move in the code itself, so it's reviewed and applied together with the change.

Refactoring with declarative moved blocks

Terraform 1.1 added the moved {} block. It tells Terraform that a resource has a new address. The plan shows the move, and the apply updates state, without touching the real resource.

Scenario A: Moving an existing resource into a module

# In environments/prod/main.tf

# 1. New module call replacing the old standalone resource
module "storage" {
  source      = "../../modules/secure-s3-bucket"
  bucket_name = "corp-data-lake-prod"
}

# 2. Declarative state migration record
moved {
  from = aws_s3_bucket.data_lake
  to   = module.storage.aws_s3_bucket.this
}

When you run terraform plan, Terraform prints: aws_s3_bucket.data_lake has moved to module.storage.aws_s3_bucket.this with 0 to add, 0 to change, 0 to destroy, as long as the module configures the bucket the same way the old resource did. If the plan shows changes, compare the module's settings with the old ones before applying.

Scenario B: Migrating from a single resource to for_each

# Before: Single resource
# resource "aws_subnet" "public" { ... }

# After: Converted to for_each map
resource "aws_subnet" "public" {
  for_each          = var.subnets
  cidr_block        = each.value.cidr
  availability_zone = each.value.az
}

# Preserve the original resource's state under the new map key
moved {
  from = aws_subnet.public
  to   = aws_subnet.public["us-east-1a"]
}

Declarative adoption with import blocks

Before Terraform 1.5, adopting unmanaged AWS resources required running terraform import <addr> <id>, followed by hand-writing HCL to match reality.

Terraform 1.5+ allows you to import resources declaratively:

# import.tf

import {
  to = aws_security_group.ingress
  id = "" # the existing resource ID in AWS
}

You can even ask Terraform to write the initial HCL for you:

terraform plan -generate-config-out=generated_sg.tf

Review the generated file, remove arguments that only repeat defaults, commit it, and run terraform apply. The resource is now managed by Terraform, with no manual state commands.

Safely detaching resources with removed blocks

In Terraform 1.7+, if you want to stop managing a resource in Terraform without deleting the underlying infrastructure in AWS, use the removed {} block:

# main.tf

# Stop managing an Aurora cluster without destroying data
removed {
  from = aws_rds_cluster.legacy

  lifecycle {
    destroy = false # Drops from state, leaves cluster running in AWS!
  }
}

Refactoring without downtime

1. Change the code and add moved in the same commit. Never remove the old resource in one commit and add the move in another.
2. Read the plan. You want Plan: 0 to add, 0 to change, 0 to destroy. If it shows a destroy, stop: the from or to address is wrong.
3. Keep moved blocks until everyone has applied them. Remove one only after every environment and every open branch using this code has applied it. In a shared module that other teams use, keep them for good.

Key terms

• moved block: records a new address for an existing resource, reviewed and applied together with the code change (Terraform 1.1+).
• import block: adopts an existing resource declaratively (1.5+). terraform plan -generate-config-out drafts its HCL.
• removed block with destroy = false: drops a resource from state but leaves it running (1.7+).
• terraform state mv: the older manual command. It isn't reviewed, and it can run out of step with the code.

Pop quiz

Five questions: three on the ideas in this module, and two scenarios where you apply them. The order changes every time you take it, and 4 out of 5 passes.