Migrate Kyverno ClusterPolicy Rules to CEL Policies Before v1.20

Kyverno is removing the old ClusterPolicy type in version 1.20, so every team still running validate, mutate, generate, or image rules needs a plan now. This guide shows you how to migrate Kyverno ClusterPolicy to CEL using real rule examples. Also, you will learn how to move your PolicyException objects and check stored data before you upgrade.

If you are new to CEL-based policies and want to learn the basics, you can check this guide on Kyverno CEL policies for Kubernetes.

Kyverno used to have one policy type, ClusterPolicy, that could validate, mutate, generate, and verify images all in one file. As Kubernetes added native support for CEL, Kyverno built five new focused policy types on top of it:

• ValidatingPolicy
• MutatingPolicy
• GeneratingPolicy
• ImageValidatingPolicy
• DeletingPolicy

These new types run faster because many of them convert directly into Kubernetes' own ValidatingAdmissionPolicy and MutatingAdmissionPolicy, so checks can run inside the API server instead of a separate webhook call.

Here is the official deprecation timeline for ClusterPolicy, Policy, CleanupPolicy, and the legacy PolicyException:

Kyverno v1.19 is the current latest stable release, and it is also the last version where ClusterPolicy still works fully. This is why every team must plan and test its move now, before v1.20 launches and the old objects stop being served.

Before migrating to CEL, make sure these things are ready:

• A test or staging Kubernetes cluster. Do not test this on production.
• kubectl configured to talk to that cluster.
• Helm 3 installed on your machine.
• Kyverno v1.19 or the latest stable release installed with Helm.
• The Kyverno CLI, matching the same version as your cluster install.
• A full backup of every ClusterPolicy, Policy, CleanupPolicy, and PolicyException object.

When v1.20 comes out, ClusterPolicy, Policy, and CleanupPolicy will be gone from Kyverno completely. If you don't migrate Kyverno ClusterPolicy to CEL before that, your old rules stop working the moment you upgrade, and your cluster loses that protection. Kyverno does not convert old rules for you, so you must create and test the new CEL policies yourself before removing the old ones.

The old and new policies can run together during the switch, since they use separate API groups, so you can migrate step by step instead of all at once.

Add the Helm repository and install or upgrade Kyverno to v1.19, the current latest stable release with full CEL policy support:

Note: the Helm chart version numbers and the Kyverno app version numbers are different. Check the chart's Chart.yaml appVersion field or run the command below to confirm Kyverno v1.19:

Confirm every pod is healthy before moving on:

In the output, you must see CRDs for:

These are the new CEL-based types you will use in the next steps.

Before you change anything, save a copy of every old policy. This way, you can go back to it if something breaks. To do this, you can use the commands below:

Now check how many rules you have of each type. This tells you how much work is left:

Validate rules are the simplest to convert. Here is a real legacy ClusterPolicy that blocks Pods without a team label:

Now here is the same rule, written as a ValidatingPolicy with a CEL expression instead of a pattern:

Here's what changed: pattern becomes a true/false CEL expression under validations, message stays the same, and validationFailureAction is now called validationActions.

Start with simple rules like this one when you migrate Kyverno ClusterPolicy to CEL. They're the easiest, and they help your team learn CEL before moving to harder rules.

One thing to watch for: with deny rules, the logic reverses. In ClusterPolicy, a deny rule blocks the request when its condition is true. In ValidatingPolicy, the expression must return true to allow the request. So when you rewrite a deny rule, reverse the condition.

Here is a legacy mutate rule that adds a default CPU and memory limit to containers that do not define one:

Here is the same rule as a MutatingPolicy. It uses the ApplyConfiguration style and a CEL map() loop to go through each container:

This part confuses most teams, because CEL has no direct match for patchStrategicMerge. You must rewrite each mutation as ApplyConfiguration merge style, shown above, or JSONPatch for single-field edits. 

Always test mutate rules on a real sample resource with the Kyverno CLI before turning them on in a cluster.

A common legacy pattern is to auto-create a default NetworkPolicy whenever a new namespace appears:

Here is the same rule as a GeneratingPolicy. It writes the new object's contents as a CEL expression:

synchronize and generateExisting keep the same names, but now sit under spec.evaluation instead of directly in the rule. Test this policy on a throwaway namespace first, then check the result with:

If your cluster checks image signatures with Cosign, here is the old rule:

Here is the same rule as an ImageValidatingPolicy, the CEL policy type made just for image security:

This shows why you should not migrate Kyverno ClusterPolicy to CEL all at once. ImageValidatingPolicy has its own CEL functions, like verifyImageSignatures() and verifyAttestationSignatures(). So test image checks separately from your plain validation rules.

The old kyverno.io PolicyException only works with legacy ClusterPolicy rules. It is also deprecated and removed in v1.20. It needs its own migration to the new policies.kyverno.io PolicyException, which is the type that works with all CEL policies.

Here is an old exception that lets one deployment skip a rule:

Here is the new exception. It points to the CEL policy by name and uses a match condition instead of named rules, since CEL policies don't have named rules inside them:

Repeat this for every exception in your backup file. Don't skip this; if you miss one, a resource that used to be allowed will suddenly get blocked.

Because CEL policies live in a separate API group, you can run old and new rules together safely. Use this pattern every time you migrate Kyverno ClusterPolicy to CEL for a rule that matters:

1. Create the new CEL policy with validationActions: [Audit] so it only reports violations without blocking anything.
2. Watch the PolicyReport objects for a few days: kubectl get polr -A and kubectl describe polr <name> -n <namespace>.
3. Limit the rollout further with matchConditions, for example, only matching one namespace at first, then widening it once you trust the results.
4. When reports look clean, switch validationActions to [Enforce].
5. Only after the CEL policy is in Enforce mode and stable, disable or delete the old ClusterPolicy rule it replaces.

Note: Never delete the old rule and switch on the new one at the same moment. Running both for a week or two in audit mode is the safest way to catch a CEL expression mistake before it blocks real traffic.

Testing is a must when you migrate Kyverno ClusterPolicy to CEL. A small mistake in a CEL expression can quietly allow or block the wrong resources. So before any policy touches a real cluster, test it locally first:

If you already have Kyverno CLI tests for your old ClusterPolicy rules, you can reuse them for the new CEL policies with no changes to the test files themselves; only the policy file needs to change. 

In Kyverno v1.19, CEL policy objects are stored internally as v1beta1. In v1.20, this changes to v1. So after you upgrade, before your final switch, update any old stored objects to the new storage version with this command:

Also, confirm no legacy objects remain before you upgrade to v1.20:

Both commands should show "No resources found" everywhere before you upgrade to v1.20. If anything still shows up, go back and finish converting it.

Once every CEL replacement is in Enforce mode and has run cleanly for a week or more, remove the legacy objects:

Keep the backup files even after deletion. They are your rollback plan if you ever need to check exactly what a legacy rule used to do.

A policy engine is only as good as the cluster running it. Once you migrate Kyverno ClusterPolicy to CEL, you need steady CPU, fast network to the API server, and reliable disk speed. This is because background scans, mutations, and image checks all add extra load. 

For production clusters, consider dedicated hosting built for Kubernetes workloads as your target. Dedicated hardware gives Kyverno's controllers guaranteed resources, so policy checks stay fast even under heavy load.

Kyverno's move to CEL is a real improvement with faster checks, better Kubernetes fit, and five focused policy types instead of one big one. But you only get these benefits once you migrate Kyverno ClusterPolicy to CEL, rule by rule, testing in audit mode before you enforce. 

First, upgrade Kyverno, back up your old rules, and convert validate rules. Then, mutate, generate, and image rules, migrate your exceptions, and roll out in stages. Finally, check for leftover objects before v1.20 removes the old types for good.

We hope you enjoy this guide. For more detailed information, you can check the Kyverno Official Migration.