Composition Patterns

## What "composition" means in Terraform The directory you run `terraform plan` in is the **root module**. Any `module` block inside it calls a **child module** — another directory of `.tf` files — with a `source` argument and a set of input variables. Composition is the practice of having the root call several small child modules side by side and wire them together by passing one module's output into another's input. Nesting is the opposite shape: the root calls one module, which calls another, which calls another, and the real resources sit at the bottom of the tree. Both shapes produce the same infrastructure. The difference is entirely about what a human can see and change. ```hcl # root main.tf — flat composition, wiring visible in one file module "network" { source = "./modules/network" cidr = "10.0.0.0/16" } module "database" { source = "./modules/database" subnet_ids = module.network.private_subnet_ids } ``` The reference `module.network.private_subnet_ids` is not just data passing: it is what creates the dependency edge in Terraform's graph, so the network is created before the database without anyone saying so explicitly. ## Depth taxes every value that crosses it Suppose the deepest module needs a new input, `kms_key_arn`. In a flat layout you add one variable and pass it in the root. Three levels down you add a `variable` block in the leaf module, another in its parent, another in the grandparent, and an argument at each `module` call site — four files edited for one value, none of which contains any logic. The same applies in reverse: an id produced at the bottom is invisible to the root until every intermediate module re-exports it with its own `output` block. That plumbing is where bugs hide. An intermediate module usually has a `default` on the forwarded variable, so a value the root forgot to pass is silently replaced by whatever a middle layer decided months ago, and the plan looks fine. ## The graph you can no longer see Module boundaries are not evaluation boundaries. Terraform flattens the whole tree into a single dependency graph and a single state file; a module is a namespace, not a sandbox. So depth buys no isolation — it only removes information: - **Review.** A pull request that changes the root gives no clue what exists three levels down; the reviewer has to open four directories to answer "what does this create?". - **Addresses.** Plan output, errors, `-target=...` and state addresses all carry the full path, `module.a.module.b.module.c.aws_instance.web`. Anything you do by address becomes long and error-prone. - **Blast radius.** Changing a shared low-level module's interface forces a matching change in every level above it, and if those levels are separately versioned, a coordinated release train for a one-line change. ## Where nesting is still correct The rule is "shallow", not "never". One level of internal reuse inside a module is normal and healthy — a `service` module that calls a small shared `iam-role` module because every service needs the same role shape. What goes wrong is nesting used as *organisation*: splitting the root into layers because the file felt long, or building a `platform` module whose only job is to call three other modules with arguments it forwards unchanged. That layer adds a name and a version and no behaviour. ## Dependency inversion is the flat alternative The move that keeps configurations flat is to stop letting a module build its own dependencies. Instead of a `database` module that creates a VPC because it needs subnets, the module takes `subnet_ids` as an input. The root creates the network once and hands its ids to every consumer. Each module then becomes independently usable — you can point the database module at an existing VPC in a test account — and the composition, the part that differs between environments, lives in one file you can read top to bottom. ## What an interviewer is listening for A good answer names a concrete cost, not a style preference: pass-through variables at every level, outputs re-exported at every level, long addresses, and reviewers who cannot see the infrastructure from the entry point. A strong answer adds the counterweight — that one level of nesting for a genuinely shared primitive is fine, and that the fix for a long root file is usually better-scoped modules, not another layer above them.