Versioning #

# Module release workflow:

# 1. Make sure all changes are committed and tested
git add -A
git commit -m "feat: add per-AZ NAT Gateway support"

# 2. Create a tag in the v<MAJOR>.<MINOR>.<PATCH> format
git tag v1.3.0

# 3. Push the tag to the remote
git push origin v1.3.0

# 4. Optional: create a GitHub Release with the changelog
# (via the UI or the GitHub CLI)
gh release create v1.3.0 \
  --title "v1.3.0 — per-AZ NAT Gateways" \
  --notes "NEW: Support per-AZ NAT Gateways via the enable_nat_per_az variable"

# Callers use the tag as the version reference
module "vpc" {
  source = "git::https://github.com/org/terraform-module-vpc.git?ref=v1.3.0"

  cidr_block  = "10.0.0.0/16"
  environment = var.environment
}

# Terraform Registry — version controlled with a version constraint
module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "~> 5.1"
  # ~> 5.1 = >=5.1.0, <6.0.0

  name = "production-vpc"
  cidr = "10.0.0.0/16"
}

# A stricter constraint for production
module "eks" {
  source  = "terraform-aws-modules/eks/aws"
  version = "= 20.2.1"
  # Pin to an exact version — no surprise updates
}

# ANTI-PATTERN: No version constraint on a Registry module
module "vpc" {
  source = "terraform-aws-modules/vpc/aws"
  # No version — every terraform init could get a different version!
}

# MODULE UPGRADE WORKFLOW:

# 1. Read the new version's CHANGELOG — look for breaking changes
# 2. Test in dev/staging first
# 3. Run terraform plan after updating the version

# Configuration change:
# From:
# source = "git::...?ref=v1.2.0"
# To:
# source = "git::...?ref=v2.0.0"

# 4. Read the plan output carefully
terraform plan
# Note which resources will be replaced
# Breaking changes in modules often cause resources to be replaced

# 5. If there's an unwanted replacement, consider:
#    - Do you need a moved block to rename a resource?
#    - Do you need a migration stage before the full upgrade?

# Example: a module renames an internal resource from v1 to v2
# Without a moved block, Terraform will destroy + create

# In the root configuration (not the module):
moved {
  from = module.vpc.aws_subnet.public
  to   = module.vpc.aws_subnet.public_tier  # New name in the v2 module
}

# STRATEGY 1: Deprecation with temporary backward compatibility
# Give a transition period before truly removing old variables/outputs

variable "subnet_id" {
  description = "DEPRECATED: Use subnet_ids. Will be removed in v3.0."
  type        = string
  default     = null

  validation {
    condition     = var.subnet_id == null
    error_message = "subnet_id is deprecated, use subnet_ids (list)."
    # Or let it run but log a warning via a null_resource
  }
}

variable "subnet_ids" {
  description = "List of subnet IDs. Replaces the deprecated subnet_id."
  type        = list(string)
  default     = []
}

locals {
  # Backward compatibility: if subnet_id is set, turn it into a list
  effective_subnet_ids = (
    length(var.subnet_ids) > 0
    ? var.subnet_ids
    : var.subnet_id != null ? [var.subnet_id] : []
  )
}

# PATCH (x.y.Z): Bug fixes that don't change the interface
# Example: fix a typo in a description, fix an incorrect tag
# No breaking change → consumers don't need to change anything
git tag v1.2.1

# MINOR (x.Y.z): New backward-compatible features
# Example: add a new output, add a new optional variable
# Existing consumers aren't affected → safe to upgrade
git tag v1.3.0

# MAJOR (X.y.z): Breaking changes
# Example: remove a variable, change an output type, remove a resource
# Consumers MUST review and update → the upgrade needs planning
git tag v2.0.0

# Exact — only a specific version (too strict for production)
module "vpc" {
  source = "terraform-aws-modules/vpc/aws"
  version = "5.1.2"  # Will never auto-update
}

# Pessimistic — patch updates only (recommended for stability)
module "vpc" {
  source = "terraform-aws-modules/vpc/aws"
  version = "~> 5.1"  # >= 5.1.0, < 5.2.0
}

# Minor updates — including minor and patch
module "vpc" {
  source = "terraform-aws-modules/vpc/aws"
  version = ">= 5.1.0, < 6.0.0"  # All 5.x but not 6.0
}

# For internal modules (you control them):
module "app" {
  source  = "./modules/app"
  version = "~> 2.1"  # Patch updates allowed
}

# For external modules (you don't control them):
module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "~> 5.0"  # Stricter — patches only
}

# For providers (stability is very important):
terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"  # Pessimistic ~> for stability
    }
  }
}

# Check available versions
terraform providers lock -platform=linux_amd64
# Generate a lock file for cross-platform consistency

# Update the provider to the latest version
terraform init -upgrade
# Careful: can change behavior

# Inside a module, DON'T pin the provider version
# Let the root module decide

# Module (modules/networking/main.tf):
terraform {
  required_providers {
    aws = {
      source = "hashicorp/aws"
      # DON'T set the version here
      # Let the root module decide
    }
  }
}

# Root module (main.tf):
terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"  # The version is decided at the root
    }
  }
}

# .terraform.lock.hcl — commit to version control
# This file ensures all developers and CI/CD
# use the same provider versions

# Generate a lock file for multiple platforms
terraform providers lock   -platform=linux_amd64   -platform=darwin_arm64   -platform=windows_amd64

# Update the provider to the latest version
terraform init -upgrade

# Review the lock file changes
git diff .terraform.lock.hcl

# OPERATORS:
# =  (exact):    version = "5.0.0"
# != (exclude):  version != "5.0.0"
# >  (gt):       version > "5.0.0"
# >= (gte):      version >= "5.0.0"
# <  (lt):       version < "6.0.0"
# <= (lte):      version <= "5.5.0"
# ~> (pessimistic): version ~> "5.0" (allows 5.x but not 6.0)

# EXAMPLES:
# ~> 5.0  = >= 5.0, < 6.0
# ~> 5.1  = >= 5.1, < 6.0
# >= 5.0, < 6.0  = same as ~> 5.0

# BEST PRACTICE:
# Registry modules:  use ~> for minor versions
# Providers:         use ~> for major versions
# Internal modules:  pin the exact version