terraform-module-design

license	Apache-2.0
allowed-tools	Read,Write,Edit,Bash,Glob,Grep,WebSearch,WebFetch
name	terraform-module-design
description	Use when designing Terraform modules for reuse, structuring root vs child modules, choosing variable shapes (object vs flat list), wiring versioning + module registries, managing remote state, detecting and remediating drift, or refactoring monolithic configs. Triggers: module composition, var validation blocks, output contracts, count vs for_each, lifecycle ignore_changes, terraform import, state mv between resources, workspaces vs separate state files, OIDC to provider, drift detection runs. NOT for Pulumi/CDK (different paradigms), CloudFormation, ad-hoc one-off deployments, or Terraform Cloud-specific UX.
metadata	{"category":"DevOps & Infrastructure","tags":["terraform","iac","modules","state","hashicorp","cloud"],"provenance":{"kind":"first-party","owners":["port-daddy"]},"pairs-with":[{"skill":"monitoring-stack-deployer","reason":"Once modules provision the infrastructure, that skill wires the observability stack watching it -- often as a caller of the modules designed here."},{"skill":"agentic-infrastructure-2026","reason":"The broader infra-architecture context (what to provision and why) that this skill's module boundaries and state-splitting decisions serve."}],"io-contract":{"kind":"deliverable","consumes":["[Truncated]","[Truncated]"],"produces":["[Truncated]","[Truncated]"]}}

Terraform Module Design

A good Terraform module is a black box: clear inputs, stable outputs, locked-down dependencies. The shift from "configuration files" to "module library" is what separates a working repo from a maintainable one.

Jump to your fire:

• Plan output changes mysteriously between runs → Versioning + registry
• Removing one item from a list recreates everything after it → count vs for_each
• Every plan shows a phantom diff → lifecycle blocks
• Refactor turned into destroy + create → Refactoring without recreate
• Apply mid-plan caused incident → Plan-apply-pray (anti-pattern)
• Small change requires apply on the whole world → State management
• Long-lived cloud creds in CI → OIDC to cloud providers

When to use

• Reusable infrastructure across environments (dev/staging/prod) or services.
• A monolithic Terraform config that's becoming unmanageable.
• Sharing modules across teams via a registry (Terraform Registry, private registry, git).
• Detecting drift before it causes incidents.
• Refactoring resource ownership (one resource → multiple modules) without recreating cloud resources.

Core capabilities

Module structure

modules/
└── service/
    ├── main.tf              # resources
    ├── variables.tf         # inputs
    ├── outputs.tf           # outputs
    ├── versions.tf          # required_providers + required_version
    └── README.md            # purpose, inputs, outputs, examples

# modules/service/variables.tf
variable "name" {
  type        = string
  description = "Service name. Used in resource names; lowercase + dashes."
  validation {
    condition     = can(regex("^[a-z][a-z0-9-]{2,30}$", var.name))
    error_message = "name must be 3-31 chars, start with a letter, lowercase + dashes."
  }
}

variable "scaling" {
  type = object({
    min  = number
    max  = number
    cpu  = number
  })
  default = { min = 1, max = 10, cpu = 50 }
}

variable "tags" {
  type    = map(string)
  default = {}
}

Validation blocks turn unclear runtime errors into clear plan-time errors. Use them on every variable that has constraints.

Outputs as the contract

# modules/service/outputs.tf
output "service_url" {
  value       = aws_ecs_service.this.url
  description = "HTTPS URL of the deployed service."
}

output "log_group" {
  value       = aws_cloudwatch_log_group.this.name
  description = "Log group name for downstream alerts."
}

output "_resources" {
  value       = { service_arn = aws_ecs_service.this.arn, role_arn = aws_iam_role.this.arn }
  description = "Internal resource references for sibling modules."
  sensitive   = false
}