module-design-checklist

name	module-design-checklist
description	Pre-publish checklist and design guide for Terraform/OpenTofu modules — covers interface design, input validation, output documentation, for_each patterns, version pinning, and testability.

Module Design Checklist

When to Use This

Before publishing a new module or accepting a module PR — to verify the module meets the contract standard that allows consumers to upgrade without surprises and compose modules safely.

1. Interface Design

• Single responsibility — the module does one thing and its name states it (e.g., s3-private-bucket, not data-stuff). If the module deploys three conceptually distinct things, split it.
• Typed variables — every variable block declares a type. Avoid bare any; use object({}) for structured inputs.
• Defaults for optional inputs only — required inputs have no default (Terraform will error with a clear message); optional ones have a sensible default.
• Description on every variable and output — the description is the API contract. It must include: what the value is, expected format/units, and any constraints.

variable "retention_days" {
  type        = number
  description = "Log retention in days. Must be one of: 1, 3, 7, 14, 30, 60, 90."
  default     = 30

  validation {
    condition     = contains([1, 3, 7, 14, 30, 60, 90], var.retention_days)
    error_message = "retention_days must be one of: 1, 3, 7, 14, 30, 60, 90."
  }
}

2. Input Validation

• Validate inputs at declaration time, not at resource creation time — a validation block with a helpful error_message surfaces errors in terraform plan, not after 3 minutes of apply.
• Common validations to add:
  • CIDR blocks: can(cidrhost(var.vpc_cidr, 0))
  • Non-empty strings: length(var.name) > 0
  • Regex-constrained names: can(regex("^[a-z0-9-]+$", var.bucket_name))
  • Enum values: contains(["dev", "staging", "prod"], var.environment)

3. Resource Naming and Tagging

• Expose a name_prefix or name variable — consumers should control naming for their environment; hard-coded names break reuse.
• Accept a tags variable — always map(string), merged with any module-internal required tags:

  variable "tags" {
    type    = map(string)
    default = {}
  }
  # In resources:
  tags = merge(var.tags, { ManagedBy = "terraform", Module = "s3-private-bucket" })
  

4. For_each vs Count

• Use for_each, not count, for collections — count creates indexed resources; inserting or removing an item from the middle changes every subsequent index and Terraform recreates them. for_each keys on a stable identifier.

# Wrong
resource "aws_iam_role" "worker" {
  count = length(var.worker_names)
  name  = var.worker_names[count.index]
}

# Right
resource "aws_iam_role" "worker" {
  for_each = toset(var.worker_names)
  name     = each.key
}

5. Outputs

• Output every resource attribute a consumer could reasonably need — ARN, ID, name, DNS names.
• Never output secrets from state — if a resource produces a secret (password, key), mark the output sensitive = true and document that it appears in state in plaintext.
• Document outputs — description on every output block.

6. Version Pinning

• Pin the provider version in required_providers:

  terraform {
    required_version = ">= 1.5"
    required_providers {
      aws = {
        source  = "hashicorp/aws"
        version = "~> 5.0"
      }
    }
  }
  

• Commit .terraform.lock.hcl — ensures reproducible runs across contributors and CI.
• Version the module itself — callers pin to a version tag, not main.

7. Examples Directory

• At least one examples/ subdirectory with a complete, runnable usage of the module.
• The example must pass terraform validate — run in CI.
• The example should be the source for documentation — Terraform-docs generates README from it.

8. Testing

• terraform validate — catches syntax and provider schema errors; zero cost; run in CI.
• terraform plan against the example — catches provider API changes and broken references.
• Terratest or tftest for modules with non-trivial logic — asserts that the deployed infrastructure behaves as specified (not just that the plan looks right).

Pre-Publish Gate

# Run before opening a module PR
cd modules/<module-name>
terraform fmt -recursive -check
terraform validate
terraform-docs markdown . > README.md
cd examples/complete && terraform init && terraform validate

Pitfalls

• Publishing a module with no examples/ directory — consumers have to read the source to use it.
• Accepting any typed variables — callers get no editor assistance and errors are cryptic.
• Using count for resource sets that might have items added/removed — causes surprising resource replacement.
• Hardcoding the AWS region in a module — the consumer's provider configuration should own the region.
• Not marking sensitive outputs sensitive = true — the value is printed in plan/apply output and CI logs.

See Also

• ../../agents/terraform-module-engineer.md — composable module authoring ownership
• ../../agents/iac-architect.md — module decomposition and boundaries