Migrate Kyverno ClusterPolicy and Policy before Kyverno 1.20 removes them #4984

🤖 Generated by the Agentic Engineer (interactive Claude Code session)

Evidence

• Kyverno 1.19 deprecates ClusterPolicy, Policy, CleanupPolicy, ClusterCleanupPolicy and the legacy kyverno.io PolicyException, calls 1.19 the final release with full support for them, and plans their removal for 1.20, estimated November 2026.
• Production runs Kyverno 1.19.1. The repository has 49 ClusterPolicy manifests and one Policy; they carry almost every admission, mutation and generation rule the platform enforces.
• The dependency rules for Kyverno do not hold it below 1.20, and KSail also installs Kyverno for the cluster (policyEngine: Kyverno), so the version can move from two places.

Problem

Installing Kyverno 1.20 before the policies are migrated would remove the platform's admission rules in one deploy.

Smallest useful change

Cap Kyverno below 1.20 in the dependency rules, with the removal condition recorded beside the cap, and confirm which Kyverno version KSail installs. Then migrate the policies to their replacement kinds in small batches, each validated with the existing policy tests.

Acceptance criteria

• An update cannot propose Kyverno 1.20 while any legacy policy kind remains; the cap names its removal condition.
• Every ClusterPolicy, Policy and legacy exception is migrated, and the policy tests pass on the new kinds.
• The cap is removed and Kyverno 1.20 deployed only after the migration is live.

Size: large — the migration is the bulk; the cap is small.

Refinement (2026-10-17): decomposed

Corrected count. main has 49 kyverno.io/v1 ClusterPolicy manifests (22 validate, 23 mutate, 4 generate; none mixes rule types or uses verifyImages) and no kyverno.io Policy, CleanupPolicy, ClusterCleanupPolicy or legacy PolicyException. The platform already runs two new-style kinds: ImageValidatingPolicy (verify-app-images) and DeletingPolicy (prune-stale-policy-reports). 28 of the 49 are named in no Kyverno CLI test, so each batch starts by pinning current behaviour.

Children, in the order they can start:

• Hold Kyverno below 1.20 while any ClusterPolicy remains #4994 — hold Kyverno below 1.20 while any ClusterPolicy remains, and record what KSail installs. Ready.
• Migrate the tenant and organisation validation ClusterPolicies to ValidatingPolicy #4995 — 12 tenant and organisation validation policies → ValidatingPolicy. Ready.
• Migrate the workload, Flux and provider validation ClusterPolicies to ValidatingPolicy #4996 — 10 workload, Flux and provider validation policies → ValidatingPolicy. Ready.
• Migrate the workload-default and HelmRelease mutation ClusterPolicies to MutatingPolicy #4997 — 11 workload-default and HelmRelease mutation policies → MutatingPolicy. Ready.
• Migrate the production storage-placement mutation ClusterPolicies to MutatingPolicy #4998 — 12 production storage-placement mutation policies → MutatingPolicy. Backlog until the existing-resource handover is decided.
• Migrate the namespace-default generation ClusterPolicies to GeneratingPolicy without a gap #4999 — 4 synchronised generation policies → GeneratingPolicy. Backlog until the handover of the objects they generated is decided.

The last criterion above (remove the cap and install 1.20) follows once every child is closed and 1.20 is released. This issue is now an Epic: it is delivered through its children.