Policy: one engine, reports before gates¶
Cluster-wide Policy as Code. Every rule this directory ships is written as if it
were enforcing, and every rule currently runs in Audit — violations become
reports, not rejections. Promotion to Enforce is a deliberate later step
(ADR-012 Phase 3), so the
inventory can be corrected before a policy can break a deploy.
Enforcement is consolidated on Kyverno. Pod Security Admission is deactivated by
removing its label, and a namespace declares its Pod Security Standards level
through the Kyverno-only key kensan-lab.platform/pss-level — reusing PSA's own
label key would switch PSA back on.
Components¶
| Directory | Role |
|---|---|
kyverno/ |
The admission and background-scan engine (Helm chart, Argo CD app kyverno) |
kyverno-policies/ |
The ClusterPolicy set and its exceptions (raw manifests, Argo CD app kyverno-policies) |
kyverno-policies/exceptions/ |
PolicyException objects. Accepted only from the kyverno namespace, so Git is the only way to grant one |
namespace.yaml |
The kyverno namespace, itself held to enforce: baseline |
Policy set¶
| ClusterPolicy | What it asserts | Action |
|---|---|---|
pss-baseline |
The floor. Pod Security Standards baseline across the cluster | Audit |
pss-restricted |
Opt-in. PSS restricted for namespaces that declare it | Audit |
ns-label-contract |
Namespaces carry the base labels, apps carry the three-axis labels, and only tier=platform may declare pss-level: privileged |
Audit |
disallow-latest-tag |
Images carry an explicit, immutable tag | Audit |
require-requests |
Every container sets resources.requests.cpu and .memory |
Audit |
The exception set is deliberately small: node-exporter needs host namespaces
and ports to read node metrics, so that one DaemonSet is exempted from
pss-baseline rather than marking the whole monitoring namespace privileged.
How a violation surfaces¶
flowchart LR
APPLY["kubectl / Argo CD<br/>applies a resource"] --> ADM["Kyverno admission<br/>webhook"]
ADM -->|Audit: always admits| API["Kubernetes API"]
SCAN["Background scan<br/>every 1h"] --> API
ADM -.->|admissionReports disabled| X["(no EphemeralReport)"]
SCAN --> PR["PolicyReport<br/>per namespace"]
PR --> OPS["kubectl get polr -A<br/>Grafana / review"]
Admission still evaluates every request, but writes no report for it. The visible record comes from the hourly background scan alone.
Design rationale¶
- One engine, not two. PSA and Kyverno both enforcing PSS meant a workload
could be blocked by a layer that had no per-workload exception mechanism.
Kyverno has
PolicyException; PSA does not. See ADR-012. admissionReports: falseprotects the control plane. Writing anEphemeralReportper admission is a write per apply against etcd on a microSD card. Reporting is routed entirely through the background scan instead.- The scan interval is pinned, not defaulted.
backgroundScanInterval: 1his written out so a chart bump cannot change it silently — the lesson of ADR-011. - Only
validatereporting is on.mutate,generate, andimageVerifyare unused, and their reporting is disabled rather than left at the default. - Exceptions live in Git.
policyExceptions.namespace: kyvernomeans an exception applied anywhere else is ignored, so the exception inventory cannot drift away from the repository.
Related¶
- Deep dive, policy inventory, and operations: docs/architecture/policy-enforcement.md
- Decision record: ADR-012
- Namespace and label contract: ADR-014 · docs/architecture/namespace-label-design.md