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`](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`](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).
- **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`](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`](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
- **Coverage state** — whether a target was actually evaluated for vulnerabilities (`scanned`,
  `pending`, `stale`, `failed`, `credential-required`, `by-tag`, `not-covered`). Zero findings means
  something only in `scanned`. See [`docs/17-vulnerability-visibility.md`](docs/17-vulnerability-visibility.md).
- **CVE triage bot** — the scheduled CI workflow that summarises the vulnerability report and asks
  Renovate to open pending updates; it never authors a version change.
- **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`](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`](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).
- **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`](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.