Enterprise Module Architecture & Registry Design
Master enterprise Terraform module design: Root vs Child modules, composition patterns, version pinning, public/private registries, and module testing.
Enterprise Module Architecture & Registry Design
Section titled βEnterprise Module Architecture & Registry Designβ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.
1. Anatomy of a Standard Enterprise Module
Section titled β1. Anatomy of a Standard Enterprise Moduleβ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 sandboxes2. Root Modules vs. Child Modules
Section titled β2. Root Modules vs. Child Modulesβ| 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 |
3. Module Composition: Passing Data Cleanly
Section titled β3. Module Composition: Passing Data Cleanlyβ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:
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!}4. Module Sourcing & Version Pinning Strategies
Section titled β4. Module Sourcing & Version Pinning Strategiesβ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=mainmeans an untested commit pushed by another engineer can instantly break your nextterraform planor introduce unexpected infrastructure mutations. Always cut tagged releases (?ref=v1.2.0).