Upgrade Strategies

# .terraform.lock.hcl — what it looks like and what each section means

provider "registry.terraform.io/hashicorp/aws" {
  version     = "5.31.0"  # Exact version locked — not a range
  constraints = "~> 5.0"  # The constraint from versions.tf that was satisfied

  hashes = [
    # h1: hash is the primary checksum for the installed provider binary
    "h1:abc123...",
    # zh: hashes are cross-platform checksums — allows the same lock file to be
    # used on macOS (darwin), Linux (linux), and Windows (windows)
    "zh:0a1b2c...",
    "zh:3d4e5f...",
  ]
}

# Rules for the lock file:
# 1. ALWAYS commit to Git — it must be in source control
# 2. NEVER edit manually — let terraform init manage it
# 3. Review lock file changes in PR just like code changes
#    A lock file update that bumps AWS provider 4.x -> 5.x is a major change
#    It should be reviewed with the same care as a code change

# Check what is currently locked
cat .terraform.lock.hcl

# Verify providers match the lock file (check for tampering)
terraform providers lock

# Step 1: Check your current required_version constraint
# In versions.tf:
terraform {
  required_version = ">= 1.5.0"  # Allows any 1.x at or above 1.5.0
  # Alternatively: "~> 1.5" — allows 1.5.x and 1.6.x but not 2.0
}

# Step 2: Read the Terraform release notes
# https://github.com/hashicorp/terraform/releases
# Look for: BREAKING CHANGES section — usually empty for minor/patch releases
# Look for: Provider compatibility notes — some providers require minimum Terraform versions

# Step 3: Install the new Terraform version
# Using tfenv (Terraform version manager — recommended)
tfenv install 1.6.3       # Install specific version
tfenv use 1.6.3           # Switch to it
terraform version         # Verify: Terraform v1.6.3

# Step 4: Run init and validate — no infrastructure changes
terraform init            # Re-download providers if needed for the new Terraform version
terraform validate        # Check for syntax or compatibility issues

# Step 5: Run plan — look for unexpected diffs
terraform plan            # Should match what you expect — no surprise changes from the upgrade

# Step 6: Update required_version to document the minimum
# If upgrading to 1.6.x:
terraform {
  required_version = ">= 1.6.0"  # Update to reflect the new minimum
}

# Step 7: Update lock file and commit
git add .terraform.lock.hcl versions.tf
git commit -m "upgrade: Terraform core 1.5.x -> 1.6.3"

# Tip: Use tfenv in CI/CD to match the version pinned in versions.tf
# .terraform-version file in the repo root — tfenv reads it automatically
echo "1.6.3" > .terraform-version

# Minor version upgrade — safe, apply in a single step

# versions.tf — update constraint to allow the new minor version
terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"  # Was "~> 5.0" — constraint already allows 5.31 -> 5.40
    }
  }
}

# Update the lock file to the latest allowed version
terraform init -upgrade  # Upgrades within the constraint (~> 5.0 → latest 5.x)
terraform plan           # Verify: no unexpected changes

git add .terraform.lock.hcl
git commit -m "upgrade: AWS provider 5.10 -> 5.31"

# ─────────────────────────────────────────────────────────────────────────────

# Major version upgrade — must be done carefully

# Step 1: Read the CHANGELOG — find all BREAKING CHANGES
# https://github.com/hashicorp/terraform-provider-aws/releases
# Search for: "BREAKING CHANGE", "removed", "renamed", "deprecated"

# Step 2: Check your code against the migration guide
# HashiCorp publishes upgrade guides for major provider versions:
# https://registry.terraform.io/providers/hashicorp/aws/latest/docs/guides/version-4-upgrade
# https://registry.terraform.io/providers/hashicorp/aws/latest/docs/guides/version-5-upgrade

# Step 3: Update the constraint to allow the major version
terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"  # Was "~> 4.0" — change the major version bound
    }
  }
}

# Step 4: Run init -upgrade to download the new major version
terraform init -upgrade  # Downloads 5.x — different code from 4.x

# Step 5: Run validate — many breaking changes are caught here
terraform validate       # Likely shows errors for removed/renamed arguments

# Step 6: Fix all validation errors BEFORE running plan
# Removed arguments: delete or replace with the new resource
# Renamed arguments: update to new names
# Changed defaults: explicitly set the old default to maintain current behaviour

# Step 7: Run plan and read EVERY line
terraform plan           # Some resources may show -/+ (destroy and recreate!)
# A -/+ on a database means downtime — address it before applying

# AWS Provider v4 -> v5: The major breaking changes

# BREAKING CHANGE 1: S3 bucket attributes split into sub-resources (v4 change, still relevant)
# Before (provider v3):
resource "aws_s3_bucket" "app" {
  bucket = "my-app-bucket"
  acl    = "private"                    # REMOVED in v4
  versioning { enabled = true }         # REMOVED in v4
  server_side_encryption_configuration { # REMOVED in v4
    rule {
      apply_server_side_encryption_by_default {
        sse_algorithm = "AES256"
      }
    }
  }
}

# After (provider v4+):
resource "aws_s3_bucket" "app" {
  bucket = "my-app-bucket"
  # No acl, no versioning, no encryption — all moved to sub-resources
}

resource "aws_s3_bucket_acl" "app" {
  bucket = aws_s3_bucket.app.id
  acl    = "private"
}

resource "aws_s3_bucket_versioning" "app" {
  bucket = aws_s3_bucket.app.id
  versioning_configuration { status = "Enabled" }
}

resource "aws_s3_bucket_server_side_encryption_configuration" "app" {
  bucket = aws_s3_bucket.app.id
  rule {
    apply_server_side_encryption_by_default { sse_algorithm = "AES256" }
  }
}

# BREAKING CHANGE 2: Default tags behaviour changed in v5
# v4: default_tags merged with resource tags using resource tags taking precedence
# v5: conflict between default_tags and resource tags causes an error
# Fix: Remove any tag keys from resource blocks that also appear in default_tags

# BREAKING CHANGE 3: EC2 instance metadata options changed defaults
# v5: metadata_options.http_tokens defaults to "required" (IMDSv2 only)
# This means existing EC2 instances that use IMDSv1 will show a drift diff
# Fix: Explicitly set http_tokens = "optional" to maintain old behaviour
# OR migrate your applications to use IMDSv2

resource "aws_instance" "app" {
  # ... other config ...

  metadata_options {
    http_tokens                 = "required"   # Recommended: require IMDSv2
    http_put_response_hop_limit = 1
    instance_metadata_tags      = "disabled"
  }
}

# MIGRATION APPROACH: The two-phase upgrade
# Phase 1: Update code to be compatible with BOTH v4 and v5 simultaneously
#   - Add sub-resources for S3 (they work in v4 too)
#   - Explicitly set all previously-defaulted options
#   - Apply this code change against v4 — verify nothing breaks
# Phase 2: Upgrade the provider constraint to v5
#   - terraform init -upgrade
#   - terraform validate (should pass after Phase 1 fixes)
#   - terraform plan (should show minimal or no changes)
#   - Apply

# required_version in the root configuration
terraform {
  # Best practice: lower bound only — allows any version at or above the minimum
  # This lets the team upgrade Terraform without changing the constraint
  required_version = ">= 1.5.0"

  # Alternative: tilde operator for tighter control
  # ~> 1.5 allows 1.5.x and 1.6.x but NOT 2.0
  required_version = "~> 1.5"

  # Avoid: exact pin in the root configuration
  required_version = "= 1.5.4"
  # This forces every engineer and every CI pipeline to use exactly 1.5.4
  # Every patch release requires a configuration change — unnecessary overhead

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      # In root modules: use ~> for provider constraints
      # ~> 5.0 allows 5.x but not 6.0 — protects from unintended major upgrades
      version = "~> 5.0"
    }
  }
}

# required_version in reusable modules
# Modules should be MORE permissive — not less — to avoid forcing callers to upgrade
terraform {
  # Lower bound only — module works with any sufficiently recent Terraform
  required_version = ">= 1.3.0"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      # In modules: >= not ~> — the caller's root module controls the upper bound
      version = ">= 4.0, < 6.0"  # Works with v4 and v5 — caller chooses
      # Avoid: version = "~> 5.0" in a module — forces all callers to use 5.x
    }
  }
}

# The tfenv .terraform-version file — pin the exact version for CI/CD
# Place in repository root — tfenv reads it automatically
# All engineers and pipelines use the same Terraform version
# To upgrade: update this file, update required_version, run tests, commit
cat .terraform-version
# 1.6.3

# THE TERRAFORM UPGRADE RUNBOOK
# Follow in this exact order — no skipping steps

# ── Step 1: Read the changelog BEFORE touching any code ──────────────────────
# Terraform core:   github.com/hashicorp/terraform/releases
# AWS provider:     github.com/hashicorp/terraform-provider-aws/releases
# Azure provider:   github.com/hashicorp/terraform-provider-azurerm/releases
# GCP provider:     github.com/hashicorp/terraform-provider-google/releases
# Look for: BREAKING CHANGES, deprecated arguments, changed defaults, removed resources

# ── Step 2: Create a dedicated upgrade branch ─────────────────────────────────
git checkout -b upgrade/aws-provider-5x

# ── Step 3: Update the version constraint ────────────────────────────────────
# versions.tf: change "~> 4.0" to "~> 5.0"

# ── Step 4: Download the new version ─────────────────────────────────────────
terraform init -upgrade  # -upgrade re-resolves against new constraints

# ── Step 5: Fix all validation errors ────────────────────────────────────────
terraform validate
# Fix every error before proceeding — do not move to plan with validation errors

# ── Step 6: Run plan against DEV environment ──────────────────────────────────
terraform plan -var="environment=dev" | tee upgrade-plan-dev.txt
# Critically examine:
# -/+ entries: resources being destroyed and recreated (potential downtime)
# ~ entries:   in-place modifications (usually safe, but read them)
# + entries:   new resources being created (fine)
# Any -/+ on databases, load balancers, or critical resources = STOP, investigate

# ── Step 7: Apply to DEV, verify, monitor ─────────────────────────────────────
terraform apply -var="environment=dev"
# Wait 30 minutes — watch for alarms, logs, errors
# Smoke test the application — key user journeys still work

# ── Step 8: Apply to STAGING, verify, monitor ─────────────────────────────────
terraform apply -var="environment=staging"
# Wait 24 hours minimum for staging — let any delayed failures surface

# ── Step 9: Open PR for production ────────────────────────────────────────────
# PR includes: changelog link, plan output for prod, test results from dev/staging
# PR requires review from a second engineer — peer review of infrastructure change

# ── Step 10: Apply to PRODUCTION with approval ────────────────────────────────
# Only after PR approval — apply during a low-traffic maintenance window
# Have a rollback plan: lock file from before the upgrade is in Git history
# Monitor for 30 minutes after apply completes

# ── Step 11: Rollback procedure ───────────────────────────────────────────────
# If something goes wrong after the provider upgrade:
git show HEAD~1:.terraform.lock.hcl > .terraform.lock.hcl  # Restore old lock file
# Revert the versions.tf constraint change
terraform init    # Re-downloads old provider version matching the restored lock file
terraform plan    # Verify the old provider works — should show no changes or the reverse
# Note: you cannot always roll back provider changes that modified resource attributes