Skip to content
refplat

Learn: Policy & Admission — reference

A lookup page. The orientation covers the model behind it.

The engine

Section titled “The engine”
  • Kyverno v1.18.1, HA, on the cluster’s admission webhook — evaluates every resource create/update. It layers above the native Pod Security Admission baseline floor: PSA is the backstop, Kyverno expresses what PSA can’t — registry scoping, hostname allow-lists, per-product rules.
  • The policy module holds no team data. Per-product values are derived from the Product registry (fileset + yamldecode) at apply time.

The three verbs

Section titled “The three verbs”
Verb What it does Example policies
validate reject a non-compliant resource at admission disallow-latest-tag, require-requests-limits, require-pod-probes, restrict-image-registries, restrict-images-<env>, require-prod-replica-floor
mutate rewrite the resource on the way in (inject safe defaults) mutate-pod-defaults (drop caps, allowPrivilegeEscalation:false, seccomp:RuntimeDefault, automount off), mutate-workload-labels (team), mutate-topology-spread
generate create a companion resource alongside it generate-workload-pdb (a maxUnavailable:1 PDB per workload)

The policy catalog (shape)

Section titled “The policy catalog (shape)”
  • Baseline (platform-wide, Phase 1): latest-tag, requests/limits, probes, seccomp, privilege-escalation, registry allow-list, default-namespace, wildcard-RBAC, cluster-admin binding, workload naming/labels.
  • Mutate (Phase 2): securityContext + automount defaults, team label, topology spread.
  • Generate: the per-workload PodDisruptionBudget.
  • Per-product (derived, per environment namespace): restrict-images-<team>-<product>-<stage> (only …/team-<team>/<product>-* images) and restrict-route-hostnames-<…> (only the Environment’s hostnames). Owned by the Environment Composition — rendered with the namespace.
  • Supply chain (Phase 3, cosign keyless, Enforce): verify-images-product-<team>-<product> (signed) + verify-attestations-product-<team>-<product> (SBOM + SLSA provenance). Platform-owned, per product.
  • Governance: restrict-environment-control-plane (only platform principals — GitOps/ArgoCD, crossplane-system, and the deployer — may manage XEnvironment/ProviderConfig; environments cannot), restrict-environment-envelope, restrict-over-budget-provisioning.

Full per-cluster catalog + status: kyverno-policy-catalog.md.

Audit-first → Enforce

Section titled “Audit-first → Enforce”
  • Audit: violations recorded as PolicyReports; resource admitted; webhook fails open (failurePolicy: Ignore). This is how you see what would break before it does.
  • Enforce: violations rejected; webhook fails closed (Fail) — the validate.kyverno.svc-fail you see in a rejection. The flip is a deliberate, per-policy step.

Gotchas

Section titled “Gotchas”
  • ⚠️ Enforce/Audit lives in the rule, not the spec. In v1.18 it’s each rule’s validate.failureAction. The top-level spec.validationFailureAction is deprecated and defaults to Audit, so kubectl get clusterpolicy -o …spec.validationFailureAction lies — it shows Audit even where rules Enforce. Read the per-rule field, or just test admission. This asymmetry is a latent fail-open risk on a security control.
  • A per-policy matchConditions doesn’t skip the aggregated webhook. Kyverno serves all policies through one aggregated webhook. To make it ignore a resource you need a global engine matchCondition, not a per-policy one.
  • A generate rule’s match is immutable. You can’t change an existing generate rule’s match in place — add a new rule.
  • Availability policies don’t match Rollout by default. require-prod-replica-floor, generate-workload-pdb, and mutate-topology-spread only match argoproj.io/v1alpha1/Rollout when enable_rollout_kind = true (default off — a Kyverno rule can’t name an absent CRD). Pod-level policies cover Rollout pods automatically via ReplicaSet autogen. See the Delivery reference.
  • The platform exempts itself. System namespaces (kube-system, kyverno, argocd, karpenter, …) are excluded so admission can never block the platform’s own components.

Glossary

Section titled “Glossary”
  • Admission — the API-server checkpoint every resource crosses before storage; where Kyverno runs.
  • ClusterPolicy — a cluster-scoped Kyverno policy (validate / mutate / generate rules).
  • PolicyReport — Kyverno’s per-resource pass/fail record (how Audit surfaces violations).
  • failureAction — per-rule Enforce (reject) vs Audit (record only).
  • PSA (Pod Security Admission) — Kubernetes’ native pod-security tiers; the baseline floor under Kyverno.
  • autogen — Kyverno auto-deriving pod rules for controllers (Deployment→ReplicaSet→Pod), so a pod policy covers workloads without you writing the controller variants.

Go deeper

Section titled “Go deeper”