jakman85andClaude Opus 5.5
28d0e0a0f2
Record the operator's 2026-11-08 decision to move public HTTP(S) ingress from edge port-forwarding of 80/443 to an outbound-only Cloudflare Tunnel (in-cluster cloudflared, proxied CNAMEs via ExternalDNS). Motivation: the GFiber router cannot hairpin NAT and advertises Google IPv6 DNS via RA, so LAN clients bypass Pi-hole split horizon and fail. Docs 00/01/03/07/08/09/13/14, GLOSSARY and definition-of-done brought into line. R-DNS-01..03 and R-TLS-01..03 wording unchanged. New requirements: R-DNS-04 (no 80/443 forward, resolver-independent LAN reachability), R-DNS-05 (only `public` services at the tunnel; 404 catch-all; no public record for `internal`), R-SEC-04 (Kubernetes API never publicly reachable). Co-Authored-By: Claude Opus 5.5 <[email protected]>
108 lines
7.5 KiB
Markdown
108 lines
7.5 KiB
Markdown
# 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/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`](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.
|