Infrastructure as Code

Canonical infrastructure as code with OpenTofu (the open-source Terraform fork; the binary is tofu). A repository that needs a BSL-licensed feature or employer-mandated HashiCorp Terraform pins terraform in its own mise configuration and documents the deviation.

Defaults

• Default to OpenTofu via project mise pins: opentofu tool, tofu binary; verify provider, backend, state, and language-feature compatibility before a Terraform migration. The workstation installs tofu and tflint globally only for the editor; declare opentofu, tflint, and terraform-docs in the project's mise.toml with mise use --pin <tool>, as the template does.
• Use the template tasks and hooks: mise.toml exposes the canonical vocabulary per mise — check fans out to format, validate, lint (tflint), scan (trivy), and leaks; lefthook.yml wires the hooks per lefthook.
• Generate docs with terraform-docs: mise run build injects the inputs/outputs table between the TF_DOCS markers in README.md (add them once at scaffold time) per terraform-docs.yml, without cloud access.
• Authenticate without service-account keys: Application Default Credentials locally; Workload Identity Federation in CI per cloud-run bootstrap.

Workflow

1. Resolve the target: identify the root module, backend, workspace (tofu workspace show), cloud project, credentials, and the authorized change scope. A fresh clone runs mise run install first: validation, linting, and tests need tofu init providers and tflint --init rulesets.
2. Keep one state per concern: change the smallest root module that owns the resource, with one GCS prefix per small root module.
3. Check before planning: run mise run check and mise run test; tests stay offline only while every provider is mocked (the starter's mock_provider), otherwise plan-mode tests can authenticate, refresh state, and read data sources. Native tests over tests/*.tftest.hcl use command = plan (main.tftest.hcl); encode "must never happen" rules (public buckets, missing labels) as check:scan trivy findings or plan-test assertions.
4. Plan explicitly: mise run plan writes tmp/plan.tfplan for the selected backend, workspace, and cloud target; feed secrets per State and secrets below. A plan can access APIs, state, and data sources, so keep plan and apply out of automatic gates.
5. Apply only the reviewed plan when authorized: flag replacements, destroys, IAM, and cost in tofu show tmp/plan.tfplan, run tofu apply tmp/plan.tfplan against the same target, delete the saved plan, and confirm tofu plan -input=false -detailed-exitcode exits 0.

OpenTofu inside an application repository

• Keep modules under infra/: run tofu -chdir=infra ... and tflint --chdir=infra from one check:tofu task instead of copying the standalone template's task set.
• Validate without the live backend: run tofu -chdir=infra init -backend=false -input=false -lockfile=readonly with env.TF_DATA_DIR = "../tmp/tofu-check" (a relative path resolves from infra/), so a cached live backend can never make validation read remote state.

State and secrets

• State is secret: state can store sensitive resource attributes in plaintext — never in git, always in the versioned GCS bucket, ideally wrapped by OpenTofu's encryption block. Read state-encryption before enabling it or migrating existing state.
• Keep secrets out of tfvars and plans: *.tfvars is gitignored; commit only *.example.tfvars. Feed secrets as TF_VAR_<name> environment variables that the project's secret store or launcher injects into the tofu process only, never exported in the shell or passed as arguments. A saved plan stores ordinary variable values, sensitive ones included; declare secret inputs ephemeral = true, pass them only to write-only arguments (for example secret_data_wo with an incremented secret_data_wo_version), and supply them again at tofu apply tmp/plan.tfplan.

Gotchas

• Apply-mode tests create resources: command = apply creates real (then destroyed) resources; reserve it for behavior a plan cannot prove, with approved project access and cost.
• tflint rulesets are downloaded: tflint --init (in install:lint) fetches the plugins pinned in tflint.hcl; export GITHUB_TOKEN in CI to avoid API rate limits.
• Initialize before the CI gate: the shared ci.yml runs only mise run all, so add a step with tofu init -backend=false and tflint --init before it; validation, linting, and tofu test need the providers and rulesets.
• Provider majors move fast: versions.tf pins the google provider to one major with ~>; bump majors deliberately with upgrade-tools and read the upgrade guide, because resources rename across majors.

Task guides

• scaffold: Create a new OpenTofu root module from the templates, validate it offline, lock providers, and promote its GCS backend.
• state-encryption: Enable OpenTofu client-side state and plan encryption with GCP KMS, including plaintext state migration.

Documentation

• OpenTofu · tflint · trivy config · terraform-docs · State encryption
• Releases: OpenTofu
• Upstream: hashicorp/agent-skills per the vendor-skill policy; select only the Terraform or provider guidance the stack needs.
• Companion skills: mise (task vocabulary and project pins), github-actions (CI), code-security (full-repo scans), Google catalog (product skills).