Apply any Kyverno policy you wrote before this autumn to a 1.19 cluster and you get a new line back:
$ 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 createdThe 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[].validate | ValidatingPolicy (short name vpol) |
rules[].mutate | MutatingPolicy (mpol) |
rules[].generate | GeneratingPolicy (gpol) |
rules[].verifyImages | ImageValidatingPolicy (ivpol) |
CleanupPolicy | DeletingPolicy (dpol) |
rules[].match / exclude | spec.matchConstraints (resourceRules, excludeResourceRules) and spec.matchConditions |
rules[].preconditions | spec.matchConditions |
rules[].context | spec.variables |
validate.failureAction: Enforce / Audit | spec.validationActions: [Deny] / [Audit] (plus [Warn]) |
validate.pattern, deny, foreach | spec.validations[].expression in CEL (all(), exists()) |
validate.podSecurity | not supported: one CEL validation per control |
mutate.patchStrategicMerge | not 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:
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):
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:
$ 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 0sA 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:
$ 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:
$ 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 41sNo FAIL left, so switch to Deny. The denial names the webhook and the policy:
$ 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 createdThen 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:
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 verificationSign 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:
$ 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 creatednginx: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(andkubectl get policies -Afor the namespaced ones). Every create or update of one also returns the warning above. - In CI: the guide documents
kyverno applyandkyverno testwith--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.