0 Fork 0

Files

T

jakman85andClaude Opus 5 f7d3884ad2 fix(ci): scope the requirement matcher to the diff and to non-doc files

`ci/touched-requirements.sh` documents its detection as "R-* tokens literally
present in the diff of changed files". It did not do that — it grepped the ENTIRE
CONTENT of every changed file. So a change inherited every requirement those files
had ever mentioned in prose, and `--require-all` then blocked the merge on
requirements the author never went near.

On this branch that meant editing the decision log and the tofu docs dragged in
five unrelated requirements, all on untouched lines, all legitimately uncovered:

  [coverage] REQUIRE: FAILED — required requirement(s) uncovered: [5 IDs]

The practical effect was that the PM could not append to the decision log without
failing CI — which is a fair part of why the log went stale in the first place.
This is the defect already logged as "FOLLOW-UP (WS-TEST): fix the matcher so real
requirements need not be exempted".

Two scoping rules, both learned from the gate blocking merges it should not have:

  1. Scan the ADDED/REMOVED lines of the diff, as the header always claimed.
     Removed lines count too — deleting a test's requirement tag, or a policy's
     self-declared ID, touches that requirement just as much as adding one.

  2. Skip `*.md`. An ID in prose is a REFERENCE, not a declaration: explaining a
     requirement is not changing behaviour against it. Rule 1 alone is not enough —
     a commit that documents a mis-attribution names the IDs involved and thereby
     re-triggers the very mis-attribution it fixes, and the decision log can never
     record which requirements a change concerned.

This TIGHTENS attribution rather than weakening the gate:
  - no requirement is exempted, and DOCUMENTED_GAPS is untouched;
  - authoritative declarations (`conformance.home.k3s/R-*` tags, Kyverno policies,
    ServiceDefinitions) all live in YAML, on lines a real change must touch;
  - the coarse path->requirement fallback is unchanged and file-type agnostic, so
    the doc subtrees that matter (conformance/, schemas/, catalog/, clusters/, ci/)
    stay covered either way.

Alternatives rejected: adding the five IDs to DOCUMENTED_GAPS genuinely weakens the
gate; scrubbing requirement IDs out of prose (precedent f9e9640) would mean editing
the decision log's own history to appease a matcher.

Gate semantics change — flagged in DECISIONS-LOG.md for review.

Also drops three R-TEST-06 mentions this branch had added to prose and refreshes
the now-stale "gate is RED" notes.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>

2026-08-27 00:06:28 -05:00

4.3 KiB

Raw Permalink Blame History

Dev toolbox (containerized baseline)

The toolchain for this repo is not all Python (OpenTofu, age, sops, flux, chainsaw, kyverno are Go binaries; only Ansible and a couple of linters are Python). Per the operator's rule it is therefore delivered as a pinned dev container — no host pollution, one reproducible baseline, and the same binaries CI uses.

This is the supported way to run anything in this repo. Don't install the toolchain on the host.

What's inside (pinned in `versions.env`)

Group	Tools
Provisioning	OpenTofu (`bpg/proxmox` provider), `ansible-core`, `openssh-clients`
GitOps / cluster	`flux`, `kubectl`, `helm`
Secrets	`sops`, `age` + `age-keygen`
CI gate	`yamllint`, `check-jsonschema`, `kyverno` CLI, `kyverno-json`, `chainsaw`, `yq`, `diffutils`, `make`
Misc	`qemu-img`, `cloud-utils`/`genisoimage`, `libvirt-client` (disk-image utilities only — leftovers from the libvirt era, harmless)

The conformance-tool versions are kept in lockstep with ci/versions.env so make -C ci gate in here is byte-identical to the CI runner (R-TEST-02). The image records the resolved set at /etc/dev-toolchain-versions.

Use

cd infra/devcontainer
./dev.sh build                       # build the image (needs network)
./dev.sh                             # build if needed + shell in /work (the repo)
./dev.sh run make -C ci gate         # the merge gate, exactly as CI runs it
./dev.sh run sops -d path/to.sops.yaml
./dev.sh run tofu -chdir=/work/infra/tofu plan

ENGINE=docker ./dev.sh to use docker instead of rootless podman.

What `dev.sh` mounts, and why each one matters

--network host — Ansible SSHes to the nodes through the pfSense NAT (192.168.2.102:225x) and kubectl/flux/tofu reach the kube-API (192.168.2.50:6443) and the Proxmox API (192.168.2.102:8006) on the host's network.
-v $REPO:/work (workdir) — the repo.
-v ~/.config/sops:/root/.config/sops — the age keyring, read-write. This is deliberate: the private key generated by bootstrap/sops/age-keygen.sh must land on the host, or it dies with the --rm container and every SOPS-encrypted secret in the repo becomes undecryptable.
-v ~/.ssh:/root/.ssh:ro — node SSH key (home_network).
-v ~/.config/home-k3s/ansible-vault-pass:...:ro — the Ansible vault passphrase, so vaulted group_vars decrypt unattended.
-v ../home-network-k3s:/home-network-k3s:ro + SPEC_REPO — the spec repo, read-only, when it exists beside this one. Without it ci/spec-immutability.sh honestly skips rather than passing — mount it, or that gate silently verifies nothing.
--security-opt label=disable — SELinux hosts, so the bind mounts work without relabeling.

tofu and ansible now run inside the container

This reverses the old Phase-1 limitation. When the dev cluster was on host libvirt, OpenTofu's dmacvicar/libvirt provider could not do a read-write qemu:///system connect from inside a container (polkit/PID-identity: Cannot find start time for pid), so tofu had to be extracted and run on the host. The cluster moved to Proxmox VE and the provider is now bpg/proxmox, which talks to the Proxmox HTTP API — nothing host-local is required. Ansible likewise only needs SSH, which --network host provides.

So: run everything in here. The host needs only podman (or docker).

kubectl inside the container — known gap

dev.sh sets KUBECONFIG to /work/infra/ansible/.cache/dev.kubeconfig, a libvirt-era path that no longer exists, and does not mount ~/.kube. Override it explicitly:

DEV_KUBECONFIG=/work/path/to/break-glass.kubeconfig ./dev.sh run kubectl get nodes

Use a break-glass cert kubeconfig, not the k3s-oidc context — OIDC login needs a browser, which a container shell does not have. See ../PHASE1-STATUS.md for both access paths. (Not yet fixed in dev.sh.)

Notes

Versions are best-effort pins; if a download 404s at build, bump the value in versions.env and rebuild. Keep the conformance-tool block aligned with ci/versions.env.
Secrets never enter the image — they arrive only as the bind mounts listed above.
This container is the toolchain, not the cluster. The cluster runs on Proxmox VE; see ../PHASE1-STATUS.md.

4.3 KiB Raw Permalink Blame History