Safely upgrading a long-neglected Terraform module, and why a `-/+` "must be replaced" line deserves special scrutiny

# Example plan output
  # aws_db_instance.ledger must be replaced
-/+ resource "aws_db_instance" "ledger" {
      ~ engine         = "postgres" -> "postgres"  # forces replacement
      ~ engine_version = "13.4" -> "15.2"          # forces replacement
      ~ id             = "nbi-ledger-prod" -> (known after apply)
    }

  # aws_instance.transfer_service will be updated in-place
  ~ resource "aws_instance" "transfer_service" {
      ~ instance_type = "m5.large" -> "m5.xlarge"  # safe in-place change
    }

# These attribute changes FORCE replacement (immutable):
# - aws_db_instance: engine change
# - aws_instance: availability_zone change
# - aws_subnet: cidr_block change
# - aws_s3_bucket: bucket name change

# These attribute changes are SAFE in-place updates (mutable):
# - aws_instance: instance_type, tags
# - aws_db_instance: instance_class, allocated_storage (increase)
# - aws_security_group: description, tags

# Step 1: Pin everything before you start
# Know your current baseline
cat versions.tf

# versions.tf -- pin current versions
terraform {
  required_version = ">= 1.3.0, < 1.4.0"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 4.67.0"     # Current provider
    }
  }
}

module "rds" {
  source  = "terraform-aws-modules/rds/aws"
  version = "5.2.0"              # Current module version
}

# Step 2: Read changelogs between current and target versions
# Look for: "breaking", "removed", "renamed", "forces replacement"

# Step 3: Bump ONE thing at a time
# Bump provider first, plan, then bump module, plan again

# Step 4: Test in non-production with production-like state
terraform workspace select staging
terraform plan

# Step 5: Read the plan -- every -/+ line is a red alert
terraform plan -out=upgrade.plan
# Review, then apply the saved plan
terraform apply upgrade.plan

resource "aws_db_instance" "ledger" {
  identifier     = "nbi-ledger-prod"
  engine         = "postgres"
  engine_version = "15.2"
  instance_class = "db.r6g.xlarge"

  lifecycle {
    # Terraform will error out rather than destroy this resource
    prevent_destroy = true

    # If replacement is unavoidable, create the new one first
    create_before_destroy = true

    # Stop Terraform fighting over attributes mutated externally
    ignore_changes = [tags["LastBackup"]]
  }
}

# With prevent_destroy, attempting to destroy produces:
Error: Instance cannot be destroyed

  Resource aws_db_instance.ledger has lifecycle.prevent_destroy
  set, but the plan calls for this resource to be destroyed.

# WRONG: Bump provider, module, AND Terraform core in one go
terraform {
  required_version = ">= 1.6.0"           # was 1.3.0
  required_providers {
    aws = { version = "~> 5.30.0" }       # was 4.67.0
  }
}
module "rds" {
  source  = "terraform-aws-modules/rds/aws"
  version = "6.3.0"                        # was 5.2.0
}
# If the plan shows a -/+, which version caused it?

# CORRECT: Bump one thing at a time
# First: provider 4.67 -> 5.30 alone, plan and test
# Then: module 5.2 -> 6.3 alone, plan and test
# Finally: Terraform core 1.3 -> 1.6, plan and test

# Before provider upgrade: plan shows no changes
No changes. Your infrastructure matches the configuration.

# After provider upgrade (same HCL, same state):
  # aws_db_instance.ledger must be replaced
-/+ resource "aws_db_instance" "ledger" {
      ~ ca_cert_identifier = "rds-ca-2019" -> "rds-ca-rsa2048-g1"
      # forces replacement (new provider default changed)
    }

# A module renames aws_instance.web to aws_instance.app internally
# Without state mv, Terraform sees: destroy web, create app
# With state mv:
terraform state mv \
  module.compute.aws_instance.web \
  module.compute.aws_instance.app

# Now plan shows no changes -- the resource was just renamed in state

# Save and apply the exact reviewed plan
terraform plan -out=upgrade.plan
# Review the plan file
terraform show upgrade.plan
# Apply only after review
terraform apply upgrade.plan