terraform

Terraform and OpenTofu

Write and review reproducible infrastructure with narrow state boundaries, protected credentials, reviewable plans, and explicit human approval for every apply. Use the installed runtime and pinned provider schema as the authority for resource arguments and behavior.

Version-specific behavior: inspect the existing lock file and provider documentation before changing pins or relying on a runtime feature.

When to use

• Writing or reviewing Terraform/OpenTofu configurations, modules, providers, state, or imports
• Designing backend, locking, state-boundary, OIDC, policy-as-code, or drift-detection decisions
• Implementing infrastructure controls for regulated or PCI-scoped systems
• Reviewing generated HCL for security, correctness, replacement, and state impact

When NOT to use

• Kubernetes manifests or Helm charts; use kubernetes
• Read-only Kubernetes health checks; use kubernetes-health
• VM guest configuration; use ansible or virtualization
• CI/CD pipeline architecture; use ci-cd
• Database schema, indexing, replication, or engine operations; use databases
• Application security auditing; use security-audit
• Proxmox VM/LXC provisioning specifics (bpg/proxmox provider, templates, cloud-init); use virtualization - this skill owns general HCL/module/state work

AI Self-Check

• Provider versions and resource arguments match the installed lock file and current provider docs
• Regions, account IDs, CIDRs, AMIs, and credentials are variables or discovered values, not literals
• IAM is least privilege; broad actions/resources and public ingress are explicit, justified exceptions
• Storage has encryption, access controls, versioning, logging, and a deliberate public-access posture
• Backend encryption, locking, state access, and sensitive value exposure are reviewed
• Stateful resources have deliberate lifecycle, backup, migration, and replacement behavior
• Provider/module/action versions are pinned; .terraform.lock.hcl is committed
• Secret values avoid ordinary state when supported and have a documented runtime delivery path
• Imports, moves, replacements, and destroys are visible in the reviewed plan
• No provisioners or committed real-value tfvars appear; tags/ownership are present where supported
• terraform fmt and terraform validate pass; scans and policy gates match the repository's policy
• Cross-cutting agent hygiene applied; read references/agent-hygiene.md when relevant

Secret lifecycle

Trace each credential from issuer to CI identity, provider use, state, and workload. Record who rotates and revokes it, lease duration, and the application reload path. Treat sensitive as display redaction, not protection from state persistence. Verify rotation and revocation in an approved test environment without printing values; pass runtime delivery ownership to kubernetes and pipeline identity ownership to ci-cd.

Workflow

Copy this checklist and track progress:

• Step 1: Scope determined (account, backend, state boundary, secrets)
• Step 2: Relevant references read (state-and-security before any state command)
• Step 3: fmt, validate, tflint, checkov clean for introduced findings (on failure, fix and return to Step 3)
• Plan reviewed with the owner; no apply by the agent

1. Determine the scope

Identify the provider/account boundary, environment, resource dependencies, backend and lock design, existing modules, compliance scope, and secret delivery path. For an existing system, inspect the current HCL, .terraform.lock.hcl, backend, workspace/state boundary, and prior plan conventions before introducing a new pattern.

2. Route to the narrow implementation guidance

• Read references/implementation-patterns.md for Terraform-versus-OpenTofu choice, HCL structure, lifecycle/ephemeral values, imports/moves, S3 review, module shape, account boundaries, and scans.
• Read references/state-and-security.md for backend configuration, encryption, locking, OIDC, or state surgery. Read it before any state-changing command.
• Read references/module-patterns.md for module API/testing or registry choices.
• Read references/compliance.md for PCI controls, drift detection, audit evidence, and regulated architecture. Read references/production-checklist.md before a production delivery.

3. Build and validate without applying

Run the relevant checks in order from the affected stack (use tofu for an OpenTofu stack). If fmt or validate fails, or tflint/checkov reports a finding the change introduced, fix it and rerun from fmt; plan only after validate passes. Report pre-existing tflint/checkov findings instead of blocking plan on them. A passing syntax check is not a safe infrastructure change: inspect planned creates, changes, replacements, imports, and destroys with the owner.

terraform fmt -check -recursive
terraform validate
if command -v tflint >/dev/null; then tflint --recursive; else echo "tflint not installed: lint NOT run; report it as unverified"; fi
if command -v checkov >/dev/null; then checkov -d . --framework terraform; else echo "checkov not installed: policy scan NOT run; report it as unverified"; fi
terraform plan -out=plan.tfplan
if command -v conftest >/dev/null; then terraform show -json plan.tfplan | conftest test -; else echo "conftest not installed: policy gate NOT run; report it as unverified"; fi

Report checks that ran, their results, and any unavailable tool. plan, state operations, and a policy gate provide different evidence. Do not run terraform apply, tofu apply, destroy, state removal, force-unlock, or a live migration without explicit authorization and a reviewed exact scope.

Output Contract

See references/output-contract.md for the full contract.

• Skill name: TERRAFORM
• Deliverable bucket: audits
• Mode: conditional. For analysis, review, audit, or improvement of existing content, apply the local reporting rules and write docs/local/audits/terraform/<YYYY-MM-DD>-<slug>.md. Building or explaining infrastructure remains conversational.
• Severity scale: P0 | P1 | P2 | P3 | info

Related Skills

• ansible - configuration after provisioning
• kubernetes / kubernetes-health - cluster configuration and read-only cluster diagnostics
• databases - database engine operations behind provisioned services
• ci-cd - pipeline design that invokes Terraform
• docker - container image design

Rules

1. Pin providers, modules, and CI actions. Commit the dependency lock file.
2. Protect state and secrets. Encrypt, lock, restrict, and audit state; never commit credentials.
3. Use least privilege and explicit lifecycle controls. Do not hide a destructive replacement.
4. Do not use provisioners. Use declarative infrastructure, user data, or ansible.
5. Separate high-risk/CDE state. Give it an independent backend, identity, and approval boundary.
6. Use OIDC for CI where supported. Keep plan and apply identities separate and narrowly scoped.
7. AI does not own terraform apply. A human reviews the concrete plan, the plan is archived, and the human authorizes the change.