How deep should a Terraform module tree nest, and what does each additional layer cost you?

## There is no limit, which is the problem Terraform will happily let a module call a module that calls a module. Nothing stops you, and the language gives you no feedback as the tree deepens — the cost arrives later, in the plumbing and in the day you need to move a resource. So depth is a design decision made entirely on judgment. The shape most mature estates converge on is flat: a root module (typically one per environment or per service) that calls a handful of reusable child modules directly, with an intermediate layer used sparingly, for a stack that is genuinely reused as a unit. ## Cost one: pass-through plumbing This is the cost that shows up weekly. Because encapsulation applies at every level, a value cannot skip a layer. To let a root set one new option on a resource three levels down, you must add: - a `variable` in the top module and pass it in the `module` block, - a `variable` in the middle module and pass it in *its* `module` block, - a `variable` in the leaf module where it is finally used. And if the caller needs a value back out, an `output` at each level going the other way. One option, six declarations, three files opened, three pull requests if the modules live in separate repositories. Teams respond by pre-plumbing every conceivable variable through every layer "just in case", which produces modules with sixty inputs, most of them unused, and no way to tell which ones matter. ## Cost two: addresses get long Every resource's address carries its full module path: ``` module.platform.module.network.module.subnets.aws_subnet.this["eu-west-1a"] ``` That address is not cosmetic. It is what you type for `terraform state mv`, `-target`, `-replace=`, and `terraform state show`; it is what appears in every line of a plan; and it is the thing that changes — invalidating state — when you insert or remove a layer. A refactor that moves a resource between layers requires a `moved` block or a state move for every instance affected. ```bash terraform state mv \ 'module.platform.module.network.module.subnets.aws_subnet.this["eu-west-1a"]' \ 'module.network.aws_subnet.this["eu-west-1a"]' ``` ## Cost three: distance between the reviewer and the change Infrastructure code is read in pull requests by people deciding whether a change is safe to apply to production. Each layer of nesting is one more file to open before the actual `resource` block appears. At depth three, understanding what a one-line root change does means holding three modules in your head — and the plan output, which would otherwise ground you, is now a wall of long addresses. ## Cost four: version coupling When an intermediate module pins the versions of the modules it calls, consumers cannot upgrade a leaf module independently — they wait for the intermediate to be released. A security fix in a leaf module now requires a coordinated release at every layer above it. This is the same problem transitive dependency pinning causes in application package management, and it bites for the same reasons. ## What depth actually buys A layer is worth adding when a *combination* of modules is genuinely reused, identically, in several places, and you want one place to change it. A "standard service" module that wires a load balancer, a task definition, a log group and alarms into the shape your organisation always uses is a legitimate intermediate layer: it encodes a real decision, and updating it updates everyone. The failure mode is a layer that wraps a single child module and passes fifteen variables straight through. That adds every cost above and encapsulates nothing. If a module's `main.tf` is one `module` block, delete the layer. ## The judgment, and how to defend it The tradeoff is centralisation against comprehensibility. A flat estate means the same three module calls appear in twenty roots, and changing the pattern is twenty pull requests — but each root is readable on its own and each team upgrades on its own schedule. A deep estate means one change propagates everywhere — and a rigid interface, coordinated releases, and code no individual team fully understands. Which you want depends on how many roots exist and how autonomous the teams are. A single platform team running six environments benefits from depth. Forty product teams sharing a module library do not: for them, flat modules with clear interfaces plus a code generator or a documented example is usually the better trade, because it centralises the *pattern* without centralising the *release*. The practical rules that survive contact: - Default to flat. Add a layer only for repetition you have already seen at least three times. - No wrapper layers that only forward arguments. - If exposing a new option touches more than two modules, the tree is too deep. - Nesting depth is not the way to organise state boundaries — state splitting is a separate axis and deserves its own decision.