cluster-autoscaler-with-capi/CLAUDE.md

CLAUDE.md

Home-lab research project: cluster-autoscaler + Cluster API on Proxmox VE (phase 1), then a KVM/libvirt provider (phase 2) and Kamaji hosted control planes / "poor man's KaaS" (phase 3). Start with README.md; details live in docs/.

Owner context

Experienced SRE. Be concise and technical; skip basics (k8s internals, Go, Linux, distributed systems).

Lab facts (don't re-derive)

• PVE node pv1-1, API https://192.168.0.8:8006, token capmox@pve!capi (privsep 0).
• VM network: vmbr0 is VLAN-aware, VMs in VLAN 4 → always bridge=vmbr0 + tag/vlan: 4, never vmbr0.4@vmbr0 (that is an ip link name, not a bridge).
• Storage: local (iso, dir) and local-lvm (LVM-thin) → disks are raw, never qcow2.
• Build host for image-builder: 192.168.4.181 (VLAN 4 must reach it on 8000–9000 during builds).
• Node template: ubuntu-2404-kube-v1.35.9 (image-builder v0.1.55). Login only via cloud-init.
• Management cluster: VM 201 lab-mgmt, 192.168.4.21 (ssh ubuntu@), built by the idempotent ansible/mgmt.yml (re-run must be changed=0); admin kubeconfig ~/.kube/lab-mgmt.kubeconfig.
• Required PVE ACLs: PVEVMAdmin + PVEAuditor on /, PVEDatastoreAdmin on /storage, PVESDNUser on /sdn/zones/localnetwork.

Version rules

• docs/versions.md is the source of truth. Any version change updates it in the same change.
• Before proposing any deployment or upgrade, verify versions are current (use the k8s-version-check skill if available). Go module proxy / git ls-remote / Helm index.yaml work even when the GitHub API is unavailable.
• CAPI core is pinned to v1.12.x because CAPMOX v0.9 is only tested on CAPI 1.11/1.12. This caps workload Kubernetes at 1.35 and cluster-autoscaler at 1.35.x. Don't bump CAPI unless the CAPMOX compatibility table allows it.
• Always pin versions explicitly (management cluster: ansible/group_vars/all.yml; helm install --version); never rely on "latest".
• CAPI providers are managed by cluster-api-operator (Provider CRs from ansible/mgmt.yml). Never run clusterctl init/upgrade/move/delete against the management cluster; clusterctl is only for generate cluster (always with --infrastructure proxmox:v0.9.1), describe, get kubeconfig.
• Check a provider's metadata.yaml contract and CAPI version (go.mod) before adding it to the management cluster — all providers share one CAPI core (known skew: Kamaji CP provider v0.21.0 is on CAPI 1.13).

Facts about providers: verify in source

READMEs lag. For "does provider X support Y" read the API types and templates of the exact tagged release (Go proxy zip: https://proxy.golang.org/<module>/@v/<ver>.zip). Delegate to the upstream-researcher agent for anything non-trivial.

Safety

• Never commit secrets: PVE token secret, kubeconfigs, clusterctl.yaml (see .gitignore).
• Cluster inspection is read-only via the cluster-inspector agent and read-only kubeconfigs (.claude/cluster-inspector/, see its README). Mutations (kubectl apply/delete/scale, qm, pveum) are proposed as commands for the owner to run unless explicitly asked to execute them.
• Don't delete Proxmox VMs/templates or CAPI objects on your own initiative.

Conventions

• Docs in English, Markdown, Mermaid for diagrams (Gitea renders it).
• Troubleshooting findings go into the relevant doc's troubleshooting/fixes table: symptom → root cause → fix.
• Example configs live in configs/ as *.example or non-secret values files.

Project history

Research repo: plans, conversations and decisions are kept in the repo, dated. Timestamps always come from date (+%Y-%m-%d-%H%M for file names, +%Y-%m-%d %H:%M %Z for headings), never guessed. Summaries only, never raw transcripts; mask secrets and check the staged diff before committing.

What	Where	When
Plans	docs/plans/YYYY-MM-DD-HHMM-<slug>.md	every plan-mode plan
Execution logs	docs/plans-executions/<plan's file name>	after each step of an approved plan
Session notes	docs/sessions/YYYY-MM-DD-HHMM-<slug>.md	research/design/debugging conversations without a plan
Decisions	docs/decisions.md (one table)	a direction chosen, rejected or reversed
Prompts	docs/prompts/YYYY-MM-DD-HHMM-<slug>.md	long crafted prompts/specs that kick off work (verbatim)
Reviews	docs/reviews/YYYY-MM-DD-HHMM-<slug>.md	review findings, most severe first, - [ ] ticked as processed
Changelog	CHANGELOG.md, newest on top	lab milestone, version change, design direction, new runbook/config — after the owner confirms it works

• Plans: header # Plan: <title> + **Created:** <timestamp>. Plan mode can only write to ~/.claude/plans/, so right after ExitPlanMode the first action is copying the plan into docs/plans/ and committing it on its own, before any work starts.
• Execution logs: a - [ ] Step N — <title> checklist on top (the authoritative status; a new session resumes from this file alone), then one section per step in chronological order, committed with that step's work. Light prose; exact commands as fenced blocks (clusterctl, helm, kubectl apply, qm, Packer), each with one line on why it was run that way, including commands the owner reports running on the lab and outputs that mattered (VM IDs, IPs, resolved versions, errors). Call out deviations from the plan; end with "Worth noting". Problems also go into the relevant fixes table, linked from the log.
• Session notes: write one unprompted when a conversation produced a finding worth keeping (option compared or rejected, compatibility check, root cause, open question) that no plan covers; mention it in the reply. Sections: Question, What was checked (sources, versions with date checked), Findings, Open questions, Follow-ups. Extend the note if the topic continues.
• Decisions: never rewrite a row; a reversal is a new row and the old one becomes superseded by #N. Design-doc suggestions are proposed until lab work confirms them. Link the plan/session/doc with the reasoning. README "Key decisions so far" stays the short summary.

Git

• Remote: Gitea gitea.home.hrajfrisbee.cz/kacerr/cluster-autoscaler-with-capi.
• Docs, configs and history files go straight to main. Phase-3 Go code or anything the owner calls a feature: feat/<slug> branch, git push -u, MR via tea pr create --title … --description … --base main --head <branch> (fallback: print …/compare/main...<branch>). Never merge or delete branches from the CLI.
• Commit messages end with a Co-Authored-By: trailer for Claude. /ship commits and pushes.