Glossary
Terms, hostnames and addresses used across this repo. Every entry below is
verified against a manifest, variable file or policy document in-tree; the
authoritative source is named where it is not obvious.
Sites and addressing
| Term |
Meaning |
cauda |
Project name for the dual-site self-hosted Kubernetes GitOps repo and its clusters. |
home |
Site identifier for the 10.1.x.x subnets. |
office |
Site identifier for the 10.2.x.x subnets. |
k8s-ancilla |
Kubernetes cluster name (cluster_name, ansible/inventory/group_vars/all.yml). |
wlan-iot / wlan-guest |
The only VLANs that do not route freely between sites at the gateway (PRINCIPLES.md rule 14). |
10.1.20.10 / 10.2.20.10 |
Site-local kube-apiserver VIPs (api_vip_home / api_vip_office), served on :6443 by kube-vip. |
k8s-home.infra.cauda.dev |
Cluster API endpoint for home via the cauda-home cloudflared tunnel → tcp://10.1.20.10:6443. |
k8s-office.infra.cauda.dev |
Cluster API endpoint for office via the cauda-office cloudflared tunnel → tcp://10.2.20.10:6443. |
cauda-home / cauda-office |
Cloudflare Tunnel names defined in terraform/cloudflare.tf. Not node-group names. |
Gateway and LAN service VIPs
Cilium Gateway API entrypoints, from cluster/gateway/ and
cluster/kyverno/gateway-zone-pinning.yaml.
| VIP |
Resource |
Purpose |
10.1.30.10 |
Gateway main-home |
Home LAN entrypoint (home LB pool). |
10.1.30.12 |
Gateway main |
Home-pool Gateway behind cloudflared inbound. |
10.1.30.13 |
Gateway private-home |
Home private/LAN-only Gateway; also the home Harbor bootstrap mirror. |
10.2.30.10 |
Gateway main-office |
Office LAN entrypoint (office LB pool). |
10.2.30.12 |
Gateway private-office |
Office private/LAN-only Gateway; also the office Harbor bootstrap mirror. |
10.1.30.11 / 10.2.30.11 |
Service coredns-lan |
LAN CoreDNS LoadBalancer IPs (cluster/coredns-lan/service.yaml), not Gateways. |
LB IP pools are 10.1.30.10–10.1.30.250 (home) and 10.2.30.10–10.2.30.250
(office), announced over L2/ARP from that site's worker nodes only.
Repo layout and state files
| Path |
Meaning |
.claude/skills/ |
Curated operational skills (63 of them), e.g. /site-detect, /scaffold-helm-app. |
.claude/hooks/ |
Session and post-edit validation hooks, e.g. session-start, before-write-protected, post-edit-*. |
.workingdir2/ |
Scratch and tracking artifacts: bugs, research digests, inventories, roadmap. Do not create new .workingdir/ artifacts. |
STATE.md |
Session log. Historical entries are append-only; a new entry is prepended so the newest is first. Update immediately when a bug is resolved or ruled out. |
PRINCIPLES.md |
Hard rules, testing philosophy, IaC discipline. |
AGENTS.md |
Per-module doc: purpose, topology, invariants, gotchas. |
docs/adr/ |
Architecture Decision Records in MADR format; the index table is generated by .githooks/check-adr-index.py. |
| Tool |
Role in this repo |
| ArgoCD |
GitOps engine; app-of-apps pattern rooted at cluster/argocd/app-of-apps.yaml, Applications under argocd-apps/. All cluster mutations flow through it. |
| Terraform |
Proxmox VM provisioning (bpg/proxmox) and Cloudflare zone/tunnel config (cloudflare/cloudflare 5.x). |
| Ansible |
Node preparation, kubeadm bootstrap, kube-vip and control-plane tuning playbooks. |
| Packer |
Builds the ubuntu-2604-cloud template from the Ubuntu 26.04 (resolute) cloud image (see ADR-0007). |
| Cilium |
CNI with kubeProxyReplacement, Gateway API, L2 announcements and Hubble. |
| Kyverno |
Policy-as-code admission and mutation engine. |
| CoreDNS |
Two decoupled instances: in-cluster CoreDNS and LAN CoreDNS (cluster/coredns-lan/). |
| cloudflared |
Per-site tunnels providing public ingress and TCP access to each cluster API. |
| Authentik |
SAML/OIDC identity provider. |
| Longhorn |
Distributed block storage. |
| CNPG |
CloudNativePG operator; clusters pg-cluster and pg-media. |
| Hubble |
Cilium network-flow observability; TLS pinned via a cert-manager issuer. |
| Tetragon |
eBPF runtime security observability (apps/security/tetragon). |
| Loki / Prometheus / Grafana |
Logging, metrics and dashboards under argocd-apps/monitoring/. |
| Velero |
Cluster backup and restore. |
Rules and conventions
| Term |
Meaning |
| zero-warnings cascade |
Five validation layers: IDE → pre-commit → pre-push → CI → pre-sync (argocd app diff). |
| conventional commits |
type(scope): subject, enforced by commitlint.config.js with a fixed type and scope enum. |
| deep-dive |
Component workflow shipping all six deliverables: research digests, decision matrix, skills, hooks, AGENTS.md, STATE.md delta. Config-only PRs are incomplete. |
//nolint / # noqa / # disable= |
Forbidden without a justification comment naming the issue and an expiry date. |
latest |
Forbidden image tag; all images and charts are pinned. |
kubectl apply |
Forbidden outside the ArgoCD flow; sole carve-out is the one-time ArgoCD bootstrap in README.md. |
terraform apply |
Forbidden outside a reviewed PR. |
| click-ops |
Manual UI configuration, e.g. the Cloudflare dashboard. Forbidden; all config goes through Terraform/API. |