/infra-iac-terraform

name: infra-iac-terraform
description: Infrastructure as Code with HashiCorp Terraform

Terraform Patterns

> **Quick Guide:** Declarative infrastructure using HCL. Pin provider versions in `required_providers` and commit `.terraform.lock.hcl`. Use remote backends with state locking for team collaboration. Prefer `for_each` over `count` for non-identical resources. Use `moved` blocks for refactoring, `import` blocks for adopting existing infrastructure. Validate inputs with `validation` blocks and infrastructure with `precondition`/`postcondition`. Keep modules flat, composable, and single-purpose. Run `terraform fmt` and `terraform validate` before every commit.

---

<critical_requirements>

CRITICAL: Before Using This Skill

> **All code must follow project conventions in CLAUDE.md**

**(You MUST pin provider versions with constraints in `required_providers` and commit `.terraform.lock.hcl` to version control)**

**(You MUST use a remote backend with state locking for any shared or production infrastructure)**

**(You MUST use `for_each` with a map/set for non-identical resources -- `count` causes index-shift destruction on removal)**

**(You MUST never store secrets in `.tf` files, `.tfvars`, or state -- use environment variables (`TF_VAR_*`) or your secrets manager)**

**(You MUST run `terraform plan` and review the diff before every `terraform apply` -- never apply blindly)**

</critical_requirements>

---

**Detailed Resources:**

• [examples/core.md](examples/core.md) - Resource definitions, variables, outputs, locals, data sources, provider configuration
• [examples/modules.md](examples/modules.md) - Module structure, composition, versioning, registry publishing
• [examples/state.md](examples/state.md) - Remote backends, state locking, moved/import/removed blocks, workspaces
• [examples/patterns.md](examples/patterns.md) - for_each, dynamic blocks, lifecycle, conditions, validations
• [reference.md](reference.md) - Decision frameworks, CLI cheat sheet, file naming conventions

---

**Auto-detection:** Terraform, OpenTofu, HCL, .tf files, terraform init, terraform plan, terraform apply, terraform fmt, terraform validate, required_providers, terraform block, resource block, data source, module block, variable block, output block, locals, backend configuration, remote state, state locking, moved block, import block, for_each, count, dynamic block, lifecycle, precondition, postcondition, .terraform.lock.hcl, tfvars, provider configuration

**When to use:**

• Writing or reviewing Terraform/OpenTofu configuration files (`.tf`)
• Defining cloud resources, data sources, modules, variables, and outputs
• Managing state backends, locking, and multi-environment deployments
• Refactoring infrastructure with `moved`, `import`, and `removed` blocks
• Structuring reusable modules for team or registry consumption

**When NOT to use:**

• Application code deployment logic (that belongs in CI/CD pipelines)
• Container orchestration configuration (Kubernetes manifests, Helm charts)
• One-off scripting tasks better handled by shell scripts or CLI tools

**Key patterns covered:**

• Provider pinning, lock files, and version constraints
• Resource definitions with meta-arguments (`for_each`, `count`, `depends_on`, `lifecycle`)
• Variable validation, locals for derived values, output descriptions
• Remote backend configuration with state locking
• Module structure (flat composition, single-purpose modules)
• Refactoring with `moved`, `import`, and `removed` blocks
• Custom conditions (`precondition`, `postcondition`, `check` blocks)
• Dynamic blocks for repeated nested configuration
• Environment management (directory-based vs workspaces)

---

<philosophy>

Philosophy

Terraform is a declarative infrastructure-as-code tool. You describe the desired end-state; Terraform determines the steps to reach it. The HCL configuration language is designed to be human-readable and machine-parseable.

**Core principles:**

• **Declarative, not imperative** -- describe what you want, not how to get there
• **State is the source of truth** -- Terraform tracks what it manages via state; protect it accordingly
• **Modules are the unit of reuse** -- keep them flat, composable, and single-purpose
• **Pin everything** -- provider versions, Terraform version, module versions; reproducibility is non-negotiable
• **Plan before apply** -- always review the diff; never apply blindly in production

**OpenTofu compatibility:** OpenTofu is an open-source fork (MPL 2.0) that is syntax-compatible with Terraform 1.5.x. The patterns in this skill apply to both tools. OpenTofu uses `.tofu` file extensions for OpenTofu-only features and adds native state encryption.

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Provider and Version Pinning

Pin Terraform version and all provider versions. Commit `.terraform.lock.hcl` to version control.

# terraform.tf
terraform {
  required_version = ">= 1.9.0, < 2.0.0"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"  # Allows 5.x, blocks 6.0
    }
  }
}

**Why this matters:** Without version constraints, `terraform init` on different machines downloads different provider versions, causing inconsistent plans and mysterious drift. The lock file pins exact versions and cryptographic hashes.

**Version constraint syntax:** `= 1.0.0` (exact), `>= 1.0.0` (minimum), `~> 1.0` (allows 1.x, blocks 2.0), `>= 1.0, < 2.0` (range).

See [examples/core.md](examples/core.md) for full provider configuration with aliases and default tags.

---

Pattern 2: Resource Definitions and Meta-Arguments

Resources follow a standard argument ordering: meta-arguments first, resource arguments next, nested blocks after, lifecycle last.

resource "aws_instance" "web" {
  count = var.instance_count  # Meta-argument first

  ami           = data.aws_ami.ubuntu.id
  instance_type = var.instance_type

  tags = {
    Name = "web-${