Phase 0 clarifications: resolve 5 ambiguities surfaced by implementation

- docs/07: correct plaintext-secret enforcement — CI-time ciphertext check vs
  admission SOPS-provenance (Flux decrypts before the API server, so an admitted
  Secret carries no ciphertext; a 'reject plaintext' admission rule is impossible).
- docs/13: add Contract clarifications (v1.1) — source exactly-one-of; longhorn⇒size
  (L0 policy); backup is a {policy} ref; update.channel free-string/stable default;
  auth.groups required for oidc|forward-auth; public⇒auth.mode≠none (schema);
  irreplaceable⇒off-cluster-backup (L0 policy).
- docs/02: Cilium install ownership — Ansible bootstraps, Flux adopts config, value-parity contract.
- docs/03: platform label-key convention (homelab.keithjackson.dev/{egress-class,auth-mode,...}).
- docs/14: ServiceDefinition validation is two complementary L0 gates (JSON Schema shape + Kyverno invariants).

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
This commit is contained in:
jakman85andClaude Opus 4.8 committed 2026-08-16 00:27:24 -05:00
1 parent cc1fb1d3d5
commit 70a98675ac
5 files changed
+49 -1

No files matched your search

+20
View File
@@ -112,6 +112,26 @@ radarr → qbittorrent, jackett
**"…but not limited to":** the catalog is open-ended. New services follow the same ServiceDefinition
and inherit all guarantees automatically — that is the point of the abstraction.
## Contract clarifications (v1.1 — resolved 2026-08-16)
Points the schema left ambiguous, now pinned so the JSON Schema, Kyverno policies, and renderers agree:
- **`source` is exactly-one-of** — `image` for `kind: container`, `vmTemplate` for `kind: vm`
(schema-enforced conditional).
- **`storage[].class: longhorn ⇒ size` is required** — enforced by an **L0 Kyverno policy** (a
replicated volume with no size is a defect). `bulk` size may be omitted (external mount).
- **`backup` is a reference** — `backup: {policy: <ref>}` where `policy` is either the literal
`reacquirable` (bulk/re-acquirable data) or a named off-cluster backup schedule. Cadence/retention
live in the referenced schedule object, **not** inline in the ServiceDefinition.
- **`update.channel` is a free string defaulting to `stable`** — not a closed enum, so the sanctioned
"opt-in to a non-stable channel" (R-UPD-01) is expressible per service.
- **`auth.groups` is required for `auth.mode ∈ {oidc, forward-auth}`** — access must be scoped to at
least one Keycloak group (R-IDP-06); optional for `native`/`none`.
- **`exposure: public ⇒ auth.mode ≠ none`** — a public service may not be unauthenticated
(docs/15, R-IDP-02); **schema-enforced** invariant.
- **Irreplaceable ⇒ off-cluster backup** — DR-critical services MUST NOT be `reacquirable`. This
depends on per-service criticality the schema can't see, so it is enforced by an **L0 Kyverno
policy** keyed on the service's criticality signal, not by the JSON Schema.
## Cross-cutting notes
- **Plex media** is the R-STATE-04 case: keep the metadata DB on replicated Longhorn; keep the large
library on the bulk tier; downloads stage on bulk and are handed off by the arr stack.