Kyverno Knowledge Patch

Kyverno Knowledge Patch

Use this skill when writing, migrating, testing, or operating Kyverno policies. Prefer the specialized CEL policy APIs for new work, and check the installed Kyverno release before selecting an API version or a namespaced policy kind.

Reference index

Breaking changes and migration

Use stable CEL policy APIs

For Kyverno 1.17 and newer, write specialized policies with:

apiVersion: policies.kyverno.io/v1
kind: ValidatingPolicy

The stable family includes cluster-scoped and namespaced validating, mutating, generating, image-validating, and deleting policies, plus PolicyException. v1beta1 remains supported for a transition, but new manifests should use v1.

When supporting Kyverno 1.16, use policies.kyverno.io/v1beta1. Earlier manifests may still use v1alpha1; do not copy that version into current manifests without checking the target cluster.

Migrate legacy policy kinds

ClusterPolicy and CleanupPolicy are deprecated as of 1.17. They remain functional, receive only critical fixes in 1.18 and 1.19, and are planned for removal in 1.20. Use the specialized CEL v1 kinds for new policy work.

When migrating a legacy validate.pattern rule:

1. Select ValidatingPolicy or NamespacedValidatingPolicy.
2. Translate the pattern into CEL expressions under spec.validations.
3. Move resource selection into Kubernetes-style matchConstraints.
4. Test the new policy before replacing the legacy resource.

Legacy policies remain usable during migration; do not require a flag-day conversion.

Update report integrations

Policy reports use the openreports.io API group. Update consumers that still expect wgpolicyk8s.io, including Reports Server and Policy Reporter deployments, to compatible releases.

Choosing a policy kind

Namespaced policies limit ownership and effects to their containing namespace. The namespaced validating, image-validating, and deleting kinds are available in 1.16. Namespaced mutating and generating kinds arrive in 1.17.

Validation quick start

Use spec.validations for CEL assertions and spec.matchConstraints for resource selection:

apiVersion: policies.kyverno.io/v1
kind: ValidatingPolicy
metadata:
  name: limit-deployment-replicas
spec:
  validations:
    - expression: object.spec.replicas <= 5
      message: The number of replicas must not exceed 5
  matchConstraints:
    resourceRules:
      - apiGroups: [apps]
        apiVersions: [v1]
        resources: [deployments]

Kyverno can generate a native Kubernetes ValidatingAdmissionPolicy from this policy so validation runs in the API server.

Mutation and generation quick start

MutatingPolicy supports CEL-based apply-configuration patches:

spec:
  mutations:
    - patchType: ApplyConfiguration
      applyConfiguration:
        expression: >
          Object{
            metadata: Object.metadata{
              labels: Object.metadata.labels{
                environment: "production"
              }
            }
          }

GeneratingPolicy can fetch a source resource and apply it to a target namespace:

spec:
  variables:
    - name: sourceSecret
      expression: resource.Get("v1", "secrets", "default", "regcred")
  generate:
    - expression: generator.Apply(object.metadata.name, [variables.sourceSecret])

Generation expressions can use loops and the extended Kyverno CEL libraries.

Scheduled deletion quick start

DeletingPolicy is the CEL counterpart to CleanupPolicy. It evaluates existing resources on a cron schedule and deletes resources matching its constraints and conditions:

spec:
  schedule: "0 1 * * *"
  matchConstraints:
    resourceRules:
      - apiGroups: [""]
        apiVersions: [v1]
        resources: [pods]
        scope: Namespaced
  conditions:
    - name: isOld
      expression: now() - object.metadata.creationTimestamp > duration("72h")

Policy exceptions

Keep exceptions narrow. Use policyRefs to name the policy and CEL matchConditions to select resources. An exception may also provide:

• spec.images, consumed by the policy as exceptions.allowedImages.
• spec.allowedValues, consumed as exceptions.allowedValues.
• spec.reportResult: pass to record a pass instead of the default skip.

This allows a policy to bypass only an approved image or value rather than exempting the whole resource.

CEL execution guidance

CEL policies can read live Kubernetes resources, cached global context, external HTTP responses, parsed admission users, parsed image references, and OCI registry metadata. See the CEL reference before choosing a function.

Extended libraries are also available in policy matchConditions. Kyverno evaluates those conditions itself; it does not translate them into admission webhook matchConditions, so they do not alter webhook routing.

Treat HTTP calls as privileged behavior. Unsafe destinations are blocked by default in 1.18, and namespaced policies have HTTP disabled by default. Enable it only with explicit configuration and a deliberate address policy.

Image verification guidance

Use ImageValidatingPolicy to:

• Select image references with globs or CEL.
• Verify signatures and attestations, including SBOMs.
• Extract images from arbitrary JSON payloads.
• Supply verification certificates dynamically through CEL.

Image verification supports Cosign v3 features. For legacy ClusterPolicy verification, registry credential secrets may use namespace/name, and Kyverno can automatically use a Pod's imagePullSecrets.

CLI checks

Use kyverno apply and kyverno test before installing policies. The CLI can evaluate CEL validating and image policies against arbitrary JSON and can perform offline mutation.

Current CLI support also covers cleanup policies, HTTP and Envoy authorization policies, and mutateExisting rules in MutatingPolicy. Use --exceptions-with-policies when testing policy-exception workflows.

Reports, events, and metrics

To reduce report storage, use --allowedResults to retain only selected outcomes. To suppress reports for one policy without disabling enforcement, add:

metadata:
  labels:
    reports.kyverno.io/disabled: "true"

The label suppresses ephemeral and persisted policy reports. Remove it to resume reporting.

CEL policies expose execution-duration histograms and emit Kubernetes Events for evaluation results and policy load or compile failures. Configure successEventActions to reduce successful-event noise while keeping failure reporting.

The admission controller supports memory-based HPA autoscaling, and the /metrics endpoint can use TLS.

Operational compatibility

Kyverno 1.16 uses chart 3.6.0; Kyverno 1.17 uses chart 3.7.0. Pin the chart version that matches the intended application release during upgrades.

Starting with 1.18, community patch support covers only the current and immediately previous releases for roughly three months, and fixes in that window are limited to critical or high-severity CVEs and other critical issues. Plan frequent upgrades or arrange longer-term commercial support.