home-network-k3s-impl/decisions/2026-09-30-sd-hardware-capability.md

---

date: 2026-09-30 branch: feat/sd-hardware-capability title: ServiceDefinition gains a hardware capability field — gpu: intel-quicksync renders the /dev/dri wiring, and the enum is what keeps the mechanism swappable

What changed

A new optional top-level ServiceDefinition property, hardware, with one optional member, gpu, whose enum today has exactly one value: intel-quicksync. No catalog entry uses it. This PR delivers the capability; consuming it (Plex) is separate work on top.

• schemas/servicedefinition.schema.json — adds hardware (object, additionalProperties: false, minProperties: 1) with gpu (enum ["intel-quicksync"]). Schema version bumped 1.7.0 → 1.8.0, changelog entry prepended to the schema description per that file's own convention.
• catalog/render.py — three module-level constants (DRI_VOLUME_NAME, DRI_DEVICE_DIR, INTEL_RENDER_GID = 992) and the emission in r_deployment.
• schemas/renderer-contract.md — new ### hardware field-mapping section, plus cross-field invariant 8 in that file's numbered list.
• schemas/README.md — its **Schema version:** line said 1.0.0; it had been stale since 1.1.0. Synced to 1.8.0 and annotated that the schema description is the changelog of record. Added one bullet to "Cross-field rules" for the new enum. That was the whole of the staleness; nothing ballooned.

What the renderer emits for hardware.gpu: intel-quicksync, on the app container / pod spec only (never a sidecar):

1. a hostPath volume dri → /dev/dri, type: DirectoryOrCreate;
2. a read-write volumeMount of dri at /dev/dri on the app container (deliberately not readOnly — VA-API opens the render node read-write);
3. INTEL_RENDER_GID merged into podSecurityContext.supplementalGroups, never clobbering what the SD already declares.

It emits no privileged: true (Kyverno restrict-host-namespaces is Enforce on app namespaces and it is not needed), no nodeSelector (placement is a separate concern with its own justification) and no resource requests (there is no app-container resource render path).

The design decision worth defending: the field is an enum of intent, not a device path. The SD says what class of host device the workload needs; the hostPath, the mount and the GID exist only in catalog/render.py. Migrating to the Intel GPU device plugin (gpu.intel.com/i915 resource requests, no hostPath at all) is then a renderer change with zero catalog edits. Both the schema description and the contract section say this explicitly, because the obvious "simplification" — letting an SD name /dev/dri — would push a platform implementation detail into the operator-facing contract and make that migration a catalog-wide edit.

DirectoryOrCreate is load-bearing. A node that comes back without the render device (rebuild, BIOS change, driver regression, hardware swap) must degrade the workload to software transcoding, not fail the mount: apps-wave-0 is wait: true and apps-wave-1 dependsOn it, so a failed hostPath mount stalls the entire app tier for the sake of a feature that is not load-bearing. /dev is tmpfs, so the empty directory the kubelet creates on such a node leaves nothing durable behind. Do not "tighten" it to Directory. The reasoning is recorded at the emission site.

What I verified

Measured, in this worktree, on this branch:

• python3 catalog/render.py --selftest → render.py selftest: PASS, rc 0. Three new cases were added in the existing check(...) style: the positive (volume + mount + GID, and no privileged/nodeSelector), the negative (an SD without hardware gains no volume, no volumeMount and no securityContext), and the merge case (supplementalGroups: [44] + the field → [44, 992], with fsGroup preserved).

• The self-tests actually bite. I mutated the guard (if hw_gpu == "intel-quicksync": → if True:) in a scratch copy and re-ran: rc 1 with three named failures, including "an SD without hardware must gain no dri volume, no mount and no securityContext". A test that cannot fail is not a test; this one can.

• Re-render is a zero diff. python3 catalog/render.py --all catalog -o apps --wave-layout --no-image-automation then git diff --stat apps/ → empty, and git status --porcelain apps/ → empty (so the two not-onboarded by-products, apps/wave-1/keycloak.yaml and apps/wave-0/vm-demo.yaml, were rewritten byte-identically and needed no revert). The change is inert until a service opts in.

• Schema validity and catalog conformance. Draft202012Validator.check_schema passes; all 12 catalog/*.yaml validate with 0 errors. On the new field specifically: gpu: intel-quicksync accepted; gpu: /dev/dri rejected (enum); hardware: {gpu: …, path: …} rejected (additionalProperties: false); hardware: {} rejected (minProperties: 1).

• Hand-checked the emitted YAML by rendering a throwaway SD carrying hardware, a Longhorn volume and its own podSecurityContext: {runAsUser: 1000, supplementalGroups: [44]}. Result: volumeMounts = config then {name: dri, mountPath: /dev/dri}; securityContext = {runAsUser: 1000, supplementalGroups: [44, 992]}; volumes = the PVC then {name: dri, hostPath: {path: /dev/dri, type: DirectoryOrCreate}}. That toy SD was never written into catalog/.

• GATE: rc 3 — UNDETERMINED, NOT green. Run in the pinned toolbox from this worktree with both CLAUDE.md §3 workarounds (DEV_KUBECONFIG=/dev/null, and an ENGINE shim bind-mounting the main checkout's .git at its own absolute path). Diff base origin/main @ 0fbf544d5e2f … HEAD @ 9f0db1495cfd; touched requirements R-DNS-03 R-GITOPS-02 R-IDP-02. Per stage:

  stage	result
  spec-immutability	SKIPPED — sibling spec repo not at /work/../home-network-k3s. Expected from a worktree; tolerated by §3.
  decisions-log	pass
  lint	pass
  l0	pass
  render-golden	pass — "all 10 onboarded service golden(s) reproduce from the canonical render"
  l1	pass — 3 offline checks, 0 failure(s), 0 skip(s), 0 unwired; coverage 51/51 requirements scaffolded
  approval-policy	pass (event='none', not a pull_request event — N/A locally; it will evaluate for real on the PR)
  gitea-settings	SKIPPED — SETTINGS_API_TOKEN unset. Expected; branch protection and runner registration are therefore UNVERIFIED by this run.
  conformance (L2/L3)	SKIPPED — CLUSTER_AVAILABLE!=true. Phase-0 standing skip.

  The gate's own verdict: "Stages that did not run: spec-immutability gitea-settings". No stage failed, and no stage skipped for a reason caused by this change. rc 3 is reported as rc 3; I am not calling this green.

• Blast radius of the schema change: hardware is absent from every catalog entry, so apply_defaults never materializes it and s.get("hardware") is None on all 12 — which is what the zero diff above demonstrates rather than asserts.

• Touched no sensitive path. Changes are confined to schemas/, catalog/, decisions/; per infra/gitea/approval-policy.json none of those are sensitive. conformance/** and clusters/** are untouched. I did not run --emit-waves (it writes clusters/base/, and the set of files under apps/ did not change).

What I did NOT verify

• Whether a non-privileged pod can actually open() this hostPath char device at all. This is the largest technical risk in the workstream and nobody has tested it. supplementalGroups gets the DAC permission bits right, but containerd installs a device cgroup allow-list per container, and whether /dev/dri/renderD128 reaching the container as a bind-mounted device node is also permitted by that cgroup on this k3s/containerd version is unmeasured. If it is not, the mount will succeed, the group will be present, and the open() will still fail EPERM — and the design would need the device plugin (which sets the cgroup entry) rather than a hostPath. The first real consumer proves or disproves this; nothing in this PR does.
• That a missing device degrades silently — and nothing will tell you. This is the accepted cost of DirectoryOrCreate. The workload will software-transcode and no signal reports it: media apps in this catalog declare no metricsEndpoint, so no ServiceMonitor exists, and there is no metric to alert on. I deliberately did not propose an alert, because an alert that cannot fire is worse than none — see the 2026-09-13 correction in renderer-contract.md §observability, where twelve monitors discovered zero targets. The only proof of hardware transcode is an operator seeing it in the application's own dashboard.
• Whether GID 992 survives a node rebuild. It was measured on all three prod nodes on 2026-09-30 and was identical on each, but render is a systemd dynamic group allocation, not a Debian/LSB static GID. A reinstall that creates system groups in a different order can move it, and nothing in this repo would notice. Recorded in the constant's comment; re-measure getent group render on every node after any rebuild.
• Whether supplementalGroups is the load-bearing mechanism or belt-and-braces. A concurrent agent was checking whether the pms-docker image's 45-plex-hw-transcode-and-connected-tuner init hook resolves the render group dynamically at startup. No finding reached me, so the constant's comment describes the GID and its provenance without claiming which mechanism does the work. Update that comment if the answer arrives.
• Anything on the live cluster. I ran no kubectl. The node facts above (device present, root:render 0660, GID 992, i915 bound, no device plugin, no gpu.intel.com/* advertised) and the Kyverno posture (restrict-host-namespaces Enforce; no hostPath or supplementalGroups restriction; no PSA labels on app namespaces) are prior recon handed to me, not re-measured by me. Per CLAUDE.md §2b, treat them as second-hand until re-queried.
• That CI exercises the self-tests. It does not. git grep -- --selftest ci/ returns nothing — no gate stage invokes the renderer's self-test. They are the executable spec and house style, and I ran them by hand, but a future regression in this code path will not be caught by the gate. Wiring --selftest into a gate stage is a real gap and is not part of this PR (ci/ is a sensitive path and would drag in a human reviewer for a change unrelated to this one).
• Runtime behaviour of any kind. The gate proves the L0/L1 offline subset only; vars.CLUSTER_AVAILABLE is unset, so L2/L3 conformance does not run in CI.