Ansible + Terraform managing the homelab infrastructure: Proxmox hosts, the k8s and Ceph VMs and
clusters on top, and the Linux dev box baseline. Argo CD deploys the Kubernetes workloads from
deploy repos — two monorepos with a directory per app, and a dedicated repo for each app with a
source repo of its own; Jenkins runs this repo's deploys. Components are ansible/, terraform/
and the architecture artifact — kc project list is authoritative.
Before proposing changes, read /work/AnsibleSpecs/decisions.md
— homelab doctrine: tool split, secrets, networking, MAC scheme, OS update policy — and the
relevant slice under /work/AnsibleSpecs/slices/. Operational runbooks
are in docs/runbooks/. If a decision changes, update decisions.md rather than
leaving a stale note elsewhere.
SOPs go in /work/SOPs, from any project: a procedure the operator does by hand
when a trigger fires ("after a Claude Code release", "before powering off a PVE host"). It is a
public repo, published as a static site at https://pvginkel.github.io/SOPs/ so it stays readable
with the homelab down; its README has the format. Runbooks stay in docs/runbooks/: the site
mirrors them at build time, and an SOP links to one instead of copying its steps.
This repo overrides the stock orchestrator posture. Most of the work here is orchestrator work — investigation, diagnostics, reading live state, editing a runbook, fixing a role, preparing an operator command. Do that directly and frictionlessly. You are a helpful infrastructure agent, not a gatekeeper.
Before acting, make one determination: is this a managed change to an infrastructure repo (an
Ansible role/playbook, a Terraform module, a deploy repo, a DockerImages image) substantial
enough to warrant a tracked slice? Then push back on doing it ad hoc and route it through
/dev:triage → /dev:plan-slice → /dev:run-slice. Each is a separate, explicit operator step;
authoring a slice is never permission to run it.
Otherwise — a quick fix, a diagnosis, a one-off command, a doc touch — just do it. No slice, no ceremony. When unsure which side a request falls on, say which way you're leaning and ask.
A coordinated cross-repo change, or one whose context lives in AnsibleSpecs, is Ansible-led even when the code lands elsewhere.
The operator runs every terraform apply, terraform destroy and ansible-playbook against real
infrastructure, including the scratch fleet — it lives on the production PVE cluster even though
the VMs are disposable. Claude prepares the change, proposes the exact command, and waits. Hand
back full output for parsing, not "looks good."
The operator works in this same pod and sees the same /work/<repo> paths, so this is a rule about
authority, not access. changed=N>0 and terraform state mutations are the operator's keystroke.
A slice may deviate from this where the operator rules so in its plan, and only as far as that
ruling reaches.
A push to main is safe — IaC/Build-Main only lints, validates, plans and runs the destroy check,
and starts the SOPs site's Publish workflow when the push touched docs/runbooks/. Convergence is the separate manual IaC/Apply job; never start it.
Mechanics — the toolchain, the canonical command shape, the cluster credentials (config-prd-write
is cluster-admin on prd), and writing OpenBao secrets — are in docs/live-infra-access.md.
- OpenBao secret values.
bao kv get, thekv/data/...endpoint, and anything else returning a credential need explicit operator permission for each path. Listing and metadata reads (bao kv list,bao kv metadata get,bao policy read) a 52B8 re fine for navigation and audit. Reading a value is a credential disclosure: ask first, scope to the leaf, don't widen. - The operator's shell history.
~/.bash_historyand equivalents on any host are off-limits regardless of file mode — they expose past credential entry. If you need to know what was run, ask.
The toolchain lives in the iac sidecar, not this container: cexec iac <cmd> for poetry,
ansible, terraform, kubectl, helm, bao, step. Ansible is only in the repo's poetry virtualenv,
not on the sidecar's PATH: run it as cd /work/Ansible/ansible && cexec iac poetry run ansible…,
where ansible.cfg sets the inventory and roles path. Curated entry points are kc project setup|lint|test. No pre-commit hook — run kc project lint before proposing a commit;
IaC/Build-Main runs the same gates only after the push. Terraform plan/apply work here as well
as on srviac, which Jenkins uses and which stays up when Kubernetes is down. Details in
docs/live-infra-access.md.
All under /work, same paths for Claude and operator: AnsibleSpecs (decisions, slices — a
separate git repo, commit there too), DockerImages, HomelabTerraformProvider,
Charts (the homelab-shared Helm library chart and the https://charts.home chart repository —
see its README), ArgoCDTools (two images: argocd-hook, the Argo CD Terraform PreSync hook, and
aac-tools, the architecture-as-code commands a repo's checkout runs — see its README),
ArgoCDDeploy (Argo CD's own deploy repo — the wrapper chart, the registry chart releases/,
the releases AppProject and the argocd-hooks namespace),
Architecture
(the architecture-as-code contract: pipeline-producers.yaml, the element/relation schema, the
shared product catalog and the producer manual),
JenkinsPipelineUtils (the shared library every Jenkinsfile in the estate loads, and the source
of the Jenkins pipeline style guide served at https://dev-guides.home/pipelines/; owned by this
project, its cards in YouTrack ANS and its slices in AnsibleSpecs), SecretRotator
(the OpenBao rotation platform, run nightly on srviac as an iac pipeline; YouTrack SR), SOPs
(the standard operating procedures and their GitHub Pages site, above), and the two app deploy
monorepos, PlatformAddOnsDeploy (each app deployed from an upstream Helm chart) and
HomelabAppsDeploy (each app with a chart of its own and no source repo), one directory per app
named after its registry key; slices 056–059 cite them as /work/scratch/<Monorepo>, read that as
/work/<Monorepo>. Three dedicated app deploy repos are declared too, the ones this environment's
work rolls through, so track_build.py follows their Argo CD roll: PilotDeploy (a PilotApp
promotion), PipelinesDeploy (a JenkinsPipelineUtils build) and DevGuidesDeploy (a DevGuides
build). The set is
declared in .kubecoder/config.yaml; adding an ordinary entry needs no restart — clone it to the
path the entry resolves to, run kc project setup in it, and add it to Ansible.code-workspace in
the same commit (a shared: true entry is mounted, so it takes kc env restart and is never
cloned by hand). A repo needed only for the task at hand goes under /work/scratch/<Repo> with no
entry, including one a slice changes. How a slice targets such a repo is in the dev plugin's docs/plan-template.md.
KubeCoderDeploy (KubeCoder's deploy
repo, the Argo CD pilot — see its README) and HelmCharts (the deploy path before Argo CD,
archived 2026-09-28) are such repos: older docs and slices cite them as /work/<Repo>, read that
as /work/scratch/<Repo>. So are the other dedicated app deploy repos, an <App>Deploy for each
app with a source repo of its own (DnsmasqDeploy, TfmirrorDeploy and ChartsDeploy among them).
A moved app's old <App>Deploy, which older docs cite, is archived;
read it as the app's directory in its monorepo. The iac
runner's tree lives in this repo at support/iac-agent/ — that is the copy to edit and the one the
iac_agent role installs. Older docs mention /work/Obsidian and
/work/IaCAgent — neither is cloned here any more, so treat those citations as historical
provenance.
On every microk8s channel bump, re-check whether the per-node dqlite-watchdog.timer (microk8s
role) can be retired — it works around an unreleased upstream bug. Removal checklist in
docs/runbooks/k8s-upgrade.md and
docs/runbooks/dqlite-watch-freeze.md. The whole bump, in
order, is the SOP microk8s-channel-bump.md.
Ask. The operator prefers clarifying questions over silent assumptions, and a decision with downstream consequences for prod is always worth a question first.