Skip to main content
Alex kept finding orphaned ConfigMaps and leftover debug resources across clusters. The solution is a dedicated Kubernetes policy type designed specifically for deletion workflows. In this lesson we focus on one of two cleanup approaches: the declarative, background-driven model implemented via cleanup policies. Before we dive into the policy details, let’s review how Kyverno components interact — we are introducing a new piece to this picture.
  • The admission controller intercepts kubectl apply (and other admission) requests and runs your validate, mutate, and verifyImages rules.
  • The background controller handles generate rules and mutate existing policies that must act on already-existing resources.
  • Today we add a third component: the cleanup controller.
The image outlines a "Cleanup Controller" with three sections: "Admission Controller," "Background Controller," and "Cleanup Controller," each describing specific rule-related tasks.
What the cleanup controller does The cleanup controller processes cleanup policies on a schedule you define. On each run it asks a single question for every policy: given the policy’s match and conditions, is there anything that needs to be deleted right now?
The image describes a "Cleanup Controller," highlighting its role as a dedicated controller for processing cleanup policies and scheduling resource deletion.
Key points about cleanup policies
  • schedule is required and uses standard cron syntax. It controls when the cleanup controller evaluates a policy.
  • Cleanup policies are not admission-time evaluations. They cannot reference user-specific admission data (for example, roles, clusterroles, or subjects) because that information is only available during admission.
  • Policies run in the background and delete resources that match the match clause and satisfy conditions.
Example: remove stale Deployments This ClusterCleanupPolicy deletes Deployments labeled canremove: "true" when their replica count is less than 2. The policy runs every five minutes.
What each field does
The target variable in condition expressions refers to the matched resource (for example, the Deployment being evaluated). In docs and examples, wrap the expression in backticks: {{ target.spec.replicas }}.
RBAC: explicit permissions required Kyverno does not automatically get blanket permission to delete any resource. By default the cleanup controller runs with minimal privileges (principle of least privilege). Before a cleanup policy is created, Kyverno checks whether the cleanup controller has the RBAC verbs needed to act on the targeted resource kinds.
The image poses a question about whether Kyverno has permission to delete a deployment, with the answer being "NO," and notes that explicit permission must be granted via RBAC.
If RBAC is insufficient, policy creation is rejected and an error will indicate which permission is missing.
The image is a flowchart showing Kyverno's built-in safety check process for deleting a targeted resource, involving RBAC permission verification before proceeding.
Granting permissions safely: RBAC aggregation The recommended way to give the cleanup controller permission is to create a separate ClusterRole and rely on Kubernetes RBAC aggregation. Do not modify Kyverno’s built-in roles directly. Instead, add a ClusterRole with the label rbac.kyverno.io/aggregate-to-cleanup-controller: "true". The API server will merge its rules into the cleanup controller’s role. Example ClusterRole that allows the cleanup controller to manage Deployments:
When this ClusterRole is applied, the API server aggregates its rules into Kyverno’s cleanup controller role — a declarative and auditable approach.
If the cleanup controller lacks aggregated RBAC permissions for the targeted resource kinds, Kyverno will reject creation of the cleanup policy with an error. Ensure the cleanup controller has get, list, watch, and delete (or other necessary verbs) for each targeted kind.
Recap
  • The cleanup controller is a new Kyverno component that processes cleanup policies on a schedule and deletes matched resources.
  • Cleanup policies (ClusterCleanupPolicy and CleanupPolicy) are declarative resources built for deletion workflows.
  • schedule is required and uses cron syntax to control when the cleanup logic runs.
  • You must explicitly grant the cleanup controller RBAC permissions for the resource kinds it will delete — typically via ClusterRole aggregation.
Further reading and references With these concepts and the example policy in hand, you can build safe, automated cleanup workflows for your cluster.
The image is a summary slide highlighting four key points about cleanup processes, including new components, policies, key fields, and prerequisites. The information is presented in a colorful and structured format.

Watch Video

Practice Lab