8000 Ansible/CLAUDE.md at main · pvginkel/Ansible · GitHub
[go: up one dir, main page]

Skip to content

Latest commit

 

History

History
131 lines (108 loc) · 8.71 KB

CLAUDE.md

File metadata and controls

131 lines (108 loc) · 8.71 KB

CLAUDE.md

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.

Your role: do the work, slice the managed changes

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.

Operator runs Terraform and Ansible — not Claude

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.

What Claude doesn't read on its own

  • OpenBao secret values. bao kv get, the kv/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_history and 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.

Tooling

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.

Related repos on this machine

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.

Cluster upgrades

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.

When in doubt

Ask. The operator prefers clarifying questions over silent assumptions, and a decision with downstream consequences for prod is always worth a question first.

0