# 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`](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`](docs/01-architecture-overview.md). - **C2 / Command & Control** — the UI at the root `home.keithjackson.dev`. See [`docs/12-command-center-ui.md`](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`](docs/03-networking-isolation-and-egress.md). - **Exposure class** — how a service is reachable: `internal` (LAN-only) or `public` (edge port-forwarded). - **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`](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`](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`](docs/00-vision-and-scope.md). - **ADR** — Architecture Decision Record; an append-only, superseding-only decision ledger under [`decisions/`](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`](agents/definition-of-done.md), [`docs/14-testing-and-conformance.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`](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.