Skip to content
Français
Account: not signed in, sync available My learning
Select theme
Français
Lire en français

Kyverno, the Kubernetes policy engine in YAML and CEL

By updated

Improve this page

Logo Kubernetes

Kyverno is a Kubernetes policy engine: it validates, mutates and generates resources, and it verifies image signatures, at the moment they reach the API server. A CNCF Graduated project since March 16, 2026, it is written in YAML and in CEL, the Kubernetes expression language. This guide is for a DevOps engineer who wants richer guardrails than the Pod Security Standards. The examples were replayed on Kyverno 1.19.1 and Kubernetes 1.37: installation, rejection of an unsigned image, and rejection of the requests it covers when the validation webhook becomes unreachable with failurePolicy: Fail. This does not mean every cluster write is blocked: it depends on the rules and the webhooks involved.

A point of timeline before your first policy, because it decides which syntax to learn. The CEL-based policy types arrived in two steps: ValidatingPolicy and ImageValidatingPolicy in 1.14, then MutatingPolicy, GeneratingPolicy and DeletingPolicy in 1.15. They moved to beta in 1.16, then to the stable policies.kyverno.io/v1 API in 1.17. That release also declared the historical ClusterPolicy and CleanupPolicy CRDs deprecated. Version 1.19 makes the deprecation visible: the kyverno.io CRDs, Policy included, carry deprecated: true and the API returns a warning on every apply.

Version 1.20, published on November 12, 2026, removes the old engine and blocks the creation of ClusterPolicy resources. This guide was replayed on 1.19.1, and several examples (hostPath, registries, mutation, generation, gradual rollout) are still written as ClusterPolicy. On 1.19 they apply as they are. On 1.20 you can no longer create them: convert them to CEL types with the project's migration guide.

The practical consequence: if you start today, write your policies in CEL. The historical YAML DSL stays in this guide because clusters in production still use it and you need to be able to read it, not so that you write new policies with it.

You do not even have to remember it: the API tells you on every apply.

Output
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/

In 1.19.1, the resource is created anyway and works normally: it is a warning, not a rejection. The policies.kyverno.io/v1 group also offers more types than the five listed here, each with a namespace-scoped variant: NamespacedValidatingPolicy, NamespacedMutatingPolicy and so on. This is useful when a team must set its own rules without touching the whole cluster.

A word on the CKS (Certified Kubernetes Security Specialist): the certification curriculum does not mention Kyverno. It talks about Pod Security Standards, permitted registries, signing and validating artifacts, and static analysis. Kyverno is a practical way to meet these requirements on a real cluster, but it is not an exam topic in itself.

What you will learn

  • When to use Kyverno (and when not to)
  • Install Kyverno and understand its operational complexity, webhook failure included
  • Create security-oriented validation policies
  • Verify image signatures (Supply Chain Security)
  • Test a policy outside the cluster with the Kyverno CLI
  • Diagnose violations with PolicyReports

Compatibility and versions

Kyverno follows a release cycle aligned with Kubernetes. Each major release supports several Kubernetes versions, but the available features vary from one combination to another: check the Kyverno and Kubernetes pair, not either one in isolation.

KyvernoHelm chartNotes
1.20.xnot checkedPublished on November 12, 2026: removes ClusterPolicy and CleanupPolicy; not replayed in this guide
1.19.x3.9.xBranch replayed in this guide; deprecation warnings on the kyverno.io API
1.18.x3.8.xPrevious branch
1.17.x3.7.xEnd of support

The project publishes its support policy and compatibility matrix on the releases page. It states that it tests 1.19 on Kubernetes 1.33 to 1.35. Versions outside this range, including the 1.36 and 1.37 of this course, may work, but they are not tested by the project: the examples below were replayed here, which is not a guarantee of support.

The examples in this guide were replayed on Kyverno v1.19.1, installed by chart 3.9.1, on a Kubernetes 1.37 cluster. The installation deploys four controllers: admission, background, cleanup and reports. It is therefore not a minor add-on, which is one more reason to measure its impact before switching it to blocking mode.

When to use Kyverno

Each tool answers a different need. This table helps you choose according to your real need, not the popularity of the tool. VAP stands for ValidatingAdmissionPolicy, the native API server mechanism that rejects a resource according to a CEL expression, with nothing to install. Pod Security Admission applies the three standard Kubernetes security profiles.

NeedRecommended toolWhy
Simple validation, no dependencyVAPNative, GA since K8s 1.30
Standard security profiles (runAsNonRoot...)Pod Security Admission3 ready-made profiles
Simple mutation (defaults)MutatingAdmissionPolicyNative and enabled since K8s 1.36
Advanced mutation (sidecars, foreach, context)KyvernoRicher than CEL alone
Resource generation (NetworkPolicies)KyvernoAutomation to compare with existing controllers and operators
Image signature verificationKyvernoCosign/Sigstore integration
Existing OPA/Rego cultureGatekeeperRego ecosystem

As a simple rule, if you need generation, signature verification or a mutation that CEL cannot express, Kyverno is probably the right choice. Otherwise, start with the native solutions: PSA, ValidatingAdmissionPolicy, and MutatingAdmissionPolicy since 1.36.

What Kyverno does better

What Kyverno adds on top of the native features depends on your cluster version. Up to Kubernetes 1.35, the API server could reject a resource with a ValidatingAdmissionPolicy, but not modify it. Since 1.36, MutatingAdmissionPolicy is GA and enabled by default: simple CEL mutation is native, and Kyverno 1.19 supports it too.

That leaves three capabilities with no native equivalent: generating a resource in response to another, querying a registry to verify a signature, and producing PolicyReports. Add to that a mutation richer than CEL, with patchStrategicMerge, context and foreach. This is what still justifies adding a dependency to the control plane.

  • Rich mutation: inject sidecars, apply a rule to every container with foreach, rely on external context. Simple defaults, on the other hand, now belong to MutatingAdmissionPolicy
  • Generation: automatically create NetworkPolicies, Secrets, ResourceQuotas
  • Image verification: Cosign, Sigstore, SLSA attestations
  • PolicyReports: native compliance audit

When NOT to use Kyverno

What these five situations have in common is the ratio of benefit to operational debt. Every webhook added to the cluster is a component to maintain, to update at the pace of Kubernetes and to monitor. If the need can be covered by a mechanism already present in the API server, adding Kyverno costs more than it brings.

  • Simple validation without mutation → prefer VAP (native, no dependency)
  • Simple defaults to set → prefer MutatingAdmissionPolicy, native since 1.36
  • Standard security profiles → prefer Pod Security Admission (simpler)
  • Cluster without high availability → Kyverno is an admission webhook, a sensitive component
  • Team already trained in Rego (in French) → prefer Gatekeeper

Operational complexity

Installing Kyverno means inserting a component between the API server and every resource write in the cluster. This component is an admission webhook: an address that the API server calls before storing each resource, so that an external service accepts, modifies or rejects it. This position explains most of its operational constraints: its availability governs that of deployments, its TLS certificates have a limited lifetime, and its RBAC rights cover a large part of the cluster. Before writing a single policy, decide how the cluster behaves when Kyverno is unavailable.

The diagram shows the path of a write. The API server calls the Kyverno webhook, which mutates then validates the resource before it is stored in etcd. The bottom exit is the one people forget: if the webhook does not answer, the API server applies the webhook's failurePolicy. With Fail, Kyverno's default value, it rejects the write; with Ignore, it lets it through.

Path of a write with Kyverno: kubectl apply reaches the API server, which calls Kyverno for mutation then validation and signature verification; a compliant resource is stored in etcd, a non-compliant resource is rejected with the policy message, and if the webhook is unreachable the write is rejected.compliantnon-compliantwebhook failurekubectl applyAPI serverKyvernomutationKyvernovalidation and signatureetcdobject storedRejected with thepolicy messageKyverno unreachable:write rejected
Source · SVG
Esc to close, + and − to zoom, scroll to move around. 100 %

This is not theoretical. Kyverno configures its webhooks with failurePolicy: Fail by default, and the configuration documentation describes how to switch to Ignore: the --forceFailurePolicyIgnore option, or the failurePolicy field of a policy. Measured with the default, by making the Kyverno service unreachable: even a compliant pod is rejected.

Output
Error from server (InternalError): Internal error occurred: failed calling webhook
"mutate.kyverno.svc-fail": failed to call webhook: Post
"https://kyverno-svc.kyverno.svc:443/mutate/fail?timeout=10s": dial tcp
10.96.174.50:443: connect: connection refused

In production, deploy in high availability (several replicas per controller):

Terminal window
helm install kyverno kyverno/kyverno --version 3.9.1 \
--set admissionController.replicas=3 \
--set backgroundController.replicas=2 \
-n kyverno --create-namespace

If Kyverno blocks the cluster, deleting its webhooks is not enough as long as its admission controller is running: measured, it recreates kyverno-resource-validating-webhook-cfg within a few seconds. You must stop it first. A clean shutdown removes the resource webhooks by itself; manual deletion remains the safety net if a crashed controller left them in place.

Terminal window
# 1. Stop the admission controller
kubectl -n kyverno scale deployment kyverno-admission-controller --replicas=0
# 2. Delete the webhooks that would remain in place
kubectl delete validatingwebhookconfiguration kyverno-resource-validating-webhook-cfg
kubectl delete mutatingwebhookconfiguration kyverno-resource-mutating-webhook-cfg

Installation

Two methods coexist, and the choice is not cosmetic. The Helm chart exposes the production settings (replicas per controller, resources, namespace exclusions) and allows a controlled upgrade. The install.yaml manifest deploys a fixed configuration, handy for a throwaway cluster but hard to customise afterwards. In both cases, Kyverno must live in a dedicated namespace: the project explicitly forbids co-locating it with other applications, kube-system included.

Terminal window
# Add the Helm repository
helm repo add kyverno https://kyverno.github.io/kyverno/
helm repo update
# Install Kyverno with 2 admission replicas, pinned chart (Kyverno 1.19.1)
helm install kyverno kyverno/kyverno --version 3.9.1 \
-n kyverno --create-namespace \
--set admissionController.replicas=2 \
--wait --timeout 5m

Check the installation:

Terminal window
kubectl get pods -n kyverno
NAME READY STATUS RESTARTS AGE
kyverno-admission-controller-769b8f7647-pqjbn 1/1 Running 0 37s
kyverno-admission-controller-769b8f7647-xfbbk 1/1 Running 0 37s
kyverno-background-controller-86d8df7447-wvdxj 1/1 Running 0 37s
kyverno-cleanup-controller-86c886ffff-nlnkk 1/1 Running 0 37s
kyverno-reports-controller-57c7978d69-z2d5z 1/1 Running 0 37s

Example 1: Requiring runAsNonRoot (CKS-ready)

This example maps to the CKS objective "Use appropriate pod security standards". Both tabs reject the same pod, through different paths: the CEL version evaluates a boolean expression on the submitted object, whereas the historical version compares the resource with a YAML pattern applied recursively. The CEL version is more readable for complex conditions: the exclusion of system namespaces fits here in a single matchConditions condition.

apiVersion: policies.kyverno.io/v1
kind: ValidatingPolicy
metadata:
name: require-run-as-non-root
spec:
validationActions: [Deny]
matchConstraints:
resourceRules:
- apiGroups: [""]
apiVersions: ["v1"]
operations: ["CREATE", "UPDATE"]
resources: ["pods"]
matchConditions:
- name: exclude-system-ns
expression: >-
!(['kube-system','kyverno'].exists(ns, object.metadata.namespace == ns))
validations:
- expression: >-
object.spec.containers.all(c,
has(c.securityContext) &&
has(c.securityContext.runAsNonRoot) &&
c.securityContext.runAsNonRoot == true
)
message: "Tous les conteneurs doivent avoir runAsNonRoot: true."

Replayed on Kubernetes 1.37, the CEL version shows READY true in kubectl get validatingpolicy within a few seconds, then rejects an nginx pod without a securityContext with the policy message:

Output
Error from server: admission webhook "vpol.validate.kyverno.svc-fail-finegrained-require-run-as-non-root"
denied the request: Policy require-run-as-non-root failed: Tous les conteneurs doivent avoir runAsNonRoot: true.

Example 2: Rejecting hostPath and hostNetwork

These three rules close the doors that give the container direct access to the node: a hostPath volume mounts a host directory into the pod, hostNetwork puts the pod in the node's network namespace, hostPID and hostIPC give it visibility of the host's processes and shared memory. Each rule is independent and fails separately, which makes the diagnosis readable: Kyverno reports the exact path that triggered the rejection. This policy is written as a ClusterPolicy: on 1.20, convert it to a ValidatingPolicy.

Note the =(volumes) anchor: it makes the check conditional. A pod without any volume passes the rule instead of failing on a missing field. Measured: a pod that mounts the host's /etc is rejected with rule deny-hostpath failed at path /spec/volumes/0/hostPath/, a pod with hostNetwork: true with rule deny-host-network failed at path /spec/hostNetwork/.

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
name: deny-host-access
spec:
background: true
rules:
- name: deny-hostpath
match:
any:
- resources:
kinds:
- Pod
validate:
failureAction: Enforce
message: "Les volumes hostPath sont interdits"
pattern:
spec:
=(volumes):
- X(hostPath): "null"
- name: deny-host-network
match:
any:
- resources:
kinds:
- Pod
validate:
failureAction: Enforce
message: "hostNetwork n'est pas autorisé"
pattern:
spec:
=(hostNetwork): false
- name: deny-host-pid-ipc
match:
any:
- resources:
kinds:
- Pod
validate:
failureAction: Enforce
message: "hostPID et hostIPC sont interdits"
pattern:
spec:
=(hostPID): false
=(hostIPC): false

Example 3: Restricting the allowed registries

This control links Kyverno to the Supply Chain Security domain of the CKS. The foreach loop goes through every container of the pod, not only the first one. Watch out for the trap of the image without an explicit registry: a manifest that asks for busybox:1.37 matches none of the allowed patterns and is rejected, even though the image does come from Docker Hub. Measured: the same image written docker.io/library/busybox:1.37 passes the rule. This is the intended effect, provided you explain it in the error message. This policy is written as a ClusterPolicy: on 1.20, convert it to a ValidatingPolicy.

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
name: restrict-image-registries
spec:
background: true
rules:
- name: validate-registries
match:
any:
- resources:
kinds:
- Pod
validate:
failureAction: Enforce
message: "Images autorisées uniquement depuis gcr.io ou docker.io/library"
foreach:
- list: "request.object.spec.containers"
deny:
conditions:
all:
- key: "{{ element.image }}"
operator: AnyNotIn
value:
- "gcr.io/*"
- "docker.io/library/*"

Image signature verification (Supply Chain)

Verifying a signature at admission moves the control to the last useful moment: whatever happened in the build chain, an image not signed with the expected key does not enter the cluster. Kyverno resolves the image reference with the registry, fetches the associated Cosign signature and validates it against the public key declared in the policy. A consequence to anticipate: the admission controller needs outbound network access to the registry, and a private registry requires giving it read credentials.

With the new CEL policy types (1.17+)

ImageValidatingPolicy separates two concerns that the historical syntax mixed up. The attestors block declares who is allowed to sign; the validations block describes what is required of the image once the signature is verified. That is where you would add a condition on an SLSA attestation or on the content of an SBOM.

Two details cost an hour of debugging if you ignore them, both measured on Kyverno 1.19.1. The public key does not live in a Secret: the key field accepts data, plain-text PEM, kms or expression, never secretRef, and the API rejects the policy with unknown field "spec.attestors[0].cosign.key.secretRef". And the name of an attestor must not contain a dash, because it is referenced from a CEL expression: my-cosign-key reads as a subtraction there and returns undeclared reference to 'key'.

The policy below was replayed with the test image that the Kyverno project publishes, ghcr.io/kyverno/test-verify-image, whose signed variant carries a Cosign signature and whose unsigned variant carries none. This signature was not recorded in Sigstore's public transparency log (Rekor), hence the ctlog block that exempts it from that check; an image signed by cosign sign with a key, which records the signature in Rekor by default, does without it.

apiVersion: policies.kyverno.io/v1
kind: ImageValidatingPolicy
metadata:
name: verify-image-signature
spec:
validationActions: [Deny]
matchConstraints:
resourceRules:
- apiGroups: [""]
apiVersions: ["v1"]
operations: ["CREATE", "UPDATE"]
resources: ["pods"]
matchImageReferences:
- glob: "ghcr.io/kyverno/test-verify-image*"
attestors:
- name: mycosignkey
cosign:
key:
data: |
-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE8nXRh950IZbRj8Ra/N9sbqOPZrfM
5/KAQN0/KjHcorm/J5yctVd7iEcnessRQjU917hmKO6JWVGHpDguIyakZA==
-----END PUBLIC KEY-----
ctlog:
insecureIgnoreTlog: true
validations:
- expression: >-
images.containers.map(image,
verifyImageSignatures(image, [attestors.mycosignkey])).all(e, e > 0)
message: "Image must be signed with our Cosign key."

The result, measured on Kubernetes 1.37: the signed variant is admitted, the unsigned variant is rejected with the policy message, and an image outside the matchImageReferences pattern, such as busybox, is not affected.

Output
$ kubectl run signed --image=ghcr.io/kyverno/test-verify-image:signed@sha256:b31bfb4d0213f254d361e0079deaaebefa4f82ba7aa76ef82e90b4935ad5b105
pod/signed created
$ kubectl run unsigned --image=ghcr.io/kyverno/test-verify-image:unsigned@sha256:74a98f0e4d750c9052f092a7f7a72de7b20f94f176a490088f7a744c76c53ea5
Error from server: admission webhook "ivpol.validate.kyverno.svc-fail" denied the request:
Policy verify-image-signature failed: Image must be signed with our Cosign key.

The call to verifyImageSignatures is not decorative: it is what triggers the verification. Measured by replacing it with the expression "true": the attestors are then evaluated by nobody, and every image matching the pattern is rejected, the signed variant included, with image ... is not verified: no policy performed a signature or attestation check on it. A validation must therefore always call verifyImageSignatures, or verifyAttestationSignatures for an attestation.

With the historical ClusterPolicy

The verifyImages rule writes the public key in clear in the policy. This is not a problem, a public key not being a secret, but it complicates rotation: changing the key means editing every policy involved. The background: false is not a detail: verifying signatures requires network calls to the registry, too costly to be replayed as a background task on every existing resource. This example was not replayed: it is there to help you recognise this syntax in an existing cluster, the CEL version above being the one to write.

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
name: verify-image-cosign
spec:
background: false
rules:
- name: verify-signature
match:
any:
- resources:
kinds:
- Pod
verifyImages:
- imageReferences:
- "gcr.io/my-project/*"
failureAction: Enforce
attestors:
- entries:
- keys:
publicKeys: |
-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...
-----END PUBLIC KEY-----

Mutation: adding defaults

Mutation automatically modifies a resource before it is stored. The policy below adds three security settings to every container that does not declare them.

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
name: add-security-defaults
spec:
background: false # Mutation = no background
rules:
- name: add-security-context
match:
any:
- resources:
kinds:
- Pod
mutate:
patchStrategicMerge:
spec:
containers:
- (name): "*"
securityContext:
+(runAsNonRoot): true
+(allowPrivilegeEscalation): false
+(readOnlyRootFilesystem): true

Mutation operators

The Kyverno mutation syntax uses special operators to control its behaviour. Understanding these operators is essential to write effective mutations.

OperatorEffectUse
(key)Conditional anchorTarget specific containers
+(key)Add if absentNon-intrusive defaults
<(key)Global anchorCondition on another part of the resource

Concrete example: if you want to add runAsNonRoot: true only to pods that do not already declare that field, use +(runAsNonRoot): true. This avoids overriding an explicit configuration set by the developer.

A security mutation can break what it protects. Measured on Kubernetes 1.37: a busybox pod does receive the three fields, then stays in CreateContainerConfigError, because its image starts as root and runAsNonRoot: true now forbids it. Before generalising such a mutation, check that your images run as non-root and support a read-only file system.

Mutation only knows these three anchors. There is no removal anchor: to remove a field, you go through patchesJson6902 and its remove operation. The =() equality, ^() existence and X() negation anchors belong to validation, not to mutation, and that is where you meet them earlier in this guide.

Generation: automatic NetworkPolicies

Generation answers a recurring problem: a security resource must exist in every namespace, and nobody thinks of creating it. Here, creating a namespace triggers the creation of a NetworkPolicy that blocks all incoming and outgoing traffic by default. The synchronize: true field changes the contract: Kyverno does not merely create the resource, it restores it if someone modifies or deletes it. This is what sets generation apart from a simple initialisation script.

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
name: generate-default-deny
spec:
rules:
- name: create-network-policy
match:
any:
- resources:
kinds:
- Namespace
exclude:
any:
- resources:
namespaces:
- kube-system
- kyverno
generate:
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
name: default-deny
namespace: "{{request.object.metadata.name}}"
synchronize: true
data:
spec:
podSelector: {}
policyTypes:
- Ingress
- Egress

Effect: measured, every new namespace receives a default-deny NetworkPolicy within a few seconds. Namespaces that existed before the policy do not receive it: for that you need to enable generateExisting: true in the rule.

failureAction and gradual rollout

Deploying a policy straight in blocking mode (Enforce) is risky. Kyverno allows a gradual rollout, with two modes and per-namespace overrides. Measured with the policy below: a pod without an app label is rejected in production and created in another namespace, where the violation goes to a PolicyReport.

ValueEffectPhase
EnforceBlocks the requestProduction
AuditLogs into PolicyReportsDiscovery

Recommended strategy:

  1. Start with Audit: violations are recorded in the PolicyReports. Look at them to understand the impact.
  2. Add overrides: switch to Enforce on the critical namespaces, production, while staying in Audit elsewhere.
  3. Generalise Enforce: once all workloads are compliant, switch to blocking mode globally.

Gradual strategy, with an override for production:

spec:
rules:
- name: require-labels
match:
any:
- resources:
kinds:
- Pod
validate:
failureAction: Audit # Permissive by default
failureActionOverrides:
- action: Enforce
namespaces:
- production # Strict in production
message: "Le label 'app' est obligatoire"
pattern:
metadata:
labels:
app: "?*"

Kyverno CLI (shift-left)

The CLI lets you test policies locally before deployment, without a cluster, which makes it usable in a pipeline job. Two commands cover the essentials: kyverno apply evaluates a policy against one or more manifests and shows the pass / fail / warn / error / skip count, while kyverno test runs a suite of cases described in a kyverno-test.yaml file. The apply command also serves as a syntax check: a malformed policy comes up as error before it even reaches the cluster.

Terminal window
# Install through Krew (the plugin follows version 1.19.1)
kubectl krew install kyverno
# Test a policy against a manifest
kyverno apply ./policy.yaml --resource ./pod.yaml
# Run the test suite described in ./policy-tests/kyverno-test.yaml
kyverno test ./policy-tests/

Here is the actual output of kyverno apply, measured with CLI 1.19.1 on a pod that violates the policy of example 1. The command exits with code 1, which is enough to fail a CI job:

Applying 1 policy rule(s) to 1 resource(s)...
policy require-run-as-non-root -> resource equipe-web/Pod/nginx-sans-securite failed:
1 - Tous les conteneurs doivent avoir runAsNonRoot: true.
pass: 0, fail: 1, warn: 0, error: 0, skip: 0

A test suite describes the expected result for each resource. The kyverno create test command generates a skeleton, but the 1.19.1 one carries a namespace field that kyverno test then rejects (unknown field "namespace"). The accepted format, measured, names the resource as namespace/name:

policy-tests/kyverno-test.yaml
apiVersion: cli.kyverno.io/v1alpha1
kind: Test
metadata:
name: require-run-as-non-root
policies:
- policy.yaml
resources:
- pod.yaml
results:
- policy: require-run-as-non-root
resources:
- equipe-web/nginx-sans-securite
kind: Pod
result: fail

kyverno test ./policy-tests/ then returns Test Summary: 1 tests passed and 0 tests failed: the test succeeds because the policy fails on this pod, as expected.

You may be tempted to look for a kyverno validate command to check the syntax, but it does not exist. CLI 1.19.1 exposes apply, completion, create, docs, jp, migrate, test and version; fix and oci only appear with the KYVERNO_EXPERIMENTAL=true variable. To detect an invalid policy, go through kyverno apply.

The Kyverno CLI is part of the syllabus of the Kyverno Certified Associate certification, delivered by the Linux Foundation. For the CKS, it is not required, but it lets you test a policy before deploying it.

Diagnosing policies

When a Kyverno policy "does not work", the symptom does not say which of two problems you have. Either the policy is rejected or inactive, and nothing is evaluated; or it works but does not select the resources you thought you were targeting, and its silence looks like a failure.

This distinction structures the whole diagnosis, and it is settled in one command: an accepted rule shows Ready: True in its status. In that case, look at the match and the enforcement mode, not at the installation.

Essential commands

The diagnosis follows two distinct tracks that must not be confused. The first concerns the policy itself: is it accepted by Kyverno? The answer is in kubectl describe, in the status.conditions field. The second concerns the evaluated resources: which violations were found? They live in the PolicyReports, with one report per evaluated object. These reports are fed only if the policy is in Audit mode or if background: true is active.

Terminal window
# List CEL policies (READY column) and historical ones
kubectl get validatingpolicies,imagevalidatingpolicies
kubectl get clusterpolicies,policies -A
# Details of a policy (errors, conditions)
kubectl describe clusterpolicy <name>
# PolicyReports (one report per evaluated object)
kubectl get policyreport -A
# Violation details
kubectl describe policyreport -n <namespace>
# Quick summary
kubectl get policyreport -A -o jsonpath='{range .items[*]}{.metadata.namespace}{"\t"}{.summary}{"\n"}{end}'

Common errors

Here are common problems and how to solve them quickly.

SymptomLikely causeSolution
Policy "Ready: False"Syntax errorkubectl describe clusterpolicy
No violation in Auditbackground: falseAdd background: true
Mutation not appliedPod already existingRecreate the pod
Webhook timeoutKyverno overloadedIncrease replicas

The status.conditions field of a policy holds the detailed error messages: look at it first.

Kyverno has a policy, but does it block the request?

Take a team that has deployed a rule meant to reject privileged containers. It checks the PolicyReports and concludes that the cluster is protected. One important check is still missing: submit to the Kubernetes API a request that should be denied.

A report can show that an existing resource does not comply with the policy. That does not mean Kubernetes rejected its creation, or that Kyverno will remove it. To check admission, create a compliant resource and then a deliberately non-compliant one in a test environment. Look at the API server's response in both cases.

Also test the reaction when Kyverno no longer answers. Kyverno configures failurePolicy: Fail by default: the request is rejected. With Ignore, it goes through without any check. This setting does not play the same role as the choice between audit and enforcement. The Kyverno security documentation and the reports documentation let you tell these behaviors apart. For a critical service, decide which behavior you accept, and try it on a test cluster before changing the real configuration. Check the exact fields of the version you use.

Before generalizing the rule, specify the namespaces it covers and those that are excluded. Also identify who can edit the policy and who can approve an exception. An expiry date in an annotation does not automatically remove the exception: plan how it will be removed.

A local kyverno test helps check a policy, but does not by itself prove how live admission behaves.

Key points

  1. ClusterPolicy and CleanupPolicy are deprecated since 1.17, 1.19 shows a warning on every apply, and 1.20 (November 12, 2026) blocks their creation: write your policies in CEL.

  2. validationFailureAction is deprecated: use validate.failureAction at rule level.

  3. Kyverno is a sensitive component: with failurePolicy: Fail, the default, an unreachable webhook makes the writes it covers fail. Deploy in HA, and stop the controller before deleting its webhooks.

  4. Image verification is one way to cover "sign and validate artifacts", in the Supply Chain Security domain of the CKS.

  5. For simple validation, prefer VAP: it is native and has no dependency.

  6. Two capabilities have no native equivalent: resource generation and image signature verification.

  7. kyverno validate does not exist: the CLI is checked with kyverno apply and kyverno test.

  8. An ImageValidatingPolicy must call verifyImageSignatures: with "true", every image is rejected, signed ones included.

Knowledge check

These questions cover Kyverno's position against the native solutions, the syntax of validation and mutation rules, and how to read a PolicyReport.

Knowledge check

Check what you have learned with this interactive quiz

6 questions
8 min
70% to pass

How it works

  • The timer starts when you click Start
  • Multiple choice, true/false and short answer questions
  • You can move between questions
  • Detailed results are shown at the end

Starts the quiz and the timer