What a Module Is

A module is any directory of .tf files, which means you have been writing modules since your first configuration without calling them that. The directory you run terraform apply in is the root module; the moment it calls another directory with a module block, that directory becomes a child module. There is no special syntax, no marker file, nothing that declares "this is a module" — the word names a role a directory plays, not a new kind of thing.

The only real idea here is encapsulation. A child module is a black box: input variables go in, outputs come out, and the caller never reaches inside. That boundary is what lets the six interdependent resources of the Hatch ingest pipeline — a bucket, a Pub/Sub topic, a Cloud Run service, a BigQuery dataset, and a service account — become one thing you call once per event type, instead of a block of copy-paste you maintain in ten places.

Every Config Is Already a Module

Nothing in a directory marks it as a module. The root module is just the directory you run Terraform from; a child module is a directory another module references with a module block. Modules are the unit of reuse, not a new concept layered on top of resources — when you grasp that a module is a directory plus a calling convention, the rest of the chapter is mechanics.

This is why "should I make a module" is the wrong first question. The real question is whether a group of resources will be instantiated more than once, or needs a consistent contract across teams. If the answer is no, the resources can live in your root module exactly as they have all along; the module concept costs you nothing until you reach for it.

Root vs Child

The root module is the one place that owns the provider and backend blocks, and it is where state lives — there is exactly one root per working directory. A child module declares neither: it inherits the provider configuration from its caller, and it has no backend because state belongs to the root. Putting a backend block inside a child is the most common beginner error in the whole chapter, because the block is silently ignored rather than erroring.

The snippet below is a complete child module — a directory holding variables.tf, main.tf, and outputs.tf — and a root module that calls it. Notice the child has no provider and no terraform { backend }; the root supplies both, and the child borrows the google provider the root configured.

# root: main.tf — owns the provider and backend
provider "google" {
  project = "hatch-pipeline-prod"
  region  = "us-central1"
}

module "ingest_pipeline" {
  source     = "./modules/ingest-pipeline"   # a child = a directory it references
  project_id = "hatch-pipeline-prod"
  event_name = "clickstream"
}

# child: modules/ingest-pipeline/main.tf — no provider, no backend
resource "google_storage_bucket" "raw" {
  name     = "hatch-${var.event_name}-raw"
  location = "US"
}

Run terraform apply in the root and Terraform walks both directories as one graph, but the responsibilities never blur: the root decides where state lives and which credentials to use, the child only describes resources.

Encapsulation Is the Whole Point

The caller sees only the child's input variables and its outputs. The resources, locals, and data sources inside are private — invisible across the boundary. That is what makes a module worth the indirection: the ingest-pipeline module can rearrange its internals, swap a google_storage_bucket for a different layout, or add an internal data source, and no caller changes a line as long as the inputs and outputs hold.

Encapsulation also means you cannot reach in. Referencing module.ingest_pipeline.google_storage_bucket.raw.url fails — the resource address is private to the child. You can read only what the child explicitly declares as an output. That restriction feels limiting until you realize it is exactly what keeps the boundary a real contract instead of a suggestion.

Why Modules Exist: The Second Pipeline

The Hatch ingest pipeline is six resources wired together: the raw bucket, the Pub/Sub topic events land on, the Cloud Run service that processes them, the BigQuery dataset they load into, and the service account that ties the identity together. As one pipeline in your root module, that is fine. The moment you want a second pipeline for a second event type, you face a fork: copy those six resources and maintain two divergent copies, or make them a module and instantiate it twice with different inputs.

A module turns that fork into one line of difference. event_name = "clickstream" for the first, event_name = "transactions" for the second, and a fix to the pipeline shape is made once. The copy-paste path means a fix has to be applied in every copy, and one will inevitably be missed — that drift is the exact problem the module concept exists to kill.

The Module Tree

terraform apply walks a tree rooted at your working directory, and that tree shows up in state addresses and plan output. A resource inside the child reads as module.ingest_pipeline.google_storage_bucket.raw — the module.<name> prefix tells you which module produced it. Reading those addresses as a tree is how you trace a plan line back to the directory that owns it, which becomes essential once modules call modules.