home-network-k3s-impl/catalog/README.md

catalog — ServiceDefinition entries (the onboarding surface)

One YAML file per service. Each file is a ServiceDefinition conforming to ../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). Serves R-GITOPS-02.

Source of truth for the initial catalog: spec 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)

check-jsonschema --schemafile schemas/servicedefinition.schema.json catalog/*.yaml

See ../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.