Terraform / OpenTofu infrastructure-as-code: layout, state, modules, safety, CI/CD, secrets.
\nVersion context (verified 2026-06): Terraform 1.15.x (BUSL-1.1 licence since 1.6) · OpenTofu 1.12.x (MPL-2.0 fork of Terraform 1.5.x). Commands below are interchangeable (terraform ↔ tofu) unless flagged. See Terraform vs OpenTofu for the decision note.
| File | \nCovers | \n
|---|---|
| references/state-management.md | \nRemote backends, locking, moved/import/removed blocks, state surgery, drift detection | \n
| references/module-patterns.md | \nModule composition, variable validation, optional/nullable, output contracts, versioning | \n
| references/cicd-pipelines.md | \nGitHub Actions plan/apply, OIDC auth, policy gates (tflint/trivy/checkov/OPA), Atlantis/HCP | \n
| references/security-and-secrets.md | \nSecrets in state, ephemeral resources, write-only arguments, SOPS/Vault, sensitive limits | \n
| assets/github-actions-terraform.yml | \nReady-to-adapt PR-plan + OIDC-apply workflow | \n
| scripts/check-action-refs.sh | \nStaleness verifier for any workflow's uses: action refs (offline structural / live API resolve) | \n
\n\nThe action versions pinned in
\ngithub-actions-terraform.ymlare point-in-time (verified 2026-06). Runscripts/check-action-refs.sh --livebefore adopting — a tag that was valid at write time may have been retracted or never existed (e.g.trivy-action@0.33.1vs the realv0.33.1).
How many environments / accounts?\n│\n├─ One environment, one team\n│ └─ Single root module + tfvars. Don't over-engineer.\n│\n├─ Multiple environments (dev/staging/prod)\n│ ├─ Need different backend/account/region per env? (usually YES for prod isolation)\n│ │ └─ DIRECTORY PER ENVIRONMENT (recommended default)\n│ │ environments/{dev,staging,prod}/ each a thin root calling shared modules\n│ │\n│ └─ Environments truly identical except a few variables, same backend account?\n│ └─ Workspaces are *acceptable* — but see the workspace caveats below\n│\n└─ Many teams / many state files / platform engineering\n └─ Directory-per-env + per-component state split (network / data / app)\n Consider Terragrunt, Terraform Stacks (HCP), or OpenTofu + CI orchestration\ninfra/\n├── modules/ # Reusable child modules (no provider/backend blocks)\n│ ├── network/\n│ │ ├── main.tf\n│ │ ├── variables.tf\n│ │ ├── outputs.tf\n│ │ └── versions.tf # required_providers ONLY (no provider config)\n│ └── app-service/\n├── environments/ # Root modules — one state file each\n│ ├── dev/\n│ │ ├── main.tf # module \"network\" { source = \"../../modules/network\" ... }\n│ │ ├── backend.tf # remote backend, env-specific key\n│ │ ├── providers.tf # provider config lives in ROOT only\n│ │ ├── terraform.tfvars # committed, non-secret env values\n│ │ └── versions.tf # required_version + required_providers pins\n│ └── prod/\n└── .tflint.hcl\n| Concern | \nDirectories | \nWorkspaces | \n
|---|---|---|
| Separate backend/account per env | \nYes — each root has its own backend.tf | \nNo — one backend, envs differ only by state key | \n
| Blast radius of wrong-env apply | \nLow — you're physically in prod/ | \nHigh — invisible terraform workspace select state | \n
| Env-specific config divergence | \nNatural (different main.tf if needed) | \nterraform.workspace conditionals creep everywhere | \n
| Prod IAM isolation | \nPer-dir CI role | \nSame credentials see all envs | \n
| Visibility in code review | \nDiff shows which env changed | \nWorkspace is runtime state, not in the diff | \n
Workspaces fit short-lived ephemeral copies (PR preview envs) — not the dev/prod boundary. HashiCorp's own docs say workspaces are \"not suitable for strong separation.\"
\nterraform.tfvars # auto-loaded — per-root committed defaults (non-secret)\n*.auto.tfvars # auto-loaded — generated/local overrides\nprod.tfvars # explicit only: terraform plan -var-file=prod.tfvars\nTF_VAR_db_password=... # env var injection — secrets in CI, never in files\nGotcha: -var-file + directories-per-env is belt-and-braces; with workspaces it's load-bearing and one forgotten flag applies dev values to prod.
Full detail: references/state-management.md.
\n| Task | \nCommand / block | \nNotes | \n
|---|---|---|
| Remote backend (AWS) | \nbackend \"s3\" { bucket, key, region, use_lockfile = true } | \nS3-native locking (TF ≥1.10) — DynamoDB table no longer required | \n
| Rename resource in code | \nmoved { from = aws_x.a, to = aws_x.b } | \nDeclarative, reviewable, no CLI surgery | \n
| Adopt existing infra | \nimport { to = aws_x.a, id = \"i-123\" } + plan -generate-config-out=gen.tf | \nConfig-driven import (TF ≥1.5) beats terraform import CLI | \n
| Forget without destroy | \nremoved { from = aws_x.a, lifecycle { destroy = false } } | \nTF ≥1.7; OpenTofu 1.12 also has lifecycle { destroy = false } on resources | \n
| Drift detection | \nterraform plan -detailed-exitcode | \nExit 0 = clean, 1 = error, 2 = drift — cron it | \n
| Inspect state | \nterraform state list / state show ADDR | \nRead-only, always safe | \n
| Move state (last resort) | \nterraform state mv SRC DST | \nPrefer moved blocks — see \"when NOT to\" below | \n
| Pull/push (emergency) | \nterraform state pull > backup.tfstate | \nALWAYS pull a backup before any surgery | \n
State surgery — when NOT to: if a moved/removed/import block can express it, use the block. CLI state mv/rm is immediate, unreviewed, unversioned, and a typo orphans real infrastructure. Legit uses: splitting state between roots, unwedging a failed migration. Always state pull a backup first.
Full detail: references/module-patterns.md.
\nmodule \"network\" {\n source = \"terraform-aws-modules/vpc/aws\"\n version = \"~> 6.0\" # pin minor-float for registry modules; exact pin in prod roots\n # ...\n}\n| Rule | \nWhy | \n
|---|---|
| Composition over inheritance | \nRoots compose flat modules; never module-wraps-module-wraps-module | \n
| No provider blocks in child modules | \nProviders configured in root only; child declares required_providers | \n
validation blocks on variables | \nFail at plan with a real message, not mid-apply | \n
optional(type, default) in object attrs | \nCallers omit fields; nullable = false rejects explicit null | \n
| Outputs are the contract | \nOutput IDs/ARNs consumers need; document with description | \n
| Anti-pattern: thin wrappers | \nA module that just renames variables of another module adds a version-lag layer and zero value — call the upstream module directly | \n
□ plan output READ, not skimmed — every destroy/replace explained\n□ \"Plan: X to add, Y to change, Z to destroy\" — does Z surprise you?\n□ -/+ (replace) lines: check the \"forces replacement\" attribute\n□ Applying the SAME saved plan that was reviewed: plan -out=tfplan → apply tfplan\n□ prevent_destroy on stateful resources (db, state bucket, KMS keys)\n□ Cloud-side deletion protection too (RDS deletion_protection, S3 versioning+MFA-delete)\n□ No -target unless this is a declared emergency (see below)\n□ for_each (stable keys), not count, for any collection that can reorder\n| Footgun | \nDetail | \nFix | \n
|---|---|---|
count index shift | \nRemoving item 0 of a count list re-addresses every later item → destroy/recreate cascade | \nfor_each with stable string keys | \n
-target habit | \nSkips dependency graph; state diverges from config; hides drift | \nEmergency-only (broken dependency cycle, partial outage). Follow with a full clean plan | \n
prevent_destroy false comfort | \nDoesn't survive the block being deleted, and doesn't stop state rm + console delete | \nPair with cloud-native deletion protection | \n
| Dynamic blocks everywhere | \ndynamic for 2 static blocks is obfuscation | \nUse dynamic only over genuinely variable collections | \n
| Unpinned providers | \naws = \">= 5.0\" in prod pulls a breaking major the day it ships | \n~> 6.12 + commit .terraform.lock.hcl | \n
| Apply ≠ reviewed plan | \nPlan on PR, apply on merge re-plans — drift in between applies unreviewed changes | \nSave the plan artifact, or accept + re-review the merge plan | \n
resource \"aws_db_instance\" \"main\" {\n deletion_protection = true # cloud-side\n lifecycle {\n prevent_destroy = true # terraform-side\n ignore_changes = [password] # if rotated outside TF\n }\n}\nFull detail: references/cicd-pipelines.md · template: assets/github-actions-terraform.yml.
\nPR opened → fmt -check → validate → tflint → trivy/checkov → plan → plan posted as PR comment\nPR merged → plan (fresh) → apply, authenticated via OIDC — no long-lived cloud keys\nNightly → plan -detailed-exitcode → exit 2 ⇒ drift alert\naws-actions/configure-aws-credentials with role-to-assume, never AWS_ACCESS_KEY_ID secrets. Same supply-chain doctrine as this repo's rules: short-lived tokens, no standing credentials.uses: actions/checkout@<sha>), not floating tags.tflint (provider-aware lint), trivy config / checkov (misconfig scan), OPA/conftest for org policy (\"no public buckets\").| Orchestrator | \nFit | \n
|---|---|
| Plain GitHub Actions | \nDefault — full control, free, template in assets/ | \n
| Atlantis | \nSelf-hosted PR automation, atlantis plan/apply comments, locking per dir | \n
| HCP Terraform / Terraform Cloud | \nManaged runs, Sentinel policy, state hosting; free ≤500 resources | \n
| Spacelift / env0 / Digger / Scalr | \nCommercial Atlantis-likes; Digger runs inside your Actions | \n
uses: ref stalenessGitHub Action versions rot: a tag gets retracted, or a workflow pins one that never existed. scripts/check-action-refs.sh lints every uses: owner/repo@ref line. It's general — pass any workflow file(s) as positionals (default: this skill's own assets/github-actions-terraform.yml).
# Structural only, no network — well-formedness of every uses: ref (CI-safe gate).\n# Floating @main/@master → WARN (exit 0; use --strict to fail). Malformed → exit 4.\nscripts/check-action-refs.sh --offline .github/workflows/ci.yml\n\n# Live — resolve each ref against the GitHub API. A 404 (ref doesn't exist) → exit 10\n# DRIFT; API unreachable/rate-limited → exit 7 (advisory, never fails the build, §7).\n# Set GITHUB_TOKEN to dodge the unauthenticated rate limit.\nGITHUB_TOKEN=$GH_PAT scripts/check-action-refs.sh --live .github/workflows/*.yml\n\nscripts/check-action-refs.sh --json --offline | jq '.data[] | select(.status!=\"ok\")'\n--live is the check that catches the classic aquasecurity/trivy-action@0.33.1 mistake — that tag 404s; the real one is v0.33.1. Run live on a schedule (never as a blocking PR gate), offline in PR CI.
# tests/network.tftest.hcl — native test framework (TF ≥1.6 / OpenTofu ≥1.6)\nvariables { cidr = \"10.0.0.0/16\" }\n\nrun \"valid_cidr_plan\" {\n command = plan # plan = fast unit-ish; apply = real integration\n assert {\n condition = aws_vpc.main.cidr_block == \"10.0.0.0/16\"\n error_message = \"VPC CIDR did not match input\"\n }\n}\n\nrun \"rejects_tiny_cidr\" {\n command = plan\n variables { cidr = \"10.0.0.0/30\" }\n expect_failures = [var.cidr] # asserts the validation block fires\n}\nterraform test runs every *.tftest.hcl under tests/; command = apply runs create real (then auto-destroyed) infra — use a sandbox account. Mock providers (mock_provider blocks, TF ≥1.7) fake apply without credentials. For multi-tool/Go-level orchestration (retry, real HTTP probes), Terratest is the heavyweight alternative — native terraform test covers most module CI needs first.
Full detail: references/security-and-secrets.md.
\n| Mechanism | \nVersion | \nWhat it does | \n
|---|---|---|
sensitive = true | \nall | \nRedacts from CLI output only — value still plaintext in state | \n
Ephemeral resources (ephemeral \"...\") | \nTF ≥1.10 / OpenTofu ≥1.11 | \nFetch secret at run time; never persisted to state or plan | \n
Write-only arguments (password_wo) | \nTF ≥1.11 / OpenTofu ≥1.11 | \nSend secret to provider; never stored in state; rotate via _wo_version | \n
| SOPS-encrypted tfvars | \ntool | \nSecrets encrypted at rest in git; decrypted at plan time | \n
| Vault / cloud secret manager | \ntool | \nReference by ID; resource reads secret at boot, TF never sees it | \n
| OpenTofu state encryption | \nOpenTofu ≥1.7 | \nClient-side AES-GCM encryption of state/plan — no Terraform equivalent | \n
Rule zero: treat state as secret regardless. Encrypt the backend (SSE-KMS), restrict IAM on the bucket, never commit *.tfstate (gitignore it).
| \n | Terraform | \nOpenTofu | \n
|---|---|---|
| Licence | \nBUSL-1.1 since 1.6 (no production use competing with HashiCorp; fine for normal internal use) | \nMPL-2.0 — genuinely open source, Linux Foundation | \n
| Current | \n1.15.x | \n1.12.x | \n
| Exclusive features | \nStacks (HCP-tied), Terraform Cloud agents, terraform query | \nState/plan encryption, provider for_each iteration, -exclude flag, early variable eval in backend/module blocks, OCI registry distribution, .tofu file extension | \n
| Registry | \nregistry.terraform.io | \nregistry.opentofu.org (mirrors most providers) | \n
| Compatibility | \n— | \nForked at 1.5.x; HCL/state compatible for mainstream use, diverging feature-by-feature since | \n
Decision: vendors and anyone redistributing IaC tooling commercially → OpenTofu (licence risk). Teams on HCP Terraform/Sentinel → Terraform. Everyone else: either works; OpenTofu's state encryption is the single biggest technical differentiator. Migration terraform → tofu is tofu init + state-compatible up to ~1.8-era features; the gap widens each release — migrate early or commit.
terraform init -upgrade # init / upgrade providers within constraints\nterraform fmt -recursive -check # CI: fail on unformatted\nterraform validate # syntax + internal consistency (no creds needed after init)\nterraform plan -out=tfplan # save plan for exact-apply\nterraform show -json tfplan | jq # machine-readable plan (policy tools eat this)\nterraform apply tfplan # apply EXACTLY the reviewed plan\nterraform plan -detailed-exitcode # 0 clean / 2 drift — for cron drift checks\nterraform plan -refresh-only # show drift without proposing config changes\nterraform apply -replace=aws_x.a # force recreate one resource (replaces old taint)\nterraform state pull > backup.json # ALWAYS before surgery\nterraform output -json # consume outputs in scripts\nterraform graph | dot -Tsvg > g.svg # dependency graph\ntofu init # OpenTofu: same verbs throughout\n