home-network-k3s/GLOSSARY.md

Glossary

Shared vocabulary for this platform. If you introduce a term, define it here. When a word could mean two things (e.g. "VM"), this file disambiguates.

Platform concepts

• PaaS — Platform-as-a-Service; here, containerized workloads onboarded via GitOps.
• IaaS — Infrastructure-as-a-Service; here, virtual machines run inside the cluster via KubeVirt, managed through the same Kubernetes surface.
• ServiceDefinition — the operator-facing YAML object that declares a service's intent (kind, source, storage, egress, exposure, dependencies, update policy, observability). The platform renders concrete resources from it. See docs/13-service-catalog.md.
• Renderer — the catalog tool that generates a service's concrete manifests from its ServiceDefinition; generated output is not hand-edited.
• Wave — a dependency-ordered group of rendered apps reconciled and health-gated together, so a failing service holds back only its own wave and those above it.
• Golden path — the standard flow a service follows from catalog entry to running/monitored/ updated. See docs/01-architecture-overview.md.
• C2 / Command & Control — the UI at the root home.keithjackson.dev. See docs/12-command-center-ui.md.
• Apex — the root name home.keithjackson.dev, which serves the C2 UI.

The two kinds of VM (do not conflate)

• Infrastructure VM (Layer 1) — a cluster node: a bare-metal mini-PC, imaged and managed by Ansible, not KubeVirt. The name is historical.
• Application VM (Layer 2) — an IaaS workload running inside the cluster via KubeVirt, managed by Kubernetes/GitOps like a container.

Networking

• Default-deny — the baseline where no service may talk to another unless explicitly allowed at the port level (R-NET-01).
• Egress class — a service's declared outbound path: internet (standard WAN) or vpn (commercial VPN tunnel). See docs/03-networking-isolation-and-egress.md.
• Exposure class — how a service is reachable: internal (LAN/VPN-only) or public (published through the Cloudflare Tunnel, ADR-0016). A registered platform route may also be public.
• Cloudflare Tunnel — the outbound-only connection from in-cluster cloudflared to Cloudflare that carries all public HTTP(S) ingress; public records are proxied CNAMEs to <uuid>.cfargotunnel.com (ADR-0016).
• Kill-switch — the guarantee that a vpn-class workload leaks nothing to the plain internet if the tunnel drops (R-NET-06); fail-closed.
• Multi-WAN — multiple upstream internet uplinks with routing-rule-based selection. Out of scope: the site has one WAN (OQ-1).
• Egress VPN — the outbound path that carries vpn-class pods to the internet through the commercial tunnel (ADR-0015, ADR-0020).
• Remote-access VPN — the inbound WireGuard path that lets the operator's own devices join the LAN (ADR-0021). It shares nothing with the egress VPN but the word.
• Hairpin — a LAN client reaching a service through the site's own public address; the edge cannot be relied on for it, so no path may depend on it (R-DNS-04).
• L4 VIP — a LAN virtual IP that exposes a non-HTTP service directly, outside the shared Gateway.
• kube-vip — the virtual IP that gives the Kubernetes API one HA endpoint across the 3 servers.
• Egress Gateway — Cilium feature steering selected pods' egress through a chosen node/identity.
• Hubble — Cilium's flow-observability tool; the audit surface for isolation/egress.
• Gateway API — the Kubernetes standard for north-south ingress, implemented here by Cilium.
• Split-horizon DNS — serving different answers to internal vs. external clients for the same name.

Storage

• Longhorn — distributed replicated block storage across the 3 nodes (default 3 replicas). The durable home for app/config state and VM disks.
• Bulk tier — a separate storage class for large media (Plex library, downloads) that is not 3× replicated (R-STATE-04): NFS from a standalone TrueNAS, outside platform backup (ADR-0018). See docs/04-storage-and-state.md.
• CNPG (CloudNativePG) — the operator that runs the platform's replicated PostgreSQL clusters and archives them off-cluster with Barman (ADR-0019).
• CDI — Containerized Data Importer; provisions KubeVirt VM disks onto Longhorn PVCs.
• Velero — cluster backup/restore orchestration to an off-cluster target (DR).
• DR drill — a tested restore of resources + volumes proving R-STATE-03.

Delivery & lifecycle

• GitOps — desired state lives in git and is reconciled into the cluster automatically (pull-based). Engine: Flux CD.
• Drift correction — Flux reverting live changes back to git-declared state (R-GITOPS-03).
• Renovate — bot that opens machine-authored version-bump PRs for images and charts, and auto-merges those in the allowed classes through the merge gate (R-UPD-02, ADR-0023).
• Blast-radius component — an operator-designated platform component whose machine-authored update waits for human review (R-UPD-02).
• PM agent — the in-cluster AI Program Manager (pm-agent) that turns issues into pull requests; it never pushes to main or merges (ADR-0025).
• SOPS + age — the secret-encryption scheme; secrets live encrypted in git, decrypted in-cluster.
• cert-manager / ACME DNS-01 / Let's Encrypt — the trusted, automated TLS pipeline (R-TLS-*).
• ExternalDNS — controller that publishes DNS records from declared service intent.

Identity & access

• IdP (Identity Provider) — the central authority for user identity and login. Here: Keycloak (docs/15-identity-and-access.md).
• SSO (Single Sign-On) — log in once, reach every integrated service without re-authenticating.
• OIDC (OpenID Connect) — the token-based auth protocol services use to federate to Keycloak natively (a Keycloak client).
• Forward-auth — an identity-aware proxy (oauth2-proxy) that authenticates a request against Keycloak before forwarding it — used for apps without native OIDC.
• Forward-auth sidecar — the per-app oauth2-proxy container that enforces forward-auth inside the app's own pod, rather than at the Gateway (ADR-0022).
• Realm — a Keycloak tenant/namespace holding the platform's users, groups, and clients.
• Group — a Keycloak grouping that drives per-service authorization (auth.groups in a ServiceDefinition); the basis for least-privilege access (R-IDP-06).
• Break-glass — a documented emergency access path (e.g. a local admin on Gitea) so an IdP outage doesn't lock the operator out of recovery tools.

Environments

• dev/test — the former cluster that proved the platform; decommissioned 2026-09 (ADR-0017).
• prod — 3× mini-PC bare-metal cluster; the one live environment.
• Overlay — environment-scoped configuration (Kustomize/vars) layered on shared base config; the only thing a future environment would change (R-ENV-02).

Governance

• Requirement ID (R-*) — a stable, referenceable requirement from docs/00-vision-and-scope.md.
• ADR — Architecture Decision Record; an append-only, superseding-only decision ledger under decisions/.
• Workstream (WS-*) — a durable area of ownership; maps to an agent role.
• Acceptance gate — an automated, reproducible behavior test a change must pass to be "done" (agents/definition-of-done.md, docs/14-testing-and-conformance.md).
• Open Question (OQ-n) — a tracked unknown that may block specific tasks until answered.

Testing & conformance

• Behavior-based test — a test asserting observable system behavior (Given/When/Then), not implementation internals; a policy object existing is not proof it enforces (R-TEST-01).
• Reproducible test — deterministic, hermetic, version-pinned, single-command, environment- agnostic; identical pass/fail on any conforming cluster (R-TEST-02).
• Conformance suite — the aggregate, requirement-tagged test set that gates merges and phase exits; green suite = progress (R-TEST-03). See docs/14-testing-and-conformance.md.
• Fault-injection test — a test that breaks something (tunnel down, node killed, bad update) and asserts a fail-closed / no-data-loss outcome; required for safety-critical behavior (R-TEST-05).
• Conformance layers (L0–L3) — L0 static policy and repo checks; L1 offline render checks; L2 behavior on a live cluster; L3 fault injection. See docs/14-testing-and-conformance.md.
• Covered vs. proven — a requirement is covered when an executable test exists for it, and proven only when a recorded run of that test passed at the current revision on the cluster it claims.
• Coverage report — the generated map of every R-* requirement → its verifying test(s); an uncovered requirement is an unmet requirement (R-TEST-04).
• Spec immutability (to agents) — the rule that AI agents may not modify the specifications (docs/, requirements, accepted ADRs, roadmap); they escalate spec problems to the human and never weaken a spec/test to pass (R-TEST-06). Agents edit implementation, tests, and the task board only.