Skip to content
About Me
----

Enterprise Module Architecture & Registry Design

Architect Key Takeaways

Master enterprise Terraform module design: Root vs Child modules, composition patterns, version pinning, public/private registries, and module testing.

In small personal projects, dumping everything into a single main.tf might work. In enterprise platforms supporting hundreds of microservices, this leads to monolithic state files, merge collisions, and unmaintainable code.

Modules are the foundational building block of scalable Infrastructure as Code. They encapsulate complexity, enforce organizational security baselines, and enable team-wide reusability.


A well-structured Terraform module follows HashiCorp’s standard layout convention:

terraform-aws-secure-vpc/
β”œβ”€β”€ README.md # Documentation, input/output tables, architectural diagram
β”œβ”€β”€ main.tf # Core resource declarations (VPC, Subnets, Route Tables)
β”œβ”€β”€ variables.tf # Strict input variables with types and validations
β”œβ”€β”€ outputs.tf # Exported IDs, ARNs, and CIDR blocks for consumers
β”œβ”€β”€ versions.tf # Minimum Terraform and provider versions
└── examples/ # Complete, runnable usage examples
β”œβ”€β”€ complete/ # Multi-AZ HA deployment with NAT Gateways
└── minimal/ # Lightweight VPC for development sandboxes

Dimension Root Module (Environment Orchestration) Child Module (Reusable Component)
Location environments/prod/, environments/dev/ modules/vpc/, modules/eks/, Git Registry
State File Owns the state file (terraform.tfstate) Has no state file; consumed as a component
Backend Declares backend "s3" { ... } Never defines a backend
Purpose Glues together reusable child modules Abstract, parameterized, and environment-agnostic

Instead of monolithic modules that attempt to build an entire company’s infrastructure in one shot, compose specialized, decoupled modules together in your Root Module:

environments/prod/main.tf
module "vpc" {
source = "terraform-aws-modules/vpc/aws"
version = "~> 5.5"
name = "prod-core-network"
cidr = "10.100.0.0/16"
azs = ["us-east-1a", "us-east-1b", "us-east-1c"]
private_subnets = ["10.100.1.0/24", "10.100.2.0/24", "10.100.3.0/24"]
public_subnets = ["10.100.101.0/24", "10.100.102.0/24", "10.100.103.0/24"]
enable_nat_gateway = true
single_nat_gateway = false # True High Availability across 3 AZs
}
# The EKS module consumes outputs from the VPC module:
module "eks" {
source = "terraform-aws-modules/eks/aws"
version = "~> 20.0"
cluster_name = "prod-platform-eks"
cluster_version = "1.30"
vpc_id = module.vpc.vpc_id
subnet_ids = module.vpc.private_subnets # Securely deployed in private subnets!
}

Never reference the main branch directly in production. Always pin to immutable releases:

# 1. Public Terraform Registry (SemVer Pinning)
module "s3_bucket" {
source = "terraform-aws-modules/s3-bucket/aws"
version = "~> 3.15.0"
}
# 2. Private Git Repository (Tagged Commit / Semantic Version)
module "security_baseline" {
source = "git::https://github.com/my-corp/terraform-aws-baseline.git?ref=v2.4.1"
}
# 3. Local File System (Monorepo Development)
module "internal_app" {
source = "../../modules/internal-app"
}

[!CAUTION] Avoid Sourcing Unpinned Git Branches: Sourcing ?ref=main means an untested commit pushed by another engineer can instantly break your next terraform plan or introduce unexpected infrastructure mutations. Always cut tagged releases (?ref=v1.2.0).