Kyverno Knowledge Patch

Kyverno Knowledge Patch

Use this skill when creating, reviewing, testing, or operating Kyverno policies, especially the specialized CEL policy APIs. Prefer the project's manifests, installed CRDs, Helm values, and observed behavior when they disagree with this guidance.

How to Use This Skill

1. Determine the installed Kyverno and chart versions before changing API versions or values.
2. Identify whether the policy is a specialized CEL policy or a legacy ClusterPolicy/CleanupPolicy.
3. Choose cluster-scoped or namespaced policy kinds deliberately.
4. Check whether expressions rely on Kyverno CEL extensions, network access, registry credentials, or exception-provided data.
5. Exercise the policy with kyverno apply or kyverno test, then verify reports, Events, and metrics in the cluster.
6. Open the topic reference for complete syntax and operational constraints.

Reference Index

Breaking Changes and Deprecations

Use the API Version Installed by the Target Cluster

The specialized policy API changed as it matured:

Do not copy a newer apiVersion into a cluster whose CRDs do not serve it. During the 1.17 transition, update manifests to v1; v1beta1 remains temporarily supported.

Migrate Legacy Policy Kinds

ClusterPolicy and CleanupPolicy are deprecated in 1.17. They remain functional, receive only critical fixes in 1.18 and 1.19, and are planned for removal in 1.20. Write new policies with the specialized CEL v1 APIs. Translate legacy validate.pattern rules into ValidatingPolicy CEL expressions.

Read Reports from OpenReports

Starting in 1.15, Kyverno writes PolicyReport resources in the openreports.io API group. Upgrade Reports Server, Policy Reporter, and custom integrations that still read wgpolicyk8s.io; that legacy group is planned for deprecation.

Treat Policy HTTP as Privileged I/O

In 1.18, HTTP CEL calls are constrained by configurable address allowlists and blocklists. Unsafe destinations such as loopback and metadata services are blocked by default. Namespaced policies cannot make HTTP calls unless explicitly enabled, and outbound calls use a separately scoped token.

Plan Frequent Patch Upgrades

From 1.18, community patch support covers the current and immediately previous release for roughly three months. Patches in that window are limited to critical or high-severity CVEs and other critical fixes.

Choose the Specialized Policy Kind

Namespaced validating, deleting, and image-validating kinds arrived in 1.16. Namespaced mutation and generation arrived in 1.17. Use namespaced kinds when team ownership and narrower RBAC are required; their effects stay within their namespace.

Existing ClusterPolicy resources remain supported during migration. A ValidatingPolicy can generate a native Kubernetes ValidatingAdmissionPolicy, and a MutatingPolicy can generate a native MutatingAdmissionPolicy, moving compatible admission work into the API server.

Quick Policy Patterns

CEL Validation

apiVersion: policies.kyverno.io/v1
kind: ValidatingPolicy
metadata:
  name: cap-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]

Apply-Configuration Mutation

MutatingPolicy supports CEL-computed ApplyConfiguration patches, offline CLI mutation, Kyverno CEL libraries, and native admission-policy generation.

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

CEL Generation

GeneratingPolicy supports loops and custom CEL libraries. generator.Apply(namespace, resources) can create resources in a target namespace, including cloning a source Secret when a Namespace is created.

generator.Apply(object.metadata.name, [variables.sourceSecret])

Scheduled Deletion

DeletingPolicy is the CEL counterpart to CleanupPolicy. It evaluates existing resources on spec.schedule and deletes objects that match its constraints and conditions.

spec:
  schedule: "0 1 * * *"
  conditions:
    - name: isOld
      expression: now() - object.metadata.creationTimestamp > duration("72h")

Use Narrow Exceptions

The CEL-era PolicyException selects policies with spec.policyRefs and resources with CEL matchConditions. Since 1.16 it can also supply approved image patterns through spec.images and arbitrary values through spec.allowedValues.

Consume those values as exceptions.allowedImages and exceptions.allowedValues in the referenced policy. This bypasses only a specific image or value instead of exempting the entire resource.

spec.reportResult controls the recorded result for a match. The default is skip; set it to pass when report consumers require a passing outcome.

Use Extended CEL Deliberately

Kyverno CEL policies can read live Kubernetes resources, call external HTTP services, parse admission users and image references, use cached GlobalContextEntry data, and inspect OCI registry metadata. Later additions include hashing, rounding, X.509 decoding, random strings, list-to-map conversion, JSON/YAML parsing, time helpers, and gzip operations.

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

Audit every expression for permissions, network policy, failure behavior, and offline-test fidelity. See the CEL reference for exact function names.

Verify Images with the Right API

Prefer ImageValidatingPolicy for new image verification. It can:

• select image references using globs or CEL;
• verify signatures and attestations such as SBOMs;
• extract images from arbitrary JSON payloads;
• obtain certificates dynamically through CEL;
• use Cosign v3 verification features.

For legacy ClusterPolicy image verification in 1.18, imageRegistryCredentials.secrets accepts namespace/name references, and Kyverno automatically tries a Pod's imagePullSecrets.

Test Before Admission

Use kyverno apply and kyverno test for pre-cluster checks. The CLI evaluates CEL validating and image policies against Kubernetes resources or arbitrary JSON payloads. By 1.18 it also handles cleanup policies, HTTP and Envoy authorization policies, and mutateExisting rules in MutatingPolicy.

Use --exceptions-with-policies for policy-exception test workflows. Remember that offline evaluation may need explicit context for live resource reads, HTTP, registry data, or dynamically supplied certificates.

Control Reporting and Event Volume

• Label a policy reports.kyverno.io/disabled with any value to suppress both ephemeral and persisted reports without disabling enforcement.
• Use --allowedResults to limit which result classes are stored; retaining only Fail can substantially reduce etcd load.
• Use the successEventActions ConfigMap parameter to reduce successful-policy Event noise without suppressing failure reporting.

CEL policy reports identify the producing policy type and attach owner references to evaluated resources. CEL policies emit Events for passes, violations, evaluation errors, and compile/load failures.

Observe and Operate

Execution-duration histograms exist for validating, mutating, generating, and image-validating CEL policies. Their labels describe policy, background mode, resource kind and namespace, request operation, execution path, and result; validating metrics also distinguish enforce from audit.

In 1.18, the admission controller supports memory-based HPA autoscaling and the /metrics endpoint supports TLS. Coordinate scrape configuration and certificates when enabling metrics TLS.

For Envoy or service-edge enforcement, use the Kyverno Authz Server as an External Authorization endpoint or standalone HTTP authorization service. The companion Go SDK can compile and evaluate policies and expose structured allow/deny results with optional metrics and hooks.