Composition and Nested Modules

Real systems are built by composing modules — a root module calling a network module, a compute module, and a data module, wiring one's outputs into another's inputs. The art is keeping the composition shallow and the data flow one-directional. Modules calling modules calling modules become impossible to reason about or debug well before they technically break.

Composition is where modules stop being a convenience and become an architecture. Done well, the root reads like a wiring diagram of the system. Done badly, a single change means opening five directories to trace where a value comes from, and a dependency cycle appears at apply time with no obvious cause.

The Composition Pattern

The root module is the wiring layer. It calls a handful of focused child modules and connects them by passing the outputs of one as the inputs of the next — the network module's subnet IDs become the compute module's input. The children do not know about each other; the root holds the knowledge of how they fit together. That keeps each module reusable in isolation and confines the system-specific wiring to one place.

module "network" {
  source     = "./modules/vpc"
  cidr_block = "10.0.0.0/16"
  az_count   = 3
}

module "compute" {
  source        = "./modules/asg"
  # one module's output becomes another's input
  subnet_ids    = module.network.private_subnet_ids
  instance_type = "t3.medium"
}

Flat vs Deeply Nested

A child module can call its own children, and a little of that is fine. The failure mode is depth: a root that calls a module that calls a module that calls a module, three or four levels down. To change one value you open every level to trace it, and an output at the bottom has to be re-exported through every layer above to reach the top. Most teams favor a shallow tree — a root composing a small number of single-purpose modules — over a deep one, because shallow stays legible.

Data Flow Between Modules

Wire modules with the specific values each needs, and keep the flow in one direction. module.network.private_subnet_ids feeds module.compute, which produces an autoscaling group name that feeds module.monitoring — a clean one-way chain. Passing a whole undifferentiated object between modules instead of the two values one actually needs couples them tightly: the consumer now depends on the entire shape of the producer, and a change anywhere in it ripples through.

The Wrapper Module Pattern

A wrapper is a thin internal module that wraps a third-party one to standardize its use. Instead of every team calling the community VPC module directly with its full surface, they call your modules/network wrapper, which sets your tags and naming, pins the upstream version, and exposes only the inputs your org allows. It is one level of nesting that earns its keep — a single point to upgrade and enforce standards — as opposed to the gratuitous depth of modules nested for no reason.

Avoiding Hidden Cycles

Module wiring can create a dependency cycle that is invisible in any single file. If module A takes an input from module B and module B takes an input from module A, Terraform sees a loop and fails — but because the edges are spread across two module blocks, the cause is not obvious from either one alone. Designing module interfaces so data flows one direction prevents this; when a cycle does appear, the fix is to break the bidirectional wiring, often by moving a value up to the root, not to paper over it with depends_on.