Module Design

What Are Modules?

A module is a container for one or more Terraform resources that are used together. Every Terraform configuration is a module — the root module. You can create child modules to encapsulate common patterns, reduce duplication, and enforce standards across teams.

Modules are the primary mechanism for reuse in Terraform. Instead of copying and pasting resource blocks, you create a module once and call it from multiple configurations. Changes to the module propagate to every caller during the next apply.

Module Structure

A module is a directory containing .tf files. The directory name becomes the module name. The standard convention is to include variables.tf, outputs.tf, and main.tf at minimum.

modules/
  vpc/
    variables.tf    # Input variables
    main.tf         # Resource definitions
    outputs.tf      # Output values
    versions.tf     # Provider and version constraints
    README.md       # Documentation

variable "cidr_block" {
  description = "CIDR block for the VPC"
  type        = string

  validation {
    condition     = can(cidrhost(var.cidr_block, 0))
    error_message = "Must be a valid CIDR block."
  }
}

variable "enable_nat_gateway" {
  description = "Whether to create a NAT gateway"
  type        = bool
  default     = true
}

output "vpc_id" {
  description = "ID of the VPC"
  value       = aws_vpc.main.id
}

output "private_subnet_ids" {
  description = "IDs of private subnets"
  value       = aws_subnet.private[*].id
}

Calling Modules

You call a module using a module block in your root configuration. The source argument tells Terraform where to find the module — a local path, a Git URL, the Terraform Registry, or an HTTP URL.

module "vpc" {
  source = "../../modules/vpc"

  cidr_block         = "10.0.0.0/16"
  enable_nat_gateway = true
}

# Reference outputs
resource "aws_instance" "web" {
  subnet_id = module.vpc.private_subnet_ids[0]
}

Module Registry

The Terraform Registry hosts community and official modules. Private registries (Terraform Cloud, GitLab, GitHub with Terraform) serve modules for internal teams. Registry modules are versioned and discoverable.

module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "5.1.2"

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

  azs             = ["us-east-1a", "us-east-1b", "us-east-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"]
}

Module Versioning

Modules should follow semantic versioning. The version constraint determines which releases are acceptable. The ~> operator is the most common constraint — it allows patch and minor updates but blocks major versions.

module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "~> 5.0"  # Allows 5.x.x, blocks 6.0.0
}

module "eks" {
  source  = "./modules/eks"
  version = "1.2.3"   # Exact version — no updates
}

Module Testing

Modules need tests to verify correctness. Terratest is the standard Go-based testing framework. It provisions real infrastructure, validates it, then tears it down.