home-network-k3s-impl/schemas/renderer-contract.md

# Renderer Contract — ServiceDefinition → rendered resources

**Status:** authoritative Phase-0 interface contract. **Consumed by** the manifest renderer
(WS-GITOPS), the network/egress renderer (WS-NET), storage (WS-STATE), TLS/DNS (WS-EDGE), identity
(WS-SEC), observability (WS-OBS), updates (WS-UPD), and the conformance/policy/CI agents (WS-TEST).

**Source of truth:** spec [`docs/13-service-catalog.md`](../../home-network-k3s/docs/13-service-catalog.md)
(the ServiceDefinition schema and default posture). This document maps each field of
[`servicedefinition.schema.json`](./servicedefinition.schema.json) to the concrete resources the
platform must render, and cites the requirement each mapping satisfies. Changing this contract is an
**interface change** — coordinate per the spec's `agents/coordination-protocol.md` (§2).

> The renderer MUST first materialize the schema **defaults** (below), then apply this mapping. A
> field absent from a ServiceDefinition renders from its default posture, not "not at all."

## Default posture (applied before mapping) — docs/13 §"Default posture"
| Field | Default | Requirement |
|---|---|---|
| `kind` | `container` | R-PLAT-02/03 |
| `exposure` | `internal` | R-DNS/R-NET |
| `egress` | `internet` | R-NET-05 |
| `storage` | `[]` (config PVC still expected for stateful svc) | R-STATE-02 |
| `dependencies` | `[]` → reaches **only DNS** (default-deny) | R-NET-01 |
| `inClusterClients` | `[]` → no direct east-west client; only the Gateway may reach an exposed port | R-NET-01/02 |
| `auth.mode` | `forward-auth` for any exposed UI | R-IDP-02 |
| `update.channel` | `stable` | R-UPD-01 |
| `update.autoRollbackOnFailedHealth` | `true` | R-UPD-03 |
| `observability.metrics` | `true` | R-OBS-01 |
| `observability.metricsEndpoint` | **absent** → the workload serves no Prometheus endpoint; no ServiceMonitor | R-OBS-01 |
| `observability.livenessWorkload` | the object this SD renders (`Deployment` named after the service; `VirtualMachineInstance` for `kind: vm`) | R-OBS-01 |
| backup of irreplaceable state | off-cluster (never `reacquirable`) | R-STATE-03 |

---

## Field → resource mapping

### `name`
- **Renders:** the service Namespace (trust zone), Deployment/VM name, Service name, and the DNS label
  `<name>.home.keithjackson.dev`.
- **Requirements:** R-DNS-01 (naming model, docs/09), R-NET (namespace = isolation boundary, docs/03).

### `kind` + `source`
- `container` + `source.image` → **Deployment** (+ Service) using the image ref.
- `vm` + `source.vmTemplate` → **KubeVirt VirtualMachine** with a **CDI**-imported root disk.
- The schema enforces exactly-one-of (`image` for container, `vmTemplate` for vm).
- **Requirements:** R-PLAT-02/03 (PaaS/IaaS, docs/13); VM disks inherit Longhorn durability (docs/04).

### `exposure` (`internal` | `public`)
- Both classes render an **HTTPRoute** on the shared Gateway and are reachable on the LAN via internal
  split-horizon DNS.
- `public` **additionally** signals the documented **manual edge port-forward** of 80/443 (and any
  service-specific port, e.g. Plex 32400, Minecraft 25565) to the ingress VIP, and a **public**
  ExternalDNS record for `<name>.home.keithjackson.dev`.
- `internal` renders **no public DNS record** and is never port-forwarded (PiHole resolves it to the
  internal Gateway VIP).
- **HOW "no public DNS record" IS MADE TRUE, since it was prose only until 2026-09-14.** Every
  HTTPRoute rendered for an `internal` service carries ExternalDNS's own controller annotation with
  a value other than the one ExternalDNS claims:

      external-dns.alpha.kubernetes.io/controller: none

  ExternalDNS v0.21.0 (`source/annotations/processors.go`) skips any source object whose
  `controller` annotation is present and `!= "dns-controller"`, and `source/gateway.go` applies that
  check **inside `Endpoints()` before any hostname is resolved** — so the route never becomes an
  endpoint for any name it declares. `source/service.go` applies the identical check, which covers
  the second configured source. It is derived **from `exposure` and nothing else**
  (`catalog/render.py` `_externaldns_route_annotations`), so the operator's one declaration decides,
  a service that OMITS `exposure` inherits the `internal` default and is likewise unpublishable, and
  there is no per-service list to forget to extend. `ci/render-golden.sh` proves `apps/` reproduces
  from `catalog/`, so an `internal` service cannot exist in the applied tree without it, and
  `conformance/tests/l0-static/internal-services-publish-no-public-dns` re-proves both directions
  (present on internal, **absent** on public) on every gate run.
  - The route itself, the wildcard TLS and LAN reachability are **unchanged** — only the public
    record is withdrawn. The internal split-horizon answer is Pi-hole's job (R-DNS-03), which is why
    withdrawing these records requires Pi-hole to be answering the LAN authoritatively first: the
    zone has no `*.home.keithjackson.dev` wildcard, and `*.keithjackson.dev` does not match two
    labels, so a withdrawn name is a public NXDOMAIN with no fallback.
  - Why not a cluster-wide ExternalDNS opt-in filter (`labelFilter`, which v0.21.0 supports for
    both configured sources): seven published names come from hand-authored `platform/`/`apps/`
    manifests that carry no `exposure` field for a renderer to read, and an opt-in filter deletes
    all seven the moment it is set. Per-resource exclusion has exactly the blast radius of the
    defect. The filter stays available as hardening once those seven are adjudicated — see
    `platform/externaldns/helmrelease.yaml` and the register in the L0 check.
- `public` renders the record but the renderer does **not** yet set a target: the record still
  resolves to the shared Gateway VIP, i.e. an RFC1918 address, so a `public` service is not in fact
  publicly reachable. Fixing that is **not** a renderer change on v0.21.0 —
  `source/gateway.go` reads `external-dns.alpha.kubernetes.io/target` only from the **Gateway** (and
  a ListenerSet), never from an HTTPRoute, so a per-service target override is not expressible while
  the public services share the `shared` Gateway. The open decision is recorded in
  `platform/externaldns/helmrelease.yaml`.
- Exposure does **not** relax east-west default-deny (docs/09 §"Interaction with default-deny").
- **Requirements:** R-DNS-02/03 (docs/09), R-NET-04 (docs/03).

### `egress` (`internet` | `vpn`) — egress steering
- `internet` → pod egress allow to the default WAN route (node → SOHO edge → internet).
- `vpn` → the pod is **steered through the shared in-cluster Gluetun/PIA (WireGuard) egress gateway**
  (Cilium Egress Gateway / routing). The pod gets **no independent egress path**; the
  **kill-switch (fail-closed)** and allow rules are enforced at the gateway + namespace/policy level,
  **outside** the workload.
- **Requirements:** **R-NET-05** (egress class), **R-NET-06** (VPN kill-switch, mandatory & central).
  VPN-class set is normative: sonarr, radarr, jackett, qbittorrent (docs/03/13).

### `dependencies[]` (`to` / `port` / `protocol`) — east-west policy
- Each namespace first gets the **default-deny baseline** (deny all ingress + egress) applied by
  GitOps at namespace creation, with a standing allow only for **DNS to the in-cluster resolver**.
  **Observability scraping is NOT in the baseline** — it is an additive allow rendered per declared
  `observability.metricsEndpoint` (see below), scoped to that one port. This paragraph used to claim
  the baseline carried a standing monitoring allow; it never did, and an app metrics port would have
  been dropped by policy even with the Service port and monitor endpoint in agreement.
- Each `dependencies[]` entry renders one **CiliumNetworkPolicy** egress allow: this service → `to`
  service on `port`/`protocol`. Everything undeclared stays denied.
- Empty `dependencies` ⇒ the service can reach **only DNS**.
- **Requirements:** **R-NET-01** (default-deny baseline), **R-NET-02** (explicit allow / deny
  undeclared). Auditable via Hubble (R-SEC-03, R-OBS-04).

### `storage[]` (`name` / `size` / `class` / `mountPath` / `export` / `subPath` / `readOnly`) — PVs + PVCs
- `class: longhorn` → a **PVC** on the 3-replica Longhorn StorageClass sized by `size` (replicated
  config/DB/app state), `ReadWriteOnce`, dynamically provisioned. For a `vm`, the disk is a Longhorn
  volume via CDI.
- `class: bulk` → a **static, pre-bound external NFS PersistentVolume _and_ its PVC**. The entry's
  `export` is the absolute path on the bulk server; the SERVER is never named in a ServiceDefinition
  — it is the `${BULK_NFS_SERVER}` cluster-vars knob, so one authored definition promotes across
  environments that reach the same storage by different addresses (**R-ENV-02**). Not 3× replicated:
  durability is the storage host's ZFS pool, not Longhorn.
  - `storageClassName: ""` on **both** PV and PVC (explicitly empty ⇒ statically provisioned; no
    provisioner is ever asked to create anything, and the default-StorageClass annotation is
    suppressed). Deliberately NOT the `bulk` StorageClass: a StorageClass `provisioner` is
    **immutable**, so re-pointing that stub would make Flux fail permanently on it.
  - Binding is pinned from both ends — `claimRef` on the PV, `volumeName` on the PVC — so no other
    claim of matching size/mode can win a race for the volume.
  - `persistentVolumeReclaimPolicy: Retain`, always. Bulk data pre-exists the cluster, is far larger
    than the cluster, and may have consumers outside it; nothing here may reclaim it.
  - Access mode follows the read/write posture and is always `…Many`, because one export is
    consumed by several namespaces and several nodes at once: `ReadOnlyMany` when `readOnly`,
    `ReadWriteMany` otherwise. `ReadWriteOnce` cannot express either.
  - `mountOptions` are a **platform** decision held in the renderer, not a per-service field:
    `nfsvers=4.1,hard,noatime,timeo=600,retrans=2`. NFSv4 carries mount and lock in-protocol, so
    the only port that must be reachable is **tcp/2049** — no rpcbind/111, mountd or statd, which is
    what keeps the firewall surface to a single rule. `hard` is chosen over `soft` because a soft
    mount converts a server hiccup into a short read handed to the application.
  - `size` on a bulk entry is the PV's **advertised capacity and nothing more** — no component
    enforces it (the ZFS pool is the real limit), so it should state the dataset's actual size so
    `kubectl get pv` reports something true.
  - **fsGroup does not apply.** The in-tree NFS volume plugin performs no ownership management, so
    `podSecurityContext.fsGroup` is a **no-op** on a bulk volume. A bulk mount that must be written
    therefore requires the container's own uid/gid to be one the export's ownership permits (e.g.
    Plex's `PLEX_UID`/`PLEX_GID`, LinuxServer images' `PUID`/`PGID`) — or a server-side squash. A
    mount that succeeds but cannot write is the characteristic failure of this tier.
- `mountPath` (any class) overrides the `/data/<name>` default verbatim.
- `subPath` (any class) mounts a subtree instead of the volume root. **Two `subPath` mounts of one
  export are two separate mounts**, so `link()` between them fails `EXDEV`; a workload that needs
  hardlinks or atomic moves between two directories (Sonarr/Radarr importing from a download path
  into a library) must mount their common ancestor **once** instead.
- `readOnly` (any class) marks the volumeMount read-only, and on a bulk entry also sets the PV's
  `nfs.readOnly` so the kernel mount really is `ro`. Note this is a **client-side** guarantee: one
  export serving both a reader and a writer that may land on any node cannot distinguish them
  server-side.
- State separation rule: anything that must survive a rebuild lives on a named volume here, never on
  ephemeral fs/hostPath — so the workload can be destroyed and re-applied from git with data intact.
- **Requirements:** **R-STATE-01** (rebuild survival), **R-STATE-02** (Longhorn replication),
  **R-STATE-04** (bulk tier). (docs/04)

### `ingressRoutes[]` (`host` / `port`) — HTTPRoute + Certificate + DNS
- Each entry renders an **HTTPRoute** attaching `host` → the service `port` on the shared Gateway.
- TLS: the Gateway terminates with the cert-manager **wildcard `*.home.keithjackson.dev`** certificate
  (Let's Encrypt via **DNS-01**, scoped Cloudflare token), so no per-service cert step — trusted,
  non-self-signed, auto-renewed, including for `internal` services. Per-service `Certificate` only
  where isolation warrants.
- DNS: **ExternalDNS** watches the HTTPRoute and manages the `<host>` record — but **only for a
  `public` service**. An `internal` service's route is rendered with ExternalDNS's controller
  annotation set to `none`, which removes it from ExternalDNS's view entirely (see §`exposure`), so
  its `<host>` exists **only** in the internal split-horizon answer PiHole serves, never in the
  public zone. A `public` record's TARGET is still the Gateway VIP, not a routable address — open
  operator decision, see §`exposure`.
- The `host` pattern is enforced to `<label>.home.keithjackson.dev` by the schema.
- **Requirements:** **R-TLS-01/02/03** (docs/08), **R-DNS-01/02/03** (docs/09).

### `inClusterClients[]` (`namespace` / `port` / `protocol` / `name`) — direct east-west clients
- Each entry renders ONE **CiliumNetworkPolicy** ingress allow on this service:
  `endpointSelector` = this service, `fromEndpoints` matching **only** the reserved
  `k8s:io.kubernetes.pod.namespace: <namespace>` label, `toPorts` carrying **only** the declared
  `port`/`protocol`. Name: `<service>-allow-<name>-ingress`, `name` defaulting to `namespace`.
- **Why the field exists.** `ingressRoutes` opens the **north-south** path only (the gateway allow
  admits `fromEntities: [ingress]`, the Gateway proxy identity, and nothing else), and
  `dependencies` compiles edges **only between catalog services** — both halves come from a catalog
  entry's own declaration. A **platform controller** that dials this service's ClusterIP directly
  was therefore unauthorable, and under default-deny it is dropped. Prod hit exactly that: its
  `GitRepository` points at the in-cluster Gitea Service
  (`http://gitea.gitea.svc.cluster.local:3000/...`, clusters/prod/kustomization.yaml) so GitOps
  depends on no public DNS/Cloudflare/Gateway/`${BASE_DOMAIN}`, but `flux-system`'s
  source-controller was denied — and the HTTPRoute that would have served a public name lives in a
  **downstream** tier that cannot apply while the source is down (source down → routes never rename
  → source stays down).
- **Least privilege is part of the contract:** a namespace and a port, never `fromEntities: all`,
  never a port-less allow. The client is selected by **namespace** rather than pod labels because an
  upstream controller's labels are its chart's to change, not this platform's contract — so name a
  platform-controller namespace whose entire membership may hold that reach, never a shared one.
- **Additive, and not a dependency:** the namespace default-deny baseline is unchanged
  (`ingress: []`), every undeclared source/port stays denied, and the entry creates **no wave
  ordering edge** — the client is a platform component, not a catalog service.
- **Requirements:** **R-NET-01** (default-deny baseline stands), **R-NET-02** (explicit allow / deny
  undeclared), **R-GITOPS-02** (the allowance is authored in the one reviewable object rather than
  surviving as a live-applied cluster object). Auditable via Hubble (R-SEC-03, R-OBS-04).

### `auth` (`mode` / `groups[]`) — identity integration (Keycloak / oauth2-proxy)
- `oidc` → register the app as a **Keycloak OIDC client** (declarative realm/client config, GitOps;
  client secret SOPS-encrypted). App does its own login redirect.
- `forward-auth` → protect the service's `ingressRoutes` at the **Gateway** with **oauth2-proxy →
  Keycloak** so auth happens before traffic reaches the app (bare UIs without usable OIDC).
- `native` → no platform SSO wiring; app owns its auth (documented exception, e.g. Plex/Seerr; and
  Keycloak **itself** as the IdP, admin login local + MFA).
- `none` → no auth wiring (internal-only, discouraged).
- `groups[]` → the Keycloak groups permitted access, enforced by the OIDC client mappers /
  oauth2-proxy `allowed_groups`. **Schema requires ≥1 group for `oidc`/`forward-auth`** — access is
  "in an authorized group," not merely "logged in."
- Keycloak, oauth2-proxy, and app→Keycloak / proxy→Keycloak / Keycloak→DB flows are ordinary
  workloads under default-deny with explicit allows (ties back to `dependencies`).
- **Requirements:** **R-IDP-02** (protect OIDC-capable and bare UIs), **R-IDP-06** (group-based
  authorization). (docs/15, ADR-0014)

### `update` (`channel` / `range` / `cadence` / `autoRollbackOnFailedHealth` / `pin`)
- container `kind` → a Flux **ImagePolicy** (+ ImageRepository) encoding `channel`/`range`; Flux
  image-automation advances the running version on its scan interval (`cadence`). `pin` freezes the
  service (stops automation). No human/AI edits a tag.
- `vm` `kind` → in-guest unattended package updates on `cadence` (cloud-init), per docs/11 §3.
- `autoRollbackOnFailedHealth: true` → health-gated rollout that reverts on failed health and alerts.
- **Requirements:** **R-UPD-01** (stable only), **R-UPD-02** (no human/AI authoring), **R-UPD-03**
  (health-gated auto-rollback). (docs/11, ADR-0009)

### `observability` (`metrics` / `slis[]` / `metricsEndpoint` / `livenessWorkload`) — ServiceMonitor + alerts
- `metrics: true` → the platform **collects signals** for this service: logs to Loki via the node
  agent, and kube-state-metrics readiness for the `up` SLI below. Both are platform-wide scrapes;
  neither needs a per-service CR. **It does not assert that the workload serves a Prometheus
  endpoint.** *(Corrected 2026-09-13. It used to render a ServiceMonitor unconditionally, hardcoded
  to a Service port named `metrics`. No rendered Service ever defined such a port, so all twelve app
  monitors discovered ZERO targets — verified on prod: 24 jobs in `up`, not one of the twelve — and
  every `up{job=...}` SLI built on them was structurally inert. `metrics: true` could not have been
  right: Plex, Pi-hole, Jackett, qBittorrent, Sonarr, Radarr, Seerr, Semaphore and Nextcloud serve no
  Prometheus endpoint at all without a separate exporter.)*
- `metricsEndpoint: {port, name?, path?, interval?}` → **the workload does serve metrics, here.**
  Renders all three halves of a working scrape from the one declaration, because any one of them
  missing makes the scrape silently yield nothing:
  1. a **named Service port** (`name`, default `metrics`) on that `port`;
  2. a **ServiceMonitor** endpoint selecting that port name, on `path` at `interval`;
  3. a **CiliumNetworkPolicy** admitting the `monitoring` namespace to that port — the namespace
     default-deny baseline is `ingress: []`, so without it the scrape is dropped by policy.
  The metrics port is deliberately **not** added to the Gateway ingress allow: it is east-west for
  Prometheus, never north-south.
- each entry in `slis[]` → at least one **alert rule** routed by Alertmanager to email; a per-service
  Grafana dashboard row. `up` → a `<name>-down` **critical** alert reading the readiness of
  `livenessWorkload` from **kube-state-metrics** (`kube_deployment_status_replicas_available`,
  `kube_statefulset_status_replicas_ready`, `kube_daemonset_status_number_available`) or, for a
  `VirtualMachineInstance`, the existence of `kubevirt_vmi_info{phase="running"}`. Each rule carries
  an `or absent(...)` half, so the signal DISAPPEARING fires the alert rather than silencing it.
- `livenessWorkload: {kind, name}` → which object's readiness **is** this service. Defaults to the
  object this SD renders; override it when the running workload is a different one (keycloak's server
  is a StatefulSet owned by the Keycloak operator — a Deployment-shaped rule would `absent()` and
  fire forever).
- **Requirements:** **R-OBS-01** (per-service SLIs/alerts). Platform-health alerts (R-OBS-04) are
  rendered platform-wide, not per ServiceDefinition. (docs/10)

### `backup` (`policy`)
- a schedule ref (e.g. `daily-offcluster`) → **Velero + Longhorn** off-cluster backup schedule for
  this service's volumes/namespace.
- literal `reacquirable` → **no** 1:1 backup (bulk media only). **Irreplaceable** state (configs, DBs,
  Nextcloud, Gitea, PiHole config, Keycloak DB) MUST NOT be `reacquirable`.
- **Requirements:** **R-STATE-03** (off-cluster DR backup). (docs/04)

---

## Cross-field invariants the renderer / L0-L1 tests rely on
1. **kind ↔ source:** container⇒`image`, vm⇒`vmTemplate` (schema-enforced).
2. **auth ↔ groups:** `oidc`/`forward-auth` ⇒ non-empty `groups` (schema-enforced; R-IDP-06).
3. **default-deny is unconditional:** every namespace gets the deny baseline regardless of
   `dependencies`; `dependencies` only *adds* allows (R-NET-01/02). The same holds for
   `inClusterClients`: it adds one namespace+port ingress allow and never relaxes the baseline.
4. **egress is enforced outside the workload:** `vpn` renders gateway steering + kill-switch, never a
   per-service sidecar the app could bypass (R-NET-05/06).
5. **TLS is never self-signed and needs no per-service step:** the wildcard Gateway cert covers every
   `ingressRoutes.host`, `internal` included (R-TLS-01/03).
6. **irreplaceable ⇒ off-cluster backup:** DR-critical services must not carry `backup.policy:
   reacquirable` (R-STATE-03). *(Advisory: not enforced by the schema — an L0 policy check should
   assert it; see "Ambiguities / escalations" in schemas/README.md.)*
7. **`exposure: internal` ⇒ no public DNS record, structurally.** Every HTTPRoute rendered for an
   `internal` service (including one that omits `exposure` and takes the default) carries
   `external-dns.alpha.kubernetes.io/controller: none`, and no `public` service's route carries it.
   Derived from `exposure` alone; enforced on every gate run by
   `conformance/tests/l0-static/internal-services-publish-no-public-dns` (R-DNS-03).

## Requirement traceability (contract-level)
Primary **R-GITOPS-02** (single reviewable object wires every requirement). Field-level: R-NET-01/02
(dependencies, inClusterClients), R-NET-05/06 (egress), R-STATE-01/02/04 (storage), R-STATE-03 (backup),
R-TLS-01/02/03 + R-DNS-01/02/03 (ingressRoutes + exposure), R-OBS-01 (observability),
R-UPD-01/02/03 (update), R-IDP-02/06 (auth), R-PLAT-02/03 (kind/source).