Composition and Nested Modules

Modules call modules, and composition is how you build something real. The Hatch root module calls the ingest-pipeline module, which could itself call the CFT cloud-storage module for its raw bucket. Assembling a large system from small, single-purpose pieces is the whole point of the module concept — but composition has two failure modes, and both are worth naming before you write a nested module.

The first is passing providers to a child incorrectly. The second is nesting too deep: a module tree more than two or three levels down becomes impossible to reason about, and you find yourself debugging through layers of indirection instead of looking at resources. This topic covers both, and the rule that keeps you out of trouble is to compose flatly and pass providers only when inheritance genuinely cannot express what you need.

Modules Calling Modules

A child module can contain its own module blocks, so the ingest-pipeline module could compose the CFT cloud-storage module for its raw bucket instead of declaring a google_storage_bucket directly. That is composition: the pipeline module assembles smaller reviewed pieces, and the root module assembles pipeline modules. Each layer wires the outputs of one piece into the inputs of the next, building up from primitives to a whole system.

Implicit Provider Inheritance

By default a child inherits the caller's default provider configurations, so most modules need no provider plumbing at all. The root configures the google provider once, and every child below it uses that configuration automatically. This is the common case and the simple one: you write a module block, pass the input variables, and the provider is handled for you without a single line about it.

Passing Providers Explicitly

When a child needs a non-default provider — a second region, a different project, or google-beta for a resource only the beta provider exposes — you pass it explicitly with a providers argument in the module block. The child declares it expects to receive one through configuration_aliases, and a reusable child must receive providers this way, never declare its own provider block. The snippet below passes google-beta into a child that needs it.

# root: configure both the default and a beta provider
provider "google-beta" {
  project = "hatch-pipeline-prod"
}

module "ingest_pipeline" {
  source = "./modules/ingest-pipeline"
  providers = {
    google-beta = google-beta   # hand the beta provider to the child
  }
  event_name = "clickstream"
}

# child: declare it RECEIVES a provider — never declare a provider block
terraform {
  required_providers {
    google-beta = {
      source                = "hashicorp/google-beta"
      configuration_aliases = [google-beta]
    }
  }
}

A reusable child that declares its own provider block cannot be instantiated twice and breaks for_each over the module, because the provider configuration gets tangled with the instance. Receiving providers through configuration_aliases keeps the child reusable; declaring them inside it does not.

Keeping the Tree Shallow

The healthy shape is flat composition: wire the outputs of one module into the inputs of the next, side by side under the root. The ingest-pipeline module's topic_id output flows into a bigquery-loader module's input, and a reader can follow that in one hop. The anti-pattern is burying modules four levels deep so a single input threads through three intermediaries that do nothing but pass it along — every one of those layers is a place to get lost and nothing to gain.

Keeping data flow one-directional matters as much as keeping it shallow. Wire module A's output into module B's input, never B's output back into A's — that back-and-forth is how a dependency cycle appears at apply time, when Terraform cannot decide which module to build first. Pass the specific values each module needs rather than handing whole undifferentiated objects around, and the flow stays acyclic and legible.

Reading a Composed Plan

Addresses nest to match the tree: a bucket two modules deep reads as module.ingest_pipeline.module.bucket.google_storage_bucket.raw. That nesting is your smell test. When a plan line is so deeply prefixed that you can no longer trace it back to a resource at a glance, the tree is too deep — the address is telling you the composition has more layers than the system actually has structure. A plan you can read is a tree you have kept shallow.