terraform-modules

Terraform Modules

A module is a promise: call it with these inputs and it gives you these outputs, and you never need to read its internals to trust it. That promise only holds if the interface is deliberately designed, not just whatever variables happened to exist when the code was extracted from a working root module.

The failure mode isn't usually too few modules — it's modules built too early, from a single use case, whose interface is a guess dressed up as an abstraction.

A module's job is to hide detail behind an interface, not to hide detail behind a maze.

1. Wait for the third repetition before you extract

The first time you write a VPC config, it's a root module. The second time, resist the urge — you don't yet know which parts vary and which are load-bearing constants. By the third real call site, the variance is visible: you know what actually needs to be a parameter versus what was just an artifact of one environment's choices.

• Extracting from one example bakes in that example's assumptions as if they were general requirements.
• Extracting from three exposes the real interface — the inputs that differ are the ones that need to be variables; everything else can be a sane default or hardcoded.

Done when: the module's variable list was derived from comparing multiple real call sites, not authored speculatively for cases that don't exist yet.

2. Design the interface like a public API, not an implementation detail

Every variable and output is a contract with every future caller. A module with forty required variables and no defaults isn't flexible — it's a burden that guarantees every caller gets it slightly wrong.

variable "environment" {
  type        = string
  description = "Deployment environment: dev, staging, or prod."
  validation {
    condition     = contains(["dev", "staging", "prod"], var.environment)
    error_message = "environment must be dev, staging, or prod."
  }
}

• Give every variable a description and, where possible, a sane default — required inputs should be the genuinely essential ones, not everything the resource block happens to expose.
• Validate inputs at the module boundary rather than letting a bad value surface as a cryptic provider error three resources deep.
• Expose outputs callers actually need, not every attribute of every internal resource — a wide output surface leaks implementation and makes refactors breaking changes.