Writing reusable Terraform modules that don't fight you

Design modules with clear inputs and outputs, sane defaults, and versioning so teams reuse them without forking.

A good Terraform module is a small contract: clear inputs, useful outputs, sane defaults, and a version. A bad one leaks its internals and forces every caller to fork it. The difference is mostly discipline at the interface.

The shape of a module

modules/bucket/
  variables.tf   # the inputs (the contract)
  main.tf        # the resources
  outputs.tf     # what callers can use
  README.md      # examples + the contract in prose

Validate the inputs

Defaults make the common case one line; validation turns a misconfiguration into a plan-time error instead of a 2am incident.

variable "name" {
  type = string
  validation {
    condition     = can(regex("^[a-z0-9-]+$", var.name))
    error_message = "name must be lowercase alphanumeric or dashes."
  }
}
variable "versioning" {
  type    = bool
  default = true
}

Call it with a pinned version

module "logs" {
  source  = "app.terraform.io/acme/bucket/aws"
  version = "~> 2.1"
  name    = "acme-app-logs"
}

Related posts