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.
• 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.

The two kinds of VM (do not conflate)

• Infrastructure VM (Layer 1) — a cluster node. In dev/test these are libvirt KVMs; in prod they are bare-metal mini-PCs. Managed by OpenTofu/Ansible, not KubeVirt.
• 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).
• 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; physical WAN selection is largely an edge-router responsibility (OQ-1).
• 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). See docs/04-storage-and-state.md.
• 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).
• Image automation — Flux controllers advancing container image versions per declared policy with no human/AI edit (R-UPD-02).
• Renovate — bot that opens (and auto-merges) chart/manifest version-bump PRs.
• 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) at the Gateway that authenticates a request against Keycloak before forwarding it — used for apps without native OIDC.
• 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 — local KVM cluster; the active build target where everything is proven.
• prod — 3× mini-PC bare-metal cluster; design-only until roadmap Phase 7.
• Overlay — environment-scoped configuration (Kustomize/vars) layered on shared base config; the only thing that differs between dev and prod (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).
• 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.