home-network-k3s-impl/platform/kyverno/admission/README.md

In-cluster admission enforcement (scaffolding — Phase 2 / T-2.7)

Installs Kyverno and runs the same L0 policies as an in-cluster admission controller, so a non-conforming resource that somehow bypassed CI still cannot be admitted (defense in depth — docs/07, ADR-0011). Not applied in Phase 0 (no cluster exists yet); this is scaffolding wired up in task T-2.7.

Enforcement COMPLEMENTS, never REPLACES, behavior tests

A policy admitting a manifest is not proof the runtime behaves (docs/14 principle 1, R-TEST-01). Kyverno confirms a resource is shaped correctly; it does not prove default-deny actually blocks a packet, that the VPN kill-switch fails closed, or that a PVC survives a rebuild. Those are proven only by the L2/L3 Chainsaw behavior and fault-injection tests (conformance/, ADR-0011), which remain mandatory. Admission is a gate, not a guarantee of behavior.

Authored once, shared

kustomization.yaml references the policy files in ../policies/ verbatim — the identical objects the CI kyverno test gate validates — plus the Kyverno install. No policy is forked between CI and admission, with one deliberate exception:

The one deliberate CI vs admission divergence — Secrets

../policies/disallow-plaintext-secrets.yaml (CI) requires a top-level sops block on the Secret manifest. Flux decrypts SOPS before admission, so that block is gone by the time the API server sees the Secret — the CI policy cannot run in-cluster. The admission equivalent is secret-provenance.yaml, which enforces provenance (Secret came from Flux / is an exempt controller Secret) instead of ciphertext. This is escalated in the T-0.5 report because docs/07's literal wording ("reject a plaintext Secret at admission") is not achievable post-decrypt.

Operational note (from ADR-0011)

Admission enforcement adds a failure mode: a bad policy can block legitimate reconciliation. Mitigations: policies ship with their own kyverno test suite (this directory's ../tests), roll out via GitOps, and the webhook failurePolicy: Fail is chosen so the system fails closed (coordination-protocol.md #8) — validate for bootstrap deadlocks in dev/test before prod.