Terraform

User preferences and memory live in ~/Clawic/data/terraform/ (see setup.md on first use, memory-template.md for the file format). If you have data at an old location (~/terraform/ or ~/clawic/terraform/), move it to ~/Clawic/data/terraform/.

When To Use

• Writing or reviewing HCL: resource design, count vs for_each, module boundaries, variable types and validation
• Debugging plan/apply failures, permanent diffs, cycles, unknown-at-plan errors, stuck locks, drift
• Refactoring live infrastructure: renames, module extraction, imports, splitting or merging state
• Pinning providers, upgrading the CLI or a provider major version, moving between Terraform and OpenTofu
• Designing backends, environment layout, and CI plan/apply gates with policy, tests, and drift detection
• Recovering after damage: lost or corrupted state, wrong state rm, unintended destroy, interrupted apply
• Not for choosing which cloud resources to build (→ aws, gcp, azure) or configuring what runs inside them (→ ansible)

Quick Reference

Depth on demand: debug.md plan/apply symptom→cause chains · state.md backends, locking, layout · refactoring.md moved/import/removed · modules.md design and versioning · expressions.md HCL loops, types, functions · lifecycle.md replacement, protection, ignored drift · providers.md pinning, lock file, aliases · secrets.md sensitive values and state exposure · ci.md pipelines, OIDC, drift detection · testing.md validate, terraform test, policy · upgrades.md CLI and provider majors, OpenTofu · performance.md slow plans and big states · recovery.md after the damage · commands.md incident toolkit.

Core Rules

1. The saved plan is the contract. terraform plan -out=tfplan → review → terraform apply tfplan. A bare apply re-plans against a world that may have changed since you read the diff: you approve one change and execute another.
2. Back up before state surgery. terraform state pull > backup-$(date +%s).tfstate; restore with terraform state push. One wrong state rm orphans a live resource that keeps running and billing with nothing tracking it.
3. Read the destroy count from the resource lines, not the summary. A replacement is counted once as an add and once as a destroy, so 2 to add, 0 to change, 2 to destroy can be two replacements rather than two creations plus two deletions. Machine gate: terraform show -json tfplan | jq '[.resource_changes[] | select(.change.actions | index("delete"))] | length' — compare against destroy_gate.
4. Pin everything. Providers via required_providers plus a committed .terraform.lock.hcl; third-party modules to an exact version; git module sources to a tag, never a branch. Unpinned means CI breaks on someone else's release day.
5. Key for_each on stable, human-chosen strings (environment names, logical roles) — never IDs, list indices, or computed values. Changing a key is destroy + create of the real object; count indices renumber, so removing item 0 shifts everything after it.
6. Refactor declaratively. moved, import, and removed blocks put the change in the PR diff and replay in every environment. state mv/state rm are out-of-band: unreviewable, unreplayable, invisible to the next reader.
7. Nothing sensitive is safe in state. sensitive = true masks CLI output; the value sits in plaintext in the state file, the saved plan, and TF_LOG output. Encrypt the backend, restrict who can read state, and prefer ephemeral values (>=1.10) and write-only arguments (>=1.11).
8. Drift is a question, not an error. When the cloud changed under you, decide explicitly: apply -refresh-only accepts reality into state, a normal apply overwrites reality with the code. Applying without choosing is how a console hotfix gets silently reverted at 2am.

Plan Triage

Read the symbols before the summary:

• terraform show tfplan re-renders a saved plan; terraform show -json tfplan is the machine-readable form every gate should read (ci.md).
• plan -detailed-exitcode exit codes: 0 no changes · 1 error · 2 changes present.
• "No changes" plus a real-world difference you can see means the attribute is not managed (missing from config, or hidden by ignore_changes).

Count vs for_each

• count is positional. Reserve it for identical replicas and the enable flag: count = var.enabled ? 1 : 0, referenced as one(aws_x.y[*].id).
• for_each is keyed and stable, but needs a map or a set of strings (toset() for lists) whose keys are known at plan time. Values may be unknown; keys may not. Keys built from resource attributes fail with "Invalid for_each argument" (expressions.md).
• Migrating count to for_each without one moved block per index destroys and recreates every instance. Get the index→key mapping from terraform state list, not from memory (worked example in refactoring.md).
• Sensitive values cannot be for_each keys — a map that merges in one sensitive input becomes sensitive as a whole and the plan rejects it.

Version Floors

required_version in the root module turns "my colleague gets a parse error" into a clear message. Floors for the syntax this skill recommends:

OpenTofu forked at the 1.6 line: floors above 1.6 do not transfer — check tofu version against its own changelog before using a newer block (upgrades.md).

Output Gates

Before emitting HCL or proposing an apply:

• Plan saved to a file, and the thing applied is that file?
• Destroy count read from the resource lines, with every "forces replacement" attribute named out loud?
• Every for_each keyed on a plan-time-known string?
• Providers pinned and .terraform.lock.hcl covering every platform in lock_platforms?
• New variables typed, with validation wherever a wrong value is expensive?
• No secret in a committed .tfvars, a variable default, or an unmasked output?
• If this is a refactor: does the plan read 0 to add, 0 to change, 0 to destroy?

Configuration

User-dependent variables. Defaults apply until the user states a preference; store them in ~/Clawic/data/terraform/config.yaml.

Preference areas — customizable dimensions; a stated preference gets recorded in config.yaml and applied:

• Tooling: wrappers (Terragrunt, Terramate), pre-commit hooks, plan-summary tooling — affects which pipeline shape gets proposed
• Conventions: resource and module naming, tagging standard, file split (main/variables/outputs vs per-domain) — affects every generated block
• Platform: clouds, regions, and accounts in play, and the cross-account role-assumption pattern — affects provider aliases and backend keys
• Safety posture: appetite for state surgery vs declarative blocks, whether -auto-approve is ever acceptable — affects which refactoring path is offered first
• Workflow: where apply happens (laptop, CI, managed platform), review gates, who holds production credentials — affects the CI examples
• Compliance: mandatory policy engine, required tags, encryption and public-access rules — affects the testing and gate recommendations
• Output format: plan-summary verbosity beyond plan_summary_detail, HCL-vs-explanation ratio in answers, proactive warnings versus on-demand — affects how every plan and review is reported
• Cadence: drift-detection schedule and provider-upgrade rhythm — affects what gets scheduled versus run on demand

Traps

Where Experts Disagree

• Vanilla Terraform vs wrapper tooling (Terragrunt and friends): the frontier is duplication — one team with a handful of stacks loses more to wrapper complexity than it saves; once environments × stacks means maintaining dozens of near-identical backend and provider blocks, DRY tooling earns its cost.
• Exact module pins vs ~> constraints: exact pins for third-party registry modules (supply-chain surface); pessimistic minor constraints acceptable for internal modules gated by your own CI.
• One shared state vs many micro-states: the frontier is change coupling — resources that always ship together belong in one state; every cross-state reference costs a data-source hop and an ordering problem between pipelines.
• Terraform vs OpenTofu: the frontier is licensing exposure and feature need, not ideology — OpenTofu is a drop-in for most existing code and adds state encryption; teams already on a managed HashiCorp platform, or depending on features that landed after the fork, pay a migration cost for nothing. Decide once, per organization (upgrades.md).

Related Skills

More Clawic skills, get them at https://clawic.com/skills/terraform (install if the user confirms):

• aws — provider-specific resource and service guidance
• devops — pipeline and delivery design around plan/apply gates
• github-actions — wiring plan-on-PR / apply-on-merge workflows
• ansible — configuring what lives inside the instances Terraform creates
• k8s — workloads on the clusters Terraform provisions

Feedback

• If useful, star it: https://clawic.com/skills/terraform
• Latest version: https://clawic.com/skills/terraform

Part of Clawic, the verified skill library. Get this skill: https://clawic.com/skills/terraform.