Registry #

# The most widely used VPC module
module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "~> 5.0"

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

  azs             = ["ap-southeast-1a", "ap-southeast-1b", "ap-southeast-1c"]
  private_subnets = ["10.0.1.0/24", "10.0.2.0/24", "10.0.3.0/24"]
  public_subnets  = ["10.0.101.0/24", "10.0.102.0/24", "10.0.103.0/24"]

  enable_nat_gateway = true
  single_nat_gateway = false  # Per-AZ NAT Gateway for HA

  tags = {
    Environment = "production"
    ManagedBy   = "terraform"
  }
}

# The EKS module
module "eks" {
  source  = "terraform-aws-modules/eks/aws"
  version = "~> 20.0"

  cluster_name    = "production-eks"
  cluster_version = "1.29"

  vpc_id     = module.vpc.vpc_id
  subnet_ids = module.vpc.private_subnets

  eks_managed_node_groups = {
    general = {
      min_size     = 2
      max_size     = 5
      desired_size = 2
      instance_types = ["t3.medium"]
    }
  }
}

# The RDS module
module "rds" {
  source  = "terraform-aws-modules/rds/aws"
  version = "~> 6.0"

  identifier        = "production-db"
  engine            = "postgres"
  engine_version    = "15"
  instance_class    = "db.t3.medium"
  allocated_storage = 100

  db_name  = "appdb"
  username = "dbadmin"

  vpc_security_group_ids = [module.security_group.security_group_id]
  subnet_ids             = module.vpc.database_subnets
}

# OPTION 1: Terraform Cloud / HCP Terraform Private Registry
# Modules are uploaded and managed via the UI or API
module "vpc" {
  source  = "app.terraform.io/my-org/vpc/aws"
  version = "~> 2.0"
  # Terraform Cloud handles authentication and versioning
}

# OPTION 2: Git repository with tags — the simplest
# No extra infrastructure needed
module "vpc" {
  source = "git::https://github.com/my-org/terraform-module-vpc.git?ref=v2.1.0"
}

# Or with SSH for private repos
module "vpc" {
  source = "git::ssh://[email protected]/my-org/terraform-module-vpc.git?ref=v2.1.0"
}

# OPTION 3: Gitea, GitLab, or Bitbucket as a module registry
# GitLab has a built-in Terraform Module Registry
module "vpc" {
  source  = "gitlab.example.com/infrastructure/vpc/aws"
  version = "~> 1.0"
}

# Wrapper pattern: wrap a public module with a simpler interface
# modules/internal-vpc/main.tf

module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "~> 5.0"

  # Opinionated configuration for internal standards
  name = var.name
  cidr = var.cidr

  # AZs and subnets are calculated automatically — callers don't need to know these details
  azs             = data.aws_availability_zones.available.names
  private_subnets = [for k, v in data.aws_availability_zones.available.names : cidrsubnet(var.cidr, 4, k)]
  public_subnets  = [for k, v in data.aws_availability_zones.available.names : cidrsubnet(var.cidr, 4, k + 8)]

  # Internal standards that can't be overridden
  enable_nat_gateway   = true
  single_nat_gateway   = false
  enable_dns_hostnames = true
  enable_dns_support   = true

  tags = merge(var.tags, local.mandatory_tags)
}

# A much simpler interface for internal users
# Only needs 2 required variables:
variable "name" { type = string }
variable "cidr" { type = string }
variable "tags" { type = map(string); default = {} }

# Public Registry (registry.terraform.io):
# 1. Push to GitHub with a semver tag
git tag v1.0.0
git push origin v1.0.0
# 2. Log in to registry.terraform.io
# 3. Add module → Select the GitHub repo
# 4. Terraform automatically detects tags as versions

# Private Registry (Terraform Cloud):
# 1. Push to a VCS connected to TFC
# 2. TFC → Registry → Publish Module
# 3. The module is only accessible by your org

# Using a module from the registry
module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "~> 5.0"
  
  name = "my-vpc"
  cidr = "10.0.0.0/16"
  
  azs             = ["ap-southeast-1a", "ap-southeast-1b"]
  private_subnets = ["10.0.1.0/24", "10.0.2.0/24"]
  public_subnets  = ["10.0.101.0/24", "10.0.102.0/24"]
  
  enable_nat_gateway = true
}

# Setting up a private registry in Terraform Cloud:
# 1. Connect a VCS provider (GitHub/GitLab/Bitbucket)
# 2. Publish module → Select repository
# 3. Terraform auto-detects tags as versions
# 4. The module is available at: app.terraform.io/{org}/{module}/{provider}

# Using a module from the private registry
module "app" {
  source  = "app.terraform.io/my-org/app/aws"
  version = "~> 2.0"
}

# Auto-generate module documentation
brew install terraform-docs
terraform-docs markdown table . > README.md

# Example output:
# | Name | Description | Type | Default | Required |
# |------|-------------|------|---------|----------|
# | vpc_cidr | CIDR block for the VPC | string | n/a | yes |
# | environment | Environment name | string | n/a | yes |
# | enable_nat | Enable NAT gateway | bool | true | no |

# Publish a module with good documentation
# 1. Write a README.md with usage examples
# 2. All variables have descriptions
# 3. All outputs have descriptions
# 4. Include a CHANGELOG.md
# 5. Git tag with semver (v1.2.3)

BEFORE PUBLISHING:

□ All variables have descriptions
□ All outputs have descriptions
□ README.md is complete with usage examples
□ CHANGELOG.md records all changes
□ Tests pass (terraform validate, tflint)
□ Version tag with semver
□ License file present
□ .gitignore doesn't exclude needed files
□ Examples directory with usage examples
□ terraform-docs generates the documentation

# Pre-publish validation
terraform fmt -check
terraform validate
tflint .
terraform-docs markdown . > README.md

# Tag and publish
git tag -a v1.0.0 -m "Release v1.0.0: Initial release"
git push origin v1.0.0

DEPENDENCY ORDER:

1. Foundation modules (no dependencies)
   - networking (VPC, subnets)
   - security (KMS, IAM)
   
2. Platform modules (depend on foundation)
   - compute (needs networking)
   - database (needs networking)
   
3. Application modules (depend on platform)
   - monitoring (needs compute, database)
   - ci-cd (needs compute)

# Module version pinning strategy
# The root module pins an exact version
module "networking" {
  source  = "app.terraform.io/my-org/networking/aws"
  version = "2.3.1"  # Exact pin for production
}

# Dev can use the latest
module "networking" {
  source  = "app.terraform.io/my-org/networking/aws"
  version = "~> 2.0"  # Allow minor updates
}