Enhance kyverno oci commands for standard policy and exception bundles

Summary

Evolve the existing kyverno oci commands into Kyverno's standard, interoperable mechanism for packaging, validating, distributing, and consuming versioned CEL policy sets and their PolicyException resources as OCI artifacts.

The public command surface should remain kyverno oci; the artifact should be specified as a versioned Kyverno CEL Policy Bundle OCI Specification. This preserves the existing CLI experience while providing a complete policy-aware bundle contract for CI/CD, GitOps, and controllers.

Scope

This proposal supports only the current CEL policy API family (policies.kyverno.io/v1beta1) and the matching CEL-policy PolicyException resources. The OCI command implementation and bundle specification are CEL-only: deprecated Policy, ClusterPolicy, and their exception model are unsupported, are not packaged or pulled, and have no migration or compatibility path in this work.

Current gap

The current kyverno oci push and kyverno oci pull implementation must be replaced with CEL-only bundle handling. It cannot faithfully distribute a CEL policy set together with its PolicyException resources, preserve source layout, resolve an immutable artifact identity, or validate relationships before publication.

Goals

• Retain kyverno oci as the primary public CLI namespace; avoid introducing a competing top-level command.
• Provide a stable, documented, semver-versioned OCI artifact contract for CEL policy resources.
• Support CEL policy sets and separately governable CEL policy-exception sets, including round-tripping their original YAML files and paths.
• Work with standard OCI registries and generic OCI tooling.
• Be consumable by GitOps systems, including Flux's OCIRepository and Kustomization workflow.
• Make the exact artifact testable, digest-pinnable, and consumable across environments.

Non-goals

• Support deprecated Policy, ClusterPolicy, or their legacy exception APIs.
• Replace GitOps reconciliation. Flux and other controllers should remain able to retrieve and apply the artifact.
• Require clusters to use the Kyverno CLI at runtime.
• Provide migration or backwards compatibility for existing legacy-policy OCI images.

Proposed CLI shape

Use the existing kyverno oci namespace for CEL-aware capabilities:

kyverno oci push ./bundle -i ghcr.io/acme/kyverno-baseline:v1.0.0
kyverno oci pull -i ghcr.io/acme/kyverno-baseline@sha256:... -d ./out
kyverno oci validate ./bundle
kyverno oci inspect -i ghcr.io/acme/kyverno-baseline:v1.0.0
kyverno oci resolve -i ghcr.io/acme/kyverno-baseline:v1.0.0

A bundle descriptor such as kyverno-bundle.yaml may declare bundle format version, bundle name/version, intended Kyverno compatibility, resource-set membership, and source metadata. Directory-only inputs should remain supported for a simple default workflow.

Sub-tasks

• Specify the artifact format. Publish the Kyverno CEL Policy Bundle OCI Specification, including manifest/config/layer media types, OCI annotations, a machine-readable resource index, format-versioning rules, and compatibility guarantees.
• Implement CEL resources only. Replace legacy-policy discovery, validation, push, and pull with support for policies.kyverno.io/v1beta1 CEL policy kinds and their PolicyException resources. Fail deprecated policy kinds and unknown Kubernetes objects with an actionable error; never package or extract them.
• Preserve files and layout. Archive original YAML documents, filenames, directory paths, and multi-document files so pull is a faithful round trip rather than a normalized reconstruction.
• Define CEL policy-set and exception-set semantics. Support named sets through a descriptor and/or subdirectories. Default to separate policy and exception sets; require an explicit option to mix them. Validate duplicate Kubernetes identities.
• Add CEL-aware validation. Implement kyverno oci validate for CEL policy schemas, duplicate identities, PolicyException policy/rule references, expiration, selectors, and declared Kyverno-version compatibility.
• Add artifact inspection and immutable resolution. Implement oci inspect and oci resolve; display the resolved digest, resource index, annotations, source/revision metadata, and compatibility information.
• Enable OCI-native test/apply flows. Allow kyverno test and kyverno apply to consume a digest-pinned OCI reference, so CI can test precisely the CEL-policy artifact that is promoted and deployed.
• Document GitOps interoperability. Provide end-to-end docs and examples for Flux OCIRepository + Kustomization, including media-type/layer selection, digest pinning, and authentication. Keep the format compatible with a generic artifact extraction workflow.
• Add conformance and integration tests. Cover authenticated registry operations, CEL-policy-plus-exception round trips, malformed artifacts, rejection of deprecated and unknown resources, and Flux-compatible extraction.

Flux interoperability

Flux demonstrated the value of using OCI artifacts to distribute Kyverno manifests with its OCIRepository source and Kustomization reconciler: https://fluxcd.io/blog/2022/08/manage-kyverno-policies-as-ocirepositories/

Kyverno should define CEL-policy-aware authoring and validation while preserving interoperability with that generic consumption model. In particular, extracted bundles should be directly usable as Kubernetes manifests by Flux, with documented layer/media-type expectations and a supported archive layout.

Acceptance criteria

1. A user can package a named CEL policy set and its corresponding CEL-policy exception set into OCI artifacts using only kyverno oci commands.
2. push followed by pull preserves original resource content and layout, including PolicyException documents.
3. Validation fails before push for invalid CEL resources, deprecated or unknown resources, duplicate identities, and invalid exception-to-policy/rule references.
4. An OCI tag can be resolved to a digest; downstream test and apply operations accept that digest-pinned reference.
5. Documentation includes a Flux-based, digest-pinned GitOps example that deploys the published CEL policy artifact.
6. The implementation and artifact specification accept, package, and extract only CEL policy types and their PolicyException resources; deprecated Policy and ClusterPolicy resources are rejected.