terraform-stack

Terraform / OpenTofu Stack Standard (OpenTofu 1.12+)

Canonical guidelines for infrastructure as code with OpenTofu (the open-source Terraform fork and default engine — the CLI binary is tofu). Reserve HashiCorp terraform for repositories that require a BSL-licensed feature or an employer mandate, and mention the deviation.

1. Core Stack

• Engine: OpenTofu 1.12+ via mise (opentofu tool, tofu binary). Every terraform {} block and .tf file works unchanged; OpenTofu adds client-side state encryption on top.
• Task Runner & Hooks: mise.toml (mise.toml) exposes the canonical vocabulary per the mise skill — install (init + tflint rulesets + hooks), format (tofu fmt + dprint), check (fans out below), test (tofu test), build (plan artifact), build:docs (terraform-docs). lefthook.yml (lefthook.yml) wires pre-commit (format → leaks → check) and pre-push (test) per the lefthook skill.
• Check Fan-Out (all static, parallel, cloud-free): check:format (tofu fmt -check + dprint), check:validate (tofu validate), check:lint (tflint --recursive with the pinned rulesets in tflint.hcl), check:scan (trivy config for misconfigurations, per the vocabulary in the mise skill), check:leaks (gitleaks).
• Docs: terraform-docs injects the module's inputs/outputs table into README.md between <!-- BEGIN_TF_DOCS --> / <!-- END_TF_DOCS --> markers, configured by terraform-docs.yml.
• Apply Is Manual: build produces tmp/plan.tfplan; applying it is a deliberate human step (tofu apply tmp/plan.tfplan), never a task or hook — plans mutate infrastructure and money.

2. Project Scaffolding Workflow

1. Information: Define the project Slug, GCP Project ID, and default Region.
2. Config Initialization: Copy and customize:
   • mise.toml (mise.toml) and lefthook.yml (lefthook.yml).
   • .tflint.hcl (tflint.hcl) — pins the terraform preset and the GCP ruleset release.
   • .terraform-docs.yml (terraform-docs.yml) and add the TF_DOCS markers to README.md.
   • dprint.json per the dprint skill, .gitignore (gitignore), LICENSE per the project-license skill.
3. Scaffold Sources (flat root module — no modules/ tree until a unit is reused):
   • versions.tf (versions.tf) — version constraints, provider pins, and the commented GCS backend + encryption blocks.
   • main.tf (main.tf), variables.tf (variables.tf) (typed, validated inputs), outputs.tf (outputs.tf).
   • terraform.example.tfvars (terraform.example.tfvars) — non-secret example and static-scan values; replace the project ID before planning.
   • tests/main.tftest.hcl (main.tftest.hcl) — plan-only native tests.
4. Git & Validation: git init --initial-branch=main, then mise run install, format, check, test — all green without any cloud access, because the backend ships commented and tests run in plan mode. Commit .terraform.lock.hcl (provider pins); on multi-platform teams run tofu providers lock -platform=linux_amd64 -platform=darwin_arm64 so the lockfile carries hashes for both.
5. Backend Promotion: Once real state exists, create the versioned GCS bucket (commands inline in versions.tf), uncomment the backend "gcs" block, and re-run mise run install — tofu init migrates local state after an explicit prompt.