home-network-k3s-impl/infra/devcontainer

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.