OnCallReadyStart learning

Security and secrets Lesson 23.27 · Kubernetes Security (CKS) · 15 min read

Kyverno 1.19: validate, mutate, and read the PolicyReports

In plain words

A new house rule is easier to introduce if you first walk around and write down who already breaks it, give them time to fix things, and only then lock the door. Kyverno does exactly that for cluster rules: in Audit it notes every violation in a report, and once the list is empty you switch it to Deny. It can also hand everyone a sensible default, like a seatbelt already fastened.

A policy engine you can roll out safely

The problem. A ValidatingAdmissionPolicy (previous lesson) checks one request at a time. It cannot tell you which of the 400 pods already running would fail a new rule, and it cannot fix a request, only refuse it. Turning a strict rule on blind breaks deploys. Kyverno adds the two missing pieces: reports on what already exists, and mutation that sets safe defaults.

Kyverno 1.19 (August 2026) writes policies in CEL, in the policies.kyverno.io/v1 group: ValidatingPolicy (vpol), MutatingPolicy (mpol), ImageValidatingPolicy (ivpol, the supply chain lesson). Its four controllers run in namespace kyverno:

$ kubectl get pods -n kyverno
NAME                                             READY   STATUS    RESTARTS   AGE
kyverno-admission-controller-46nc7htkpg-6qq82    1/1     Running   0          64s
kyverno-background-controller-vws4mqqf8d-cf592   1/1     Running   0          64s
kyverno-cleanup-controller-ppjqcqj2k6-gxgjf      1/1     Running   0          64s
kyverno-reports-controller-xl6blzwp9m-qlgbd      1/1     Running   0          64s

Validate: start in Audit

A ValidatingPolicy looks like the built-in policy, without a separate binding: validationActions sits in the policy itself. Audit admits everything and records the result; Deny refuses; Warn admits with a warning.

apiVersion: policies.kyverno.io/v1
kind: ValidatingPolicy
metadata:
  name: disallow-latest-tag
spec:
  validationActions: [Audit]
  matchConstraints:
    resourceRules:
    - apiGroups: ['']
      apiVersions: [v1]
      operations: [CREATE, UPDATE]
      resources: [pods]
  validations:
  - expression: >-
      object.spec.containers.all(c,
        c.image.contains(':') && !c.image.endsWith(':latest'))
    message: 'An image tag is required, and it must not be latest.'

Read the reports. The reports controller evaluates the policy against everything that already runs and writes one PolicyReport per resource, named by the resource's uid:

$ kubectl get polr -n shop
NAME                                   KIND         NAME                   PASS   FAIL   WARN   ERROR   SKIP   AGE
2160cc8d-33e7-4816-aadd-86f7c4d940af   Deployment   api                    1      0      0      0       0      0s
2329466d-13a9-42cd-bbe8-378af6bf74ba   Pod          web-t944brwrs8-z8qrp   0      1      0      0       0      0s
49c091e6-7850-4e12-bb2c-c53856b66d28   Pod          debug                  0      1      0      0       0      0s
cb6384b8-3d4a-4ee6-9ab2-2491e8be2f66   Pod          api-rtqpztxcnh-r9crn   1      0      0      0       0      0s
eb22aaf5-2512-4cf5-924f-ab6534aadacb   Deployment   web                    0      1      0      0       0      0s

The policy names pods, yet the Deployments have reports too: Kyverno's autogen writes the same rules for the pod controllers (Deployments, StatefulSets, DaemonSets, Jobs, CronJobs) against their pod template - object.spec becomes object.spec.template.spec - and lists them in the policy's status.autogen.configs. They report and deny under the policy's own name. spec.autogen.podControllers.controllers narrows the list; an empty list turns autogen off.

kubectl get polr <name> -n shop -o yaml shows why, one entry per policy:

results:
- message: An image tag is required, and it must not be latest.
  policy: disallow-latest-tag
  result: fail
  scored: true
  source: KyvernoValidatingPolicy

Fix the FAILs (here: web runs nginx:latest, debug runs busybox without a tag), and only then switch to [Deny]. Now a bad request is refused, and the message names the policy:

$ kubectl run test -n shop --image=nginx:latest
Error from server: admission webhook "vpol.validate.kyverno.svc-fail" denied the request: Policy
disallow-latest-tag failed: An image tag is required, and it must not be latest.

Thanks to autogen, kubectl create deployment test -n shop --image=nginx:latest gets the same denial at the Deployment itself, instead of a Deployment whose ReplicaSet can never create its pods.

Several failing policies are joined in one message with ; . A CEL runtime error (reading a field that is not there, object.metadata.labels.team on a pod without labels) is reported as Policy <name> error: no such key: ... and, with the default failurePolicy: Fail, also denies. Guard optional fields with has() or the optional form object.metadata.?labels.team.orValue('').

Mutate: set the safe default

A MutatingPolicy changes the request before it is stored. patchType: ApplyConfiguration merges an object you build in CEL into the request; matchConditions limit it to requests that need it:

apiVersion: policies.kyverno.io/v1
kind: MutatingPolicy
metadata:
  name: default-seccomp
spec:
  matchConstraints:
    resourceRules:
    - apiGroups: ['']
      apiVersions: [v1]
      operations: [CREATE]
      resources: [pods]
  matchConditions:
  - name: no-seccomp-yet
    expression: "!has(object.spec.securityContext) || !has(object.spec.securityContext.seccompProfile)"
  mutations:
  - patchType: ApplyConfiguration
    applyConfiguration:
      expression: >-
        Object{
          spec: Object.spec{
            securityContext: Object.spec.securityContext{
              seccompProfile: Object.spec.securityContext.seccompProfile{
                type: "RuntimeDefault"
              }
            }
          }
        }
$ kubectl run cache -n shop --image=redis:8
pod/cache created
$ kubectl get pod cache -n shop -o jsonpath='{.spec.securityContext}'
{"seccompProfile":{"type":"RuntimeDefault"}}

Mutation runs before validation, so a policy can add what another one requires. patchType: JSONPatch is the other form: a list of JSONPatch{op, path, value}. Autogen applies here too: a new Deployment gets the profile in its pod template at its own admission. Kyverno rewrites the matchConditions and the ApplyConfiguration for the template (Object.spec becomes Object.spec.template.spec); a JSONPatch is applied unchanged, so its paths would land on the Deployment itself.

The old API

Before 1.19 the same rules were kyverno.io/v1 ClusterPolicy objects with validate, mutate and verifyImages rules. 1.19 deprecates them and plans to remove them in 1.20:

Warning: kyverno.io/v1 ClusterPolicy is deprecated and will be removed in a future release; migrate to
ValidatingPolicy, MutatingPolicy, GeneratingPolicy or ImageValidatingPolicy (policies.kyverno.io), see
https://kyverno.io/docs/guides/migration-to-cel/

Which engine for which rule

ValidatingAdmissionPolicyKyverno 1.19OPA Gatekeeper 3.23
Installedbuilt in (API server)an add-on: 4 controllersan add-on: a controller + audit
Rules inCELCELRego (CEL with K8sNativeValidation)
ObjectsPolicy + Bindingone policy object per rule setConstraintTemplate + Constraint
ModesDeny / Warn / AuditDeny / Audit / Warndeny / dryrun / warn
Existing resourcesnoPolicyReportsaudit results
MutationMutatingAdmissionPolicy (newer)MutatingPolicyAssign / AssignMetadata
Image signaturesnoImageValidatingPolicyvia external data

Simple checks of the request: the built-in policy, nothing to run. Reports, defaults, signatures: a policy engine. Gatekeeper is the choice where Rego is already the language of the company's policies.

In an interview: "roll a policy out in Audit, read the PolicyReports, fix the violators, then switch to Deny" is the answer to "how do you add a policy without breaking production?".

On the exam: the CKS names "permitted registries" and "pod security"; whichever engine the task gives you, the pattern is the same: a rule, a binding of where it applies, a mode, and a proof.

Why it helps

Turning on a strict admission rule without knowing what already violates it breaks deploys, so a safe rollout is the skill teams actually need. PolicyReports show the current state of the cluster against each rule, and mutation removes whole classes of mistakes by setting defaults. Kyverno 1.19 also changed its API, so knowing the new CEL policy types keeps your answers current.

On the blog

Commands in this lesson

kubectl

FAQ

What do validationActions Deny, Audit and Warn do?

Deny refuses a request that fails the validation, Audit admits it and records the failure in a PolicyReport, and Warn admits it and returns a warning to kubectl. Start in Audit, fix what the reports show, then switch to Deny.

What is a PolicyReport?

A report the reports controller writes for each resource, named by the resource's uid, with one result per policy: pass, fail, warn, error or skip, the policy name and its message. kubectl get polr -n NAMESPACE lists them with the resource kind, name and the counts.

Why does a mutation run before validation?

Because the API server calls mutating admission first and validating admission after it. A MutatingPolicy can add the default a ValidatingPolicy requires, and the validation then sees the request as it will be stored, which is why a default can make a stricter rule pass.

What happened to ClusterPolicy?

Kyverno 1.19 deprecates kyverno.io/v1 ClusterPolicy and Policy and plans to remove them in 1.20; applying one returns a deprecation warning. New policies use the policies.kyverno.io types: ValidatingPolicy, MutatingPolicy, GeneratingPolicy and ImageValidatingPolicy, all written in CEL.

When is the built-in ValidatingAdmissionPolicy enough?

For simple checks of the request itself, such as a required label or a permitted registry, with nothing extra to run. You need a policy engine for reports on existing resources, mutation with defaults, or image signature checks.

In an interview Mid

How do you add a new admission policy without breaking production?

Roll it out in Audit first: the policy admits everything and the PolicyReports list each resource that would fail. Fix the violators, for example pin the image tags, check that kubectl get polr shows no FAIL left, then switch validationActions to Deny and prove it with a request that must be refused. Mutation can set the safe default so fewer requests fail at all.

Also asked: How do Kyverno and ValidatingAdmissionPolicy differ? · What does a MutatingPolicy change, and when does it run? · How would you migrate a Kyverno ClusterPolicy to the new API?

Practise this lesson in the terminal Free, in your browser - a real Ubuntu terminal to try it in, with missions that check your work.