How Big Should A Terraform Root Module Be?

Hey folks,

Everyone agrees one giant Terralith state file is a dumpster fire.

But once you start breaking things up, how small is too small? How big is too big?

At a recent internal discussion at Masterpoint, we landed on a three tier system that capture how we think and reason about this problem:

Service-scoped: one primary resource per workspace. An S3 bucket. An RDS instance. An EKS cluster. Best for foundational anchor resources (such RDS, EKS, ECS, Redis, VPCs) and anything with a long lifecycle you don't want blocking other changes. Composes well, but wiring lots of them together is real work.

Domain-scoped: multiple resources that share a lifecycle, bundled together. An ECS service + its SQS queue + its IAM permissions, all in one root module. Best when your org has a strong repeated pattern ("every worker service has a queue and a bucket"). Reduces friction dramatically. But, gets awkward when resources cross domain boundaries.

Composition-scoped: this is larger configuration not intended for reuse. A self-hosted vendor tool (think vault or GH Runners). Your org's single transit gateway. Best for one-off infra that doesn't fit the reusable mold.

If you have a service-scoped S3 root module and a domain-scoped root module that also provisions an S3 bucket, they need to use the same underlying child module. Otherwise your compliance settings, naming/tagging rules, and bucket policies can drift, which you do not want. Avoid this trap.

Child modules are the brick. Root modules are walls built from those bricks. Walls share bricks. (I need a better analogy here 😅.)

A lot of "Terraform doesn't scale" criticisms are actually "we never thought about module scoping" complaints. Neither extreme works: a single Terralith hurts, but a thousand fragmented root modules hurts too.

Three tiers, with shared child modules underneath where needed, is how we can have balance.

May your root modules be just the right size,

Matt @ Masterpoint

PS If you want to chat about how we help architect IaC systems so teams can move fast, grab some time on my calendar here. You might also enjoy my talk “IaC and Agents: AI's Disruption of Infrastructure Operations” which I gave at the most recent IaCConf.