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:
1 parent
cc1fb1d3d5
commit
70a98675ac
5 files changed
+49
-1
No files matched your search
@@ -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.
|
||||
|
||||
Reference in new issue
Block a user