terraform-module-author

Terraform Module Author

Overview

This skill encodes the conventions for writing reusable Terraform modules that are safe to share, version, and consume across teams. It covers file layout, typed variables with validation, outputs, provider/version pinning, state hygiene, and documentation.

Keywords: terraform, opentofu, hcl, module, variables, outputs, validation, terraform.tfvars, versions.tf, provider pinning, remote state, registry, tflint, terraform fmt, terraform validate, infrastructure as code, IaC, DevOps.

A "module" here is any directory of .tf files meant to be called by another configuration via a module "x" { source = ... } block. The same rules apply to the root module — the only difference is the root configures providers and backends, while reusable child modules must NOT.

Workflow

1. Clarify the boundary. Decide what the module owns. A good module manages one logical unit (a VPC, an S3 bucket with policy, a Kubernetes namespace). If you cannot name it in one phrase, split it. List required inputs, optional inputs, and what callers need back as outputs.
2. Lay out the standard files. Create main.tf, variables.tf, outputs.tf, versions.tf, and README.md. Keep resource logic in main.tf (or split by concern, e.g. iam.tf, network.tf). Never put variables or outputs inline in main.tf. See references/module-conventions.md.
3. Pin versions in versions.tf. Set required_version for Terraform/OpenTofu and required_providers with a source and a ~> pessimistic constraint. Reusable child modules declare required_providers but do NOT include provider blocks or backend config — those belong only to the root.
4. Write typed variables with validation. Every variable gets an explicit type, a description, and a default only when truly optional. Add validation blocks for enums, ranges, regex, and naming rules. Mark secrets sensitive = true. See references/variables-and-validation.md.
5. Expose minimal, stable outputs. Output the IDs/ARNs/endpoints callers need to wire things together. Every output has a description. Mark sensitive outputs sensitive = true. Avoid leaking the entire resource object unless intentional.
6. Guard state hygiene. Use for_each over count for named, stable resources. Never hardcode backends inside reusable modules. Document any moved {} blocks when renaming resources to avoid destroy/recreate. See references/state-hygiene.md.
7. Validate and lint. Run terraform fmt -recursive, terraform validate, and tflint. Use the bundled scripts/validate_module.sh to run the full gate in one command.
8. Document. Fill in README.md from templates/README.md.tmpl — purpose, usage example, and an inputs/outputs table. If terraform-docs is available, generate the tables automatically.