Designing Reusable Modules

A reusable module is a product with users, and designing one well means thinking past your first use case: a clear minimal interface, sensible defaults, sound validation, useful outputs, documentation, and a versioning discipline. This page pulls the chapter together into the principles that separate a module others adopt happily from one they fork in frustration.

The test of a module is the second consumer. Anything works for the caller who wrote it; a module is reusable only when a different team, with a slightly different need, can adopt it without reading the source or forking a copy. Every principle here is aimed at that second consumer.

Interface Design

Design the interface around minimal required inputs, optional inputs with defaults for everything else, precise types, and validation. The required set is what the module genuinely cannot guess — a name, the subnets it lives in. Everything with a safe default becomes optional, so the common call is short. Precise types and validation blocks turn misuse into a clear plan-time error at the call site instead of a failure deep in the apply.

variable "instance_count" {
  type        = number
  description = "Number of instances, 1 to 10."
  default     = 2

  validation {
    condition     = var.instance_count >= 1 && var.instance_count <= 10
    error_message = "instance_count must be between 1 and 10."
  }
}

Sensible Defaults and Escape Hatches

Make the common case trivial and the advanced case possible. A good default — a db.t3.micro class, a 7-day backup retention, encryption on — means most callers write three lines and get a sound result. The escape hatch is the optional input that lets the rare caller override that default when they have a real reason. Defaults carry the eighty percent; escape hatches keep the other twenty from forking the module.

Documentation and Examples

A module nobody can use without reading its source is not reusable. Ship a README with input and output tables — generated by terraform-docs so they never drift from the code — and a runnable examples/ directory that shows the module called for real. The example is the fastest way for a new adopter to learn the interface, and it doubles as something you can actually plan and apply to prove the module works.

module "db" {
  source     = "../../"
  identifier = "orders"
  subnet_ids = ["subnet-0a1b", "subnet-0c2d"]
  # every other input uses the module's defaults
}

Versioning and Changelogs

Follow semantic versioning strictly so consumers can pin and upgrade with confidence. A breaking interface change — a removed input, a renamed output — is a major bump; a new optional input is a minor; a fix is a patch. Keep a changelog so an adopter raising a constraint knows what they are getting. This discipline is what makes a consumer's ~> 6.0 pin actually safe: it only holds if you never sneak a break into a minor release.

Testing Modules

A module others depend on deserves tests, so a refactor that breaks the interface fails in CI rather than in a consumer's production. Terraform's built-in terraform test framework and contract testing — asserting the module still produces the outputs its consumers rely on — are how you keep the interface stable across changes. Both are covered in depth in the testing chapter; the point here is that a reusable module's interface is a promise worth verifying.