T-0.3 ServiceDefinition schema + renderer contract + examples (R-GITOPS-02)

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
2026-08-16 00:08:30 -05:00
1 parent 253b6600f4
commit eccc13bb3c
@@ -1,3 +1,37 @@
-# catalog
+# catalog — ServiceDefinition entries (the onboarding surface)

-_Placeholder — populated in Phase 0. See ../home-network-k3s (read-only spec)._
+One YAML file per service. Each file is a **ServiceDefinition** conforming to
+[`../schemas/servicedefinition.schema.json`](../schemas/servicedefinition.schema.json). Adding or
+editing a service here is the *only* onboarding step — the platform renders compute, storage, network
+policy, egress, TLS, DNS, monitoring, and update policy from it (see
+[`../schemas/renderer-contract.md`](../schemas/renderer-contract.md)). Serves **R-GITOPS-02**.
+
+**Source of truth for the initial catalog:** spec
+[`docs/13-service-catalog.md`](../../home-network-k3s/docs/13-service-catalog.md) (14-service table +
+SSO/egress/dependency intent).
+
+## Current examples (Phase 0)
+| File | docs/13 row | exposure | egress | auth | Notes |
+|---|---|---|---|---|---|
+| `pihole.yaml` | 6 | internal | internet | forward-auth | admin UI behind oauth2-proxy; config on Longhorn (DR-critical); also platform DNS |
+| `keycloak.yaml` | 0 | public | internet | native | the IdP itself (own admin login + MFA); PostgreSQL on Longhorn; DR-critical |
+
+The remaining catalog services (plex, sonarr, radarr, jackett, seerr, nextcloud, minecraft, unifi,
+semaphore, kasm, gitea, qbittorrent) are onboarded in later phases; they follow the same schema and
+inherit every guarantee automatically.
+
+## Authoring rules
+- Only `name` and `source` are mandatory; every other field defaults to docs/13's default posture
+  (`kind: container`, `exposure: internal`, `egress: internet`, `auth.mode: forward-auth`, stable
+  auto-update, DNS-only default-deny). Set a field only to override the default.
+- Any exposed UI must have an `auth` block: `forward-auth` (default) or `oidc`, each with a non-empty
+  `auth.groups`; `native`/`none` are documented exceptions only.
+- Irreplaceable state (`class: longhorn` configs/DBs) must set `backup.policy` to an off-cluster
+  schedule — never `reacquirable` (R-STATE-03). Only bulk media may be `reacquirable`.
+
+## Validate before commit — single command, no cluster (R-TEST-02)
+```bash
+check-jsonschema --schemafile schemas/servicedefinition.schema.json catalog/*.yaml
+```
+See [`../schemas/README.md`](../schemas/README.md) for install/pinning and a pure-Python fallback.
+This is the L0/L1 schema gate (spec `docs/14`); CI (`.gitea/`) runs it on every change.
@@ -0,0 +1,35 @@
+# ServiceDefinition: keycloak
+# Source of truth: spec docs/13-service-catalog.md row 0; docs/15-identity-and-access.md; ADR-0014.
+# public IdP | egress internet | PostgreSQL on Longhorn (irreplaceable, DR-critical) | auth native.
+# Keycloak IS the IdP (root of trust): its own admin login is local + MFA, so it does not federate.
+# Validates against schemas/servicedefinition.schema.json.
+name: keycloak
+kind: container
+source:
+  image: quay.io/keycloak/keycloak
+exposure: public              # login/redirect flows for internet-exposed services; hardened (docs/15; R-DNS/R-NET)
+egress: internet              # normal WAN egress (docs/03; R-NET-05)
+storage:
+  - name: db
+    size: 10Gi
+    class: longhorn           # PostgreSQL on 3-replica Longhorn; irreplaceable (docs/15, docs/04; R-STATE-02)
+dependencies:
+  - to: keycloak-db           # explicit allow: Keycloak -> its PostgreSQL (docs/13 graph; R-NET-02)
+    port: 5432
+    protocol: tcp
+ingressRoutes:
+  - host: keycloak.home.keithjackson.dev
+    port: 8080                # HTTP listener; TLS terminates at the Gateway (docs/08, docs/09)
+auth:
+  mode: native                # it IS the IdP; own admin login is local + MFA (docs/15; ADR-0014). Documented exception.
+update:
+  channel: stable             # R-UPD-01
+  range: ">=24.0.0"
+  cadence: "0 4 * * *"
+  autoRollbackOnFailedHealth: true   # R-UPD-03
+observability:
+  metrics: true
+  slis:
+    - up                      # IdP down/unhealthy is a critical alert (docs/10; R-OBS-01)
+backup:
+  policy: daily-offcluster    # DR-critical: rebuilds from DB + git realm config (docs/15, docs/04; R-STATE-03)
@@ -0,0 +1,33 @@
+# ServiceDefinition: pihole
+# Source of truth: spec docs/13-service-catalog.md, row 6.
+# internal | egress internet | config on Longhorn (DR-critical config) | auth forward-auth.
+# Also a platform DNS dependency (docs/09). Validates against schemas/servicedefinition.schema.json.
+name: pihole
+kind: container
+source:
+  image: pihole/pihole
+exposure: internal            # LAN-only admin UI (docs/13 row 6; R-DNS/R-NET)
+egress: internet              # normal WAN egress (docs/03; R-NET-05)
+storage:
+  - name: config
+    size: 2Gi
+    class: longhorn           # replicated config state; DR-critical (docs/04 line 118; R-STATE-02/03)
+dependencies: []              # default-deny: reaches only DNS; it PROVIDES DNS (docs/03; R-NET-01/02)
+ingressRoutes:
+  - host: pihole.home.keithjackson.dev
+    port: 80                  # admin web UI, protected at the Gateway by forward-auth (docs/09)
+auth:
+  mode: forward-auth          # oauth2-proxy -> Keycloak; bare UI, no native OIDC (docs/15; R-IDP-02)
+  groups:
+    - platform-admins         # sensitive admin UI: authenticated AND in group (R-IDP-06)
+update:
+  channel: stable             # R-UPD-01
+  range: ">=2024.0.0"
+  cadence: "0 4 * * *"
+  autoRollbackOnFailedHealth: true   # R-UPD-03
+observability:
+  metrics: true
+  slis:
+    - up                      # R-OBS-01
+backup:
+  policy: daily-offcluster    # PiHole config is DR-critical (docs/04 line 118; R-STATE-03)