Break/Fix: Unexpected Replace from Provider Schema Change

Scenario

You are operating a production Terraform estate. The team upgraded the AWS provider from 5.0 to 5.5. The next plan is scheduled for the maintenance window. You run terraform plan and see:

# aws_instance.web must be replaced
-/+ resource "aws_instance" "web" {
    ~ ami           = "ami-0e1bed4f" -> "ami-9ad034sd" # forces replacement
    # ...
  }

# aws_security_group.web must be replaced
-/+ resource "aws_security_group" "web" {
    ~ name_prefix = "web-" -> "web-" # forces replacement
    # ...
  }

Plan: 0 to add, 0 to change, 47 to replace.

The plan proposes to replace 47 resources. The expected plan was “0 to add, 0 to change, 0 to destroy”.

Your task

Investigate the cause of the plan and decide the correct remediation.

Evidence to discover

# Check the provider version
terraform providers

# Check the recent provider updates
git log --oneline -10 .terraform.lock.hcl

# Read the provider release notes
# (the release notes link is in the provider repository)

# Check the resource documentation
# (the resource arguments are documented in the provider docs)

Questions to answer

1. What changed in the provider? The release notes document the breaking changes.
2. Why is the replacement forced? The providers schema marks the attribute as immutable.
3. Is the change intentional? The change may be a new default (e.g. a new AMI).
4. What is the correct remediation? Either pin the attribute to the old value, or accept the replacement.

Recovery procedure

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

1. Identify the cause. The provider upgrade introduced a new default for an attribute. The provider marks the attribute as immutable.
2. Verify the change is intentional. Read the release notes. Confirm the new default is correct.
3. Decide the remediation.
   • Pin the attribute. Add the attribute to the configuration with the old value.
   • Accept the replacement. Apply the plan and accept the replacement. Verify the data is preserved.
4. Apply the chosen remediation.
   • If pinning: update the configuration, run terraform plan, verify the plan is empty.
   • If accepting: run terraform apply, verify the replacements complete.
5. Document the incident. The provider upgrade, the change, the remediation.

Remediation

The cause was the provider upgrade introducing a new default. The new default was incompatible with the existing attribute (the provider marks it as immutable). The team decided to pin the attribute to the old value. The plan is now empty.

Prevention

• Read the provider release notes before every upgrade.
• Pin attributes that have provider defaults.
• Test the upgrade in a development environment.
• Use -refresh-only after the upgrade to check for drift before planning.

What you learned

• A provider upgrade may introduce a new default.
• The new default may trigger replacement.
• The replacement is the providers decision, not the operator’s.
• The remediation is to pin the attribute, not to revert the upgrade.
• Read the release notes before every upgrade.