What belongs in a reusable Terraform module's examples/ directory, and how do you keep the input and output tables in its README accurate?

## Why a module needs examples at all A module's `variables.tf` tells a consumer what arguments exist. It does not tell them which combination actually works, which arguments are meaningful together, or what a realistic call looks like. That gap is where `examples/` lives — and unlike prose documentation, an example is code that can be checked. ## What an example directory actually is Each subdirectory under `examples/` is a complete **root module** in its own right: it declares its providers, calls the module by relative path, and supplies real values. ```hcl # examples/simple/main.tf provider "aws" { region = "eu-west-1" } module "network" { source = "../../" name = "example" cidr_block = "10.0.0.0/16" } ``` Two properties make this work. First, Terraform loads only the `.tf` files in the module directory itself and never recurses into subdirectories, so `examples/` is completely invisible to a consumer who calls your module — it adds no resources and no variables to their configuration. Second, because an example *is* a root module, all the normal commands work inside it. A good set is small and purposeful: a minimal example showing the required inputs only, and one or two showing the options that people get wrong. A directory with fifteen near-identical examples rots faster than no examples at all. ## Making examples executable in CI The reason to use examples rather than a README snippet is that they can be run. The cheap tier costs no cloud credentials at all: ```bash set -euo pipefail for dir in examples/*/; do terraform -chdir="$dir" init -backend=false terraform -chdir="$dir" validate done ``` `init -backend=false` installs providers and the local module without configuring state; `validate` then checks syntax, references, types and required arguments against the real provider schemas. If you delete a variable that an example passes, or rename an output an example reads, this fails — which is the point. Your own build breaks before a consumer's does. The expensive tier is a `plan` (or a full apply-and-destroy) against a sandbox account, which catches provider-level errors that `validate` cannot see. That belongs on a slower schedule, not on every commit. ## Generated documentation Hand-maintained input and output tables always drift; someone adds a variable and does not touch the README. The fix is to generate them from the source of truth, which means the `description` field on every declaration: ```hcl variable "cidr_block" { description = "IPv4 CIDR range for the VPC, e.g. 10.0.0.0/16" type = string } ``` `terraform-docs` reads a module directory and emits a Markdown table of inputs (name, description, type, default, required) and outputs (name, description). It can inject that table into an existing README between marker comments, so the prose you wrote stays and only the generated section is replaced. Generation alone is not enough — it has to be enforced, or someone will edit `variables.tf` and forget to regenerate. Two mechanisms, ideally both: - A **pre-commit hook** that regenerates the README on every commit touching `.tf` files. - A **CI check** that regenerates into a temporary file and fails if it differs from what is committed. This is the one that actually holds, because hooks are per-developer and easy to skip. ## What documentation is for here All of this serves the leaf idea that a module's inputs and outputs are its API. Generated tables mean the published contract is mechanically identical to the declared contract. Descriptions stop being optional politeness and become the documentation itself, which changes how they should be written — say what the value is *for* and what units or format it takes, not merely restate the name. "IPv4 CIDR range for the VPC, e.g. 10.0.0.0/16" is documentation; "The cidr block" is noise that will be published verbatim. And a README should still carry what a generator cannot produce: what the module is for, what it deliberately does not do, the prerequisites a caller must already have, and a pointer at the examples. Generation replaces the tables, not the thinking.