Skip to main content
RunBook Academy

← All break/fix scenarios in Terraform

advancedterraform-supply-chain~25 min

Break/Fix: Module Upgrade Changes Resource Addresses

Reported symptoms

  • ●After a module upgrade, the plan proposes to destroy and recreate resources
  • ●The configuration has not changed
  • ●The real-world resources are still operational
  • ●The plan shows destroy + create for the same resources

Evidence

  • · The module was upgraded from 1.0.0 to 1.1.0
  • · The module moved resources from `aws_instance.web` to `aws_instance.server`
  • · The state has `aws_instance.web`
  • · The plan proposes to destroy `aws_instance.web` and create `aws_instance.server`
Diagnosis and resolutionclick to reveal

Root cause

The module upgrade renamed the resource inside the module. The state has the old name; the module declares the new name.

Remediation

1. Identify the cause. 2. Add a `moved` block. 3. Re-plan. 4. Verify the plan is empty.

Verification

The plan is empty after the `moved` block. The state has the new resource address.

Prevention

- Use `moved` blocks when refactoring modules. - Test module upgrades in a development environment. - Read the module release notes for breaking changes.

Scenario

You are operating a production Terraform estate. The team upgraded the terraform-aws-modules/vpc/aws module from 5.0.0 to 5.1.0. The next plan is scheduled for the maintenance window. You run terraform plan and see:

# module.network.aws_vpc.main will be destroyed
- resource "aws_vpc" "main" {
    - cidr_block = "10.0.0.0/16" -> null
  }

# module.network.aws_vpc.this will be created
+ resource "aws_vpc" "this" {
    + cidr_block = "10.0.0.0/16"
  }

Plan: 1 to add, 0 to change, 1 to destroy.

The plan proposes to destroy the VPC and recreate it. The configuration has not changed.

Your task

Investigate the cause and recover without destroying the real VPC.

Evidence to discover

# Check the module release notes
# (the modules CHANGELOG is on GitHub)

# Check the modules source
grep -A5 "source" versions.tf

# Check the previous state
terraform state list

Questions to answer

  1. What changed in the module?
  2. Is the change intentional?
  3. What is the correct remediation?
  4. What is the verification step?

Recovery procedure

(Do not reveal this until the student has reasoned through the problem.)

  1. Read the module release notes. The 5.1.0 release renamed the resource inside the module from aws_vpc.main to aws_vpc.this.
  2. Identify the cause. The module upgraded the resource address. The state has the old address.
  3. Add a moved block.
# main.tf
moved {
  from = module.network.aws_vpc.main
  to   = module.network.aws_vpc.this
}
  1. Re-plan.
terraform plan

The plan should be empty.

  1. Verify the state.
terraform state list

The state should have module.network.aws_vpc.this.

  1. Document the incident. The module upgrade, the changed address, the moved block.

Remediation

  • The cause was the modules renamed resource.
  • The moved block preserves the state.
  • The plan is empty after the moved block.
  • The next apply is a no-op.

Prevention

  • Use moved blocks when refactoring modules.
  • Test module upgrades in a development environment.
  • Read the module release notes for breaking changes.
  • Pin module versions deliberately.
  • Document the upgrade in the runbook.

What you learned

  • A module upgrade may break the resource addresses.
  • A moved block tells Terraform that the resource has been moved.
  • The state is updated to reflect the new address.
  • The plan is empty after the moved block.
  • The moved block is the under-used feature that allows refactoring without recreating resources.