jakman85andClaude Opus 4.8
cbc2301b30
Text-only cleanup after the upgrade campaign. Updates stale version strings, prose, and comments to the verified current facts; no Kubernetes behavior or version pins changed except the kubectl toolchain bump (below). Verified facts applied: k3s v1.36.4+k3s1, Debian 13 trixie, Cilium 1.20.1 / Gateway API v1.6.1, Longhorn 1.12.1, node RAM 24 GiB, dedicated virtio2 SSD etcd disk per node, Velero chart 12.x / v1.18, Grafana 13.2.0. - Version strings across infra/ and platform/ READMEs + comments - kubectl toolchain 1.31.4 -> 1.36.4 (devcontainer/ci/conformance versions.env; 1.31 vs a 1.36 cluster exceeded the +-1 skew) - Retired-single-apps-Kustomization refs -> apps-wave-0/1/2 + apps-vms with per-wave SOPS decryption (flux/clusters docs + bootstrap.sh) - COMPLETED/historical banners on the three executed plan docs - Resolved TODO(WS-SEC) markers -> Renovate-maintained ranges - Appended dated DECISIONS-LOG entry (2026-08-30) superseding the 2026-08-26 LIVE STATE line Left as revalidation items (not blind-edited): external-snapshotter v8.2.0 vs 1.36, Cilium ext_authz/forward-auth relevance under 1.20.1, conformance ImageVolume feature-gate assertions under 1.36. Co-Authored-By: Claude Opus 4.8 <[email protected]>
64 lines
4.0 KiB
Markdown
64 lines
4.0 KiB
Markdown
# catalog — ServiceDefinition entries (the onboarding surface)
|
|
|
|
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
|
|
| 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.
|
|
|
|
## Rendering — `render.py` (the ServiceDefinition renderer, T-0.3)
|
|
[`render.py`](./render.py) compiles a ServiceDefinition into the concrete manifest set defined
|
|
by [`../schemas/renderer-contract.md`](../schemas/renderer-contract.md): a Namespace (with the
|
|
`app-namespace`/`gateway-access` labels), the default-deny baseline (R-NET-01), a
|
|
Deployment+Service **or** a KubeVirt VirtualMachine + CDI DataVolume (R-PLAT-02/03), PVCs
|
|
(R-STATE), one CiliumNetworkPolicy egress-allow per `dependency` (R-NET-02), the
|
|
`egress-class` steering label (R-NET-05), HTTPRoute(s) on the shared Gateway (R-TLS/R-DNS),
|
|
ServiceMonitor + SLI alerts (R-OBS-01), the Flux ImageRepository/ImagePolicy update plumbing
|
|
(R-UPD), and the auth-mode / backup wiring hints (R-IDP/R-STATE-03).
|
|
|
|
```bash
|
|
python3 catalog/render.py catalog/pihole.yaml # render one SD to stdout
|
|
python3 catalog/render.py --all catalog -o out/ # render every SD to out/<name>.yaml
|
|
python3 catalog/render.py --selftest # deterministic self-test (no cluster)
|
|
```
|
|
|
|
- **Deterministic:** identical input → byte-identical output (golden-diffable). The L1 render
|
|
conformance tests (`conformance/tests/l1-rendering/*`) diff the output against committed
|
|
goldens — run offline by `conformance/run.sh --layer l1` and `ci/l1.sh` (no cluster).
|
|
- **How CI/Flux consume it:** CI invokes `render.py` in the L1 stage; a GitOps flow renders
|
|
`--all catalog -o <rendered-dir>` and Flux reconciles the rendered directory. Design choice
|
|
(renderer-contract is silent on mechanism): a render-then-consume script is the simplest
|
|
reproducible option — see the header of `render.py`.
|
|
- **Dependency:** PyYAML (the renderer's single dependency; the conformance harness stays
|
|
stdlib-only and only shells out to this script + diffs text).
|