OnCallReadyStart learning

KubernetesSecurity · 5 min read

Kyverno 1.19: moving from ClusterPolicy to ValidatingPolicy and ImageValidatingPolicy

Kyverno 1.19 deprecates ClusterPolicy and plans to remove it in 1.20. How the CEL policy types map, one rule converted, and a rollout that breaks nothing.

Apply any Kyverno policy you wrote before this autumn to a 1.19 cluster and you get a new line back:

terminal
$ kubectl apply -f legacy.yaml
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/
clusterpolicy.kyverno.io/disallow-latest-tag created

The policy still works. The warning is the notice period. Kyverno 1.19.0 (released 20 August 2026) deprecated ClusterPolicy, Policy, CleanupPolicy and the old kyverno.io PolicyException, and the migration guide says they "will be removed in v1.20". The replacements are the CEL-based types in the policies.kyverno.io/v1 group, which the guide says reach "full feature parity as of v1.19". Admission policies are also on the CKS exam ("permitted registries, sign and validate artifacts"), so the new types are worth learning either way.

What changes, in one table

A ClusterPolicy held a list of named rules, each of them a validate, mutate, generate or verifyImages rule written in Kyverno's patterns or JMESPath. The new model has one kind per action, written in CEL, and matching works the way the built-in ValidatingAdmissionPolicy does:

ClusterPolicy (kyverno.io/v1)CEL-based type (policies.kyverno.io/v1)
rules[].validateValidatingPolicy (short name vpol)
rules[].mutateMutatingPolicy (mpol)
rules[].generateGeneratingPolicy (gpol)
rules[].verifyImagesImageValidatingPolicy (ivpol)
CleanupPolicyDeletingPolicy (dpol)
rules[].match / excludespec.matchConstraints (resourceRules, excludeResourceRules) and spec.matchConditions
rules[].preconditionsspec.matchConditions
rules[].contextspec.variables
validate.failureAction: Enforce / Auditspec.validationActions: [Deny] / [Audit] (plus [Warn])
validate.pattern, deny, foreachspec.validations[].expression in CEL (all(), exists())
validate.podSecuritynot supported: one CEL validation per control
mutate.patchStrategicMergenot supported: patchType: ApplyConfiguration or JSONPatch

(From the migration guide's field tables.) Two of those rows are real work, not renaming: podSecurity rules and strategic-merge patches have to be rewritten.

One rule, converted

The classic "no latest tag" rule as a pattern:

yaml
apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: disallow-latest-tag
spec:
  rules:
  - name: require-image-tag
    match:
      any:
      - resources:
          kinds: [Pod]
    validate:
      failureAction: Audit
      message: An image tag is required.
      pattern:
        spec:
          containers:
          - image: "*:*"

The same check as a ValidatingPolicy. The match block is the one you know from ValidatingAdmissionPolicy, the pattern becomes a CEL expression over object, and the action moves into the policy itself (there is no separate binding object):

yaml
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.'

Both versions share a blind spot worth knowing: an image like registry.lab:5000/shop/api contains a : (the registry port) and has no tag. If your registries use ports, test the expression against those image names before you trust it.

Reading a field that may be missing is the most common CEL mistake. object.metadata.labels.team on a pod without labels is a runtime error, not false, and with the default failurePolicy: Fail an error denies the request. Guard it with has() or with the optional syntax the migration guide uses: object.metadata.?labels[label].orValue('') != ''.

Roll it out without breaking production

Start in Audit. Nothing is blocked, and the reports controller evaluates the policy against what already runs and writes one PolicyReport per resource:

terminal
$ kubectl apply -f vpol.yaml
validatingpolicy.policies.kyverno.io/disallow-latest-tag created
$ kubectl get vpol
NAME                  AGE   READY
disallow-latest-tag   0s    true
$ kubectl get polr -n shop
NAME                                   KIND   NAME                     PASS   FAIL   WARN   ERROR   SKIP   AGE
56988385-56af-496b-8293-c1c962049231   Pod    api-kdxwkx48wz-4rgql     1      0      0      0       0      0s
78d1cbcc-670b-4c0b-b659-20c35e9d67a3   Pod    cache-5w5x859frj-ppm6n   0      1      0      0       0      0s
8473174a-1eb8-4501-a0b9-0a5b666b83d8   Pod    web-p7jtq2fs7x-mssmt     0      1      0      0       0      0s

A report is named by the resource's uid, so the list is hard to read at a glance. A jsonpath gives you a to-do list:

terminal
$ kubectl get polr -n shop -o jsonpath='{range .items[*]}{.scope.name}{"\t"}{.results[0].result}{"\t"}{.results[0].message}{"\n"}{end}'
api-kdxwkx48wz-4rgql	pass	
cache-5w5x859frj-ppm6n	fail	An image tag is required, and it must not be latest.
web-p7jtq2fs7x-mssmt	fail	An image tag is required, and it must not be latest.

Fix the owners of the failing pods, not the pods. kubectl set image starts a rolling update, and the new pods get new reports:

terminal
$ kubectl set image deployment/web web=nginx:1.29 -n shop
deployment.apps/web image updated
$ kubectl set image deployment/cache cache=redis:8 -n shop
deployment.apps/cache image updated
$ kubectl get polr -n shop
NAME                                   KIND   NAME                     PASS   FAIL   WARN   ERROR   SKIP   AGE
16e5b599-d7ac-4aee-814f-41e97aaa7908   Pod    web-t5khz9dnxf-hztbb     1      0      0      0       0      0s
3fed9575-35ee-4fb8-a40f-1239f1b00129   Pod    cache-6qhvhw9ptq-hvwl9   1      0      0      0       0      0s
56988385-56af-496b-8293-c1c962049231   Pod    api-kdxwkx48wz-4rgql     1      0      0      0       0      41s

No FAIL left, so switch to Deny. The denial names the webhook and the policy:

terminal
$ sed -i 's/\[Audit\]/[Deny]/' vpol.yaml && kubectl apply -f vpol.yaml
validatingpolicy.policies.kyverno.io/disallow-latest-tag configured
$ 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.
$ kubectl run test -n shop --image=nginx:1.29
pod/test created

Then delete the old ClusterPolicy (kubectl delete clusterpolicy disallow-latest-tag). Running both means two webhooks judging the same request with two different messages.

verifyImages becomes ImageValidatingPolicy

Image signature checks move the most. In a ClusterPolicy they were a verifyImages rule with imageReferences and attestors[].entries[].keys.publicKeys. Per the guide's mapping, that becomes spec.matchImageReferences, spec.attestors[].cosign and a CEL validation that calls verifyImageSignatures, which returns how many attestors verified the image:

yaml
apiVersion: policies.kyverno.io/v1
kind: ImageValidatingPolicy
metadata:
  name: verify-shop-images
spec:
  validationActions: [Deny]
  matchConstraints:
    resourceRules:
    - apiGroups: ['']
      apiVersions: ['v1']
      operations: ['CREATE', 'UPDATE']
      resources: ['pods']
  matchImageReferences:
  - glob: "registry.lab/shop/*"
  attestors:
  - name: cosign
    cosign:
      key:
        data: |
          -----BEGIN PUBLIC KEY-----
          ...
          -----END PUBLIC KEY-----
  validations:
  - expression: >-
      images.containers.map(image, verifyImageSignatures(image, [attestors.cosign])).all(e, e > 0)
    message: failed the image Signature verification

Sign the image you trust with the matching private key (cosign sign --key cosign.key registry.lab/shop/api:2.3), apply the policy, and only that image gets in:

terminal
$ kubectl apply -f ~/verify.yaml
imagevalidatingpolicy.policies.kyverno.io/verify-shop-images created
$ kubectl run legacy --image=registry.lab/shop/legacy-api:1.0
Error from server: admission webhook "ivpol.validate.kyverno.svc-fail-finegrained-verify-shop-images" denied the request: Policy verify-shop-images failed: failed the image Signature verification
$ kubectl run api --image=registry.lab/shop/api:2.3
pod/api created
$ kubectl run web --image=nginx:1.29
pod/web created

nginx:1.29 is not under registry.lab/shop/*, so the policy does not look at it. matchImageReferences decides which images are checked at all. And sign by digest in real pipelines (cosign warns when you sign a tag): a tag can be moved to another image after you signed it.

Find what is left before 1.20

  • On the cluster: list the legacy kinds with kubectl get clusterpolicies (and kubectl get policies -A for the namespaced ones). Every create or update of one also returns the warning above.
  • In CI: the guide documents kyverno apply and kyverno test with --warnings-as-errors. They print the same deprecation warnings and fail the job on them. Scanners like kubesec and KubeLinter catch many of the same mistakes earlier, on the manifest itself: see kubesec vs kube-linter.
  • In metrics: the counter kyverno_deprecated_api_requests_total, labelled by group, version, kind and field, counts admission requests that still use deprecated types or fields. Wait for it to stay at zero before you upgrade.

Practise it

In the Kubernetes Security (CKS) chapter, the lesson Kyverno 1.19: validate, mutate, and read the PolicyReports covers the CEL types and how Kyverno compares with ValidatingAdmissionPolicy and Gatekeeper. The lab Roll out a policy without breaking production is the Audit, reports, fix, Deny sequence above on a namespace with two violators. Give every pod a seccomp profile by default does the same for a MutatingPolicy, and Only signed shop images may run builds the ImageValidatingPolicy with your own cosign key.

OnCallReady is free, with no ads and no tracking. RSS · All posts