Terraform

Terraform

Overview

Opinionated conventions for safe, minimal, well-typed Terraform modules. Configuration is data; expose the smallest knob surface that supports real use cases. Bad input should fail at parse, not at plan a day later in CI.

RELATED SKILLS: General test discipline (TDD, black-box testing, naming) lives in tests and superpowers:test-driven-development. This skill only adds Terraform-specific test notes.

When to use

• Writing, modifying or reviewing any .tf / .hcl or .tftest.hcl file
• Designing a module's input or output surface

Do

• Format, lint, validate: terraform fmt -recursive, tflint in the module directory, then terraform validate. All three must pass before ship. Ignore failures in .terraform/modules/ (downloaded deps).
• Pin everything. required_version and every entry in required_providers. Commit .terraform.lock.hcl.
• Specific types on every variable. object({...}), list(string), map(...). Never any on a complex input.
• optional(T, default) for non-required object fields.
• Validate inputs aggressively. validation blocks with a concrete condition and a clear error_message.
• Reject invalid combinations at the variable level. If enable_x = true requires x_arn, enforce it with a validation.
• Hardcode in main.tf over exposing a variable. If you can't name a consumer that would set it differently, don't add the knob.
• for_each over count. Map keys survive reorders; count indexes don't.
• moved {} blocks for renames or refactors. Never destroy and recreate just to rename.
• removed {} blocks when dropping a resource you want to keep. With lifecycle { destroy = false } to only remove from state.
• import {} blocks to adopt existing infra. Reviewable in a PR, visible in plan. Imperative terraform import is neither.
• sensitive = true on variables and outputs holding secrets, tokens, ARNs, or PII.
• One module, one purpose. Outputs expose only what consumers need.
• data sources for account ID, region, partition. Never hardcode 123456789012 or us-east-1.
• Default tags on the provider (e.g. AWS default_tags) or a single tags module. Don't sprinkle tags = merge(...) across every resource.
• Concise tests that guard invariants. terraform test is verbose; use it only for what would silently break consumers (required outputs, validation rejection, key resource attributes).
• Comments explain why. A workaround, an upstream bug, a non-obvious ordering. Don't narrate what the HCL already says.
• Early returns via try() / coalesce() beat deeply nested ternaries.

Don't

• Don't expose a knob you can't safely combine. If var.a = true requires var.b = false, that's a footgun, not a feature - constrain it or remove it.
• Don't depends_on to paper over a missing reference. Reference an attribute of B from A instead.
• Don't reach for null_resource / local-exec when a provider resource exists.
• Don't manually edit state. Use moved, removed, or an import {} block. terraform state rm and terraform import (the CLI) are last resorts, not workflows.
• Don't use count = var.enabled ? 1 : 0 when for_each over a (possibly empty) set reads more clearly and survives future changes.
• Don't test trivial wiring or upstream behaviour. Test the contract your module promises.

Rationalizations: when adding a variable

Common excuses for exposing a knob you shouldn't. If you catch yourself reaching for one, hardcode the literal in main.tf instead.

Quick reference

Validation pattern

variable "cluster_name" {
  type        = string
  description = "EKS cluster name. <= 100 chars, DNS-1123 compatible."
  validation {
    condition     = length(var.cluster_name) <= 100 && can(regex("^[a-z0-9-]+$", var.cluster_name))
    error_message = "cluster_name must be <= 100 lowercase alphanumeric or hyphen characters."
  }
}

variable "logging" {
  type = object({
    enabled       = bool
    bucket_arn    = optional(string)
    retention_days = optional(number, 30)
  })
  validation {
    condition     = !var.logging.enabled || var.logging.bucket_arn != null
    error_message = "logging.bucket_arn is required when logging.enabled = true."
  }
}

The second block is the key pattern: cross-field constraints belong at the variable, not in plan-time errors.

Source: FollowTheProcess/dotfiles — distributed by TomeVault.