Repository navigation
feat(tofu): provision lab guests with OpenTofu, state encrypted before the first apply (#445) - #803
Merged
Merged
Conversation
…e the first apply (#445) OpenTofu over Terraform because it encrypts state (ADR-0075). The key is a pbkdf2 passphrase in phoenix.env, escrowed in secrets/tofu.sops.yaml to the estate's two recipients: OpenTofu has no age key provider and ADR-0043 keeps age keys off phoenix. enforced = true on state and plan. Guards land before any apply: .gitignore, check-tracked-artefacts.sh patterns and its first --self-test, a tfstate-plaintext gitleaks rule, and phoenix recorded in docs/security.md as secret-bearing. check-tofu-state-encryption.sh --self-test proves the real encryption.tf against a canary, and that the checks fail without it. The first apply (proof guest 998) and its on-host proofs wait for template 901 (#440). The six hand-built domain guests stay out until #448. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
There was a problem hiding this comment.
Copilot review overview
🟡 Changes recommended
Pool teardown removes its ACL and the encryption test does not independently verify both enforcement guards.
Review effort: Balanced
Findings: 1
Open (3)
What changed in this PR
Adds OpenTofu-based Proxmox guest provisioning with encrypted state, validation guards, and operational documentation.
Changes:
- Adds a reusable full-clone guest module and proof guest.
- Enforces and tests state/plan encryption.
- Adds repository safeguards, CI integration, ADR, and runbooks.
| File | Description |
|---|---|
tofu/versions.tf |
Pins OpenTofu and providers. |
tofu/variables.tf |
Defines proof and SSH-key inputs. |
tofu/README.md |
Documents the OpenTofu tree. |
tofu/providers.tf |
Configures Proxmox access. |
tofu/modules/guest/variables.tf |
Defines guest module inputs. |
tofu/modules/guest/outputs.tf |
Exposes guest identifiers and addresses. |
tofu/modules/guest/main.tf |
Implements full-clone guests. |
tofu/guests.tf |
Declares proof guest and managed pools. |
tofu/encryption.tf |
Enforces state and plan encryption. |
tofu/.terraform.lock.hcl |
Locks provider artifacts. |
stacks/observability/compose.yaml |
Pins the OpenTofu CI image. |
secrets/tofu.example.yaml |
Defines the escrow secret shape. |
secrets/README.md |
Documents passphrase escrow. |
scripts/lint.sh |
Adds OpenTofu formatting and validation. |
scripts/check-tracked-artefacts.sh |
Rejects tracked OpenTofu artifacts. |
scripts/check-tofu-state-encryption.sh |
Tests encryption safeguards. |
scripts/check_container_health.py |
Excludes profiled OpenTofu service. |
README.md |
Updates documentation counts. |
docs/security.md |
Records phoenix secrets and controls. |
docs/runbooks/provision-lab-guests.md |
Adds provisioning and recovery procedures. |
docs/runbooks/build-the-jumpbox.md |
Extends phoenix credential setup. |
docs/roadmap.md |
Records OpenTofu implementation status. |
docs/changelog.md |
Adds the dated implementation record. |
docs/adr/0075-provision-lab-guests-with-opentofu-and-encrypt-its-state-from-the-first-apply.md |
Records the architecture decision. |
.gitleaks.toml |
Detects plaintext state. |
.gitignore |
Ignores state, plans, and caches. |
Files not reviewed (1)
- tofu/.terraform.lock.hcl: Generated file
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
… loses its grant (#445) The enforced fixture swapped the state and plan methods together, so either block losing enforced = true stayed green behind the other. One fixture per block now; deleting either line turns its own fixture red. Proxmox's pool delete drops the pool's ACL (delete_pool_acl), so the proof teardown removes phoenix's /pool/proof grant. The runbook, ADR-0075 and guests.tf say so, and the runbook re-grants before each proof rather than widening the grant to /pool. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Gerrrt
enabled auto-merge (squash)
October 2, 2026 05:05
…u-provision-825058 # Conflicts: # docs/changelog.md
main took ADR-0075 for the SSO re-acceptance (#799), so this branch's ADR becomes ADR-0076 and every reference to it moves; references to main's ADR-0075 are untouched. README counts both: 76 ADRs, 42 runbooks. The changelog keeps both sides' 2026-10-01 entries. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Gerrrt
added a commit
that referenced
this pull request
Oct 2, 2026
…ine-3a8fc3 main took ADR-0076 for OpenTofu (#803), so this branch's ADR is now ADR-0077 and its references follow; main's ADR-0075 and ADR-0076 references are untouched. README counts 77 ADRs and main's 42 runbooks. lint.sh keeps both new linters, tofu then ansible-lint. #445 landed leaving the six hand-managed and their move into tofu/ to #448 (ADR-0076 decision 7), with no MAC input on the guest module. ADR-0077 decision 6 and the docs now say the MACs are pinned when the six are declared there, rather than that #445 pins them. Refs #448 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.



Refs #445. This lands the code and every guard. The first apply and its two on-host proofs wait for template 901 (#440), so this does not close the issue.
What
tofu/(ADR-0076) usesbpg/proxmox, pinned exactly.enforced = trueon both state and plan, so a plaintext write is refused rather than made.-var proof=true.pbkdf2passphrase inphoenix.env.secrets/tofu.sops.yaml, encrypted to the estate's two recipients.phoenixcan write that copy and cannot read it.phoenix..gitignorecovers state, plans and.terraform/.check-tracked-artefacts.shasserts the same patterns are untracked, and gains its first--self-test(14 fixtures)..gitleaks.tomlgainstfstate-plaintext. It matches plaintext state by content under any name and stays silent on OpenTofu's encrypted wrapper.docs/security.mdrecordsphoenixas a secret-bearing host.scripts/check-tofu-state-encryption.shproves the encryption rather than assuming it.--self-test(10 fixtures): it copies the realtofu/encryption.tfnext to aterraform_datacanary. It then proves:enforcedrefuses an unencrypted method.git addof the state is refused, andgit add -ffailscheck-tracked-artefacts.sh.phoenix: the same script checks the real state, with the secret piped in on stdin.lint.shrunstofu fmt -check, theninit -backend=false -lockfile=readonly, thenvalidate. It usesghcr.io/opentofu/opentofu, pinned instacks/observability/compose.yaml.docs/runbooks/provision-lab-guests.md, plus updates to the jumpbox runbook, roadmap, changelog and README counts.Proved locally
All checks below ran with tofu 1.13.1, and all passed:
check-tofu-state-encryption.sh --self-test(10 fixtures)check-tracked-artefacts.sh --self-test(14 fixtures)lint.sh, plusshellcheckandyamllintcheck_docs.pyandcheck_sops_rules.pyMutation checks, run on copies:
enforced = trueturns the encryption suite red.stateblock turns it red..gitignorelines turns it red.check-tracked-artefacts.shturns its suite red.Not run locally: there is no Docker on this machine, so the image path of both tofu checks is first exercised by this PR's CI.
check_mounted_config.py --self-testfails locally for the same reason, and that is unrelated to this change.Still open (runbook §2–§4, on
phoenix, after #440)Pool.Allocateon/pool/proof. Whether Proxmox accepts that ACL before the pool exists is unverified.prometheus.git addmust refuse the state, andgit add -fmust turncheck-tracked-artefacts.shred.🤖 Generated with Claude Code