Terraform Modules — the Contract, the Composition, and the Versioned Release

A module is a function for infrastructure. The copy-paste tax is what you pay for not writing one.

§ IFrame

Wednesday's lesson ended at the state file: the shared record that must stay honest under a team. Today climbs one level, to the code that writes to that record. And the first honest thing to say about Terraform code in the wild is that most of it is copied.

A team stands up a staging environment. It works. Production needs the same network, the same cluster, the same alarms, so someone copies the folder, edits four values, and applies. Six months later the two folders have quietly diverged in eleven places, nobody remembers which differences are deliberate, and a security fix has to be hand-carried into every copy. Call this the copy-paste tax. You do not pay it on the day you copy. You pay it on every day after.

The module is Terraform's answer, and the answer has the same shape it has in every programming language: put the repeated thing in one place, give it a name, give it parameters, and call it. A module is a function for infrastructure. This lesson names the three disciplines that make modules work under a team.

Today's trio holds together on the module. This Ops lesson takes the outside view: the module as a unit others consume. The Dev lesson goes inside the body, where HCL's for_each, dynamic blocks, and expression language let one module absorb the variation its callers throw at it. The cert lesson drills the same ground the way the Terraform Associate exam asks it, as objectives 5 and 8.

§ IIFoundations — the Module Is a Function

Strip away the ceremony and a module is any folder containing .tf files. That is the whole definition. The folder you have been running apply in all along is itself a module, called the root module. A reusable module is the same thing consumed differently: some other configuration names it in a module block, passes it values, and reads back what it exposes.

Brikman's chapter on reusable infrastructure grounds today's lesson, and its opening move is the one worth internalizing: he takes a working web-server cluster, moves the files into a folder, and the folder is now a module. Nothing was rewritten. What changed is the relationship. Code that was an environment became code that produces environments.

Hold the function analogy, because every part of it maps. Input variables are the arguments. Outputs are the return values. The resources in the body are the implementation. And the analogy carries its most useful consequence: callers should depend on the signature, never on the body. A teammate calling your network module should need to know what it asks for and what it hands back. The moment they need to read your resource blocks to use the module safely, the module has failed at its one job.

One consequence of the folder-is-a-module rule deserves its own sentence. State does not live in the module. The module is pure code; the caller's root configuration owns the state, the backend, and the blast radius that Wednesday's lesson mapped. A module consumed by ten configurations appears in ten state files, and no two of those deployments can collide through the module itself.

§ IIIMechanism — the Contract

The contract is the module's public face, and Terraform gives you exactly three surfaces to write it on.

Input variables are the signature. Each variable block declares a name, a type, optionally a default, optionally a validation rule, and optionally sensitive = true. Types are not decoration. A variable typed map(object({...})) rejects a malformed caller at plan time, which is the cheapest possible place to fail. A validation block moves a rule out of a wiki page and into the tool: minimum CIDR sizes, allowed regions, naming patterns. The signature is where a module says no early, so the apply never has to say it late.

Outputs are the return. An output block names a value the module promises to hand back: the subnet IDs it created, the DNS name of the load balancer, the ARN a downstream policy needs. Outputs are the only sanctioned way information leaves a module. Everything not exported is private by construction, free to change without breaking anyone.

The source is the address. A caller binds to a module through the source argument: a local path during development, a registry address for public modules, or a Git URL for the team's own. The address form matters less than the discipline attached to it, which is where versioning enters.

A local-path source always points at whatever is on disk right now. Fine for the module's own development repo. Dangerous everywhere else, because it means every consumer silently upgrades the moment anyone edits the module. The team that wires production to a moving target has rebuilt the copy-paste tax in reverse: instead of changes reaching consumers too slowly, every change reaches all of them instantly, tested or not.

The fix is the versioned release. Publish the module from its own repository, tag releases with semantic versions, and make every consumer pin one. Brikman's production-grade chapter states the rule this lesson carries: the version is a promise. A patch bump promises bug fixes only. A minor bump promises new capability that breaks nobody. A major bump announces the contract itself changed, and consumers must read before they move. Pinning turns "the module changed" from an event that happens to you into a change you schedule.

§ IVWorked Example — the Pin-and-Promote Release

Take the Hedronite two-environment shape from Wednesday's lesson: prod/network and staging/network, each with its own state key, both consuming one network module from the team's modules repository. The repository is tagged v0.1.0, and both environments pin it.

module "network" {
  source = "git::https://github.com/hedronite/tf-modules.git//network?ref=v0.1.0"

  env              = "staging"
  vpc_cidr         = "10.1.0.0/16"
  az_count         = 2
  enable_flow_logs = true
}

Read the address closely, because every character is doing work. The git:: prefix names the protocol. The double slash separates the repository from the path inside it, so one repository can carry many modules. The ?ref=v0.1.0 pins the Git tag, and that pin is the entire release discipline compressed into one query parameter. Below the source, the four arguments are the signature in use: this caller states its environment, its address space, its spread, and one feature flag, and it states nothing else because the contract asks for nothing else.

Now the team adds NAT-gateway support to the module and tags v0.2.0. Staging moves its ref to v0.2.0, runs plan, reads the diff, applies, and soaks for a day. Production has not moved. It is still pinned to v0.1.0, still reproducible, still deliberately behind. When staging holds, promotion is a one-line edit to production's ref and a plan whose contents have already been rehearsed. If the new tag misbehaves, rollback is the same edit run backward.

§ VThe Composition Discipline

The remaining failure mode is the module that grew too large. It starts as network, absorbs the cluster, then the database, then the alarms, until one module block provisions the company and every change to anything is a change to everything. The monolith module carries the same disease as the monolith service: one blast radius, shared by all tenants.

Brikman's composable-modules section prescribes the alternative, and it is function composition applied to infrastructure. Keep each module small, single-purpose, and honest about its contract. Then compose: the network module's output subnet IDs become the cluster module's input; the cluster module's security-group ID feeds the database module. Each seam between modules is typed, validated, and visible in the root configuration that wires them together. The root module stops being where resources live and becomes where the wiring lives, a dozen lines of module blocks and the arrows between them.

Composition also finishes the isolation story Wednesday started. State keys isolate environments from each other's records. Contracts isolate modules from each other's internals. An engineer can rework the inside of cluster from top to bottom, and so long as the signature holds, network and database cannot tell. The blast radius of a refactor shrinks to the module boundary, for the same reason the blast radius of a bad apply shrank to the state key: the seam is explicit, and explicit seams are where failures stop.

§ VIConnection to Today's Dev Lesson

This lesson kept to the outside of the module: signature, return, address, pin. The obvious objection is waiting inside. If a module is called by ten consumers with ten shapes of need, how does one body serve them all without becoming ten copies internally? That is a language question, and HCL has specific machinery for it: for_each to stamp resources from a caller's map, dynamic blocks to generate nested configuration from structure, conditionals and for expressions to reshape what the caller passed into what the providers require. Today's Dev lesson works that machinery directly. The two lessons are one claim seen from two sides. The contract is what the module promises; the expression language is how the body keeps the promise for every caller at once.

§ VIIClosing

The module is the unit of reuse, and reuse is a discipline before it is a feature. Write the contract first: typed inputs that reject bad callers at plan time, outputs that export exactly what consumers need, and nothing else visible. Keep modules small and compose them, so the wiring lives in one readable place and a refactor stops at the module boundary. Publish through tags, pin every consumer, and promote the pin environment by environment, so change arrives on a schedule you chose and rehearsed. A team holding these three disciplines has stopped paying the copy-paste tax. What it pays instead is the small, fixed cost of writing contracts, and that cost buys the thing Terraform was always for: infrastructure whose sameness is enforced by code rather than remembered by people.

Open your root configuration and count the module blocks with a local path or an unpinned source. Each one is a consumer wired to a moving target. Pin it today, or explain at the next incident why production upgraded itself.

Paired lessons → Dev Polyglot-Dev/HCL/2026-07-25-hcl-metaprogramming-... · Cert Cert-Prep/HashiCorp/2026-07-25-terraform-associate-003-modules-and-configuration-...