Skip to main content
When you need ongoing cluster housekeeping, scheduled, rule-based cleanup policies are ideal. But for resources that are known to be temporary at creation time — for example, a debug Pod, a short-lived namespace for a CI job, or a one-off test resource — Kyverno provides a simple, per-resource mechanism: the reserved label cleanup.kyverno.io/ttl. How it works
  • Add the cleanup.kyverno.io/ttl label to a resource’s metadata at creation time.
  • The Kyverno Cleanup Controller watches for that label, records the resource and its expiration, and deletes the resource when the TTL has passed.
The image illustrates the process of using the cleanup.kyverno.io/ttl label on Kubernetes resources, explaining how Kyverno handles cleanup by identifying the label, calculating expiration time, and deleting the resource when time is up.
No policy required Important: you do not need a cleanup policy for this to work. The presence of the cleanup.kyverno.io/ttl label on the resource itself is the instruction — the label triggers the Cleanup Controller to act. TTL value formats Kyverno supports two TTL value formats:
The image explains two supported TTL value formats in Kyverno: "Relative Duration," which specifies a time duration from when the label is seen, and "Absolute Timestamp (ISO 8601)," which specifies a specific UTC date and time for resource deletion.
Choose a relative duration when you want the countdown to start at creation time. Use an ISO 8601 timestamp when you require deletion at a precise UTC moment.
Practical example A developer needs a temporary Pod to debug an issue and wants to ensure it is cleaned up automatically. Add the TTL label to the Pod manifest:
When created, the Cleanup Controller records the resource and schedules deletion after two minutes. The container’s internal runtime does not prevent Kyverno from deleting the Pod when the TTL expires. Permissions and RBAC The TTL label is a trigger; the Cleanup Controller performs the actual deletion. Therefore, the controller must have the appropriate RBAC permissions to delete the resource type you label.
  • Label a Pod for deletion → the controller must have delete permission on pods.
  • Label a Deployment for deletion → the controller must have delete permission on deployments.
The image is a reminder about permissions for labeling in a system. It explains that when using a TTL label, the controller requires permission to delete Pods or Deployments.
Ensure the Kyverno Cleanup Controller’s ClusterRole (or aggregated role) includes the delete verb for every resource type you want TTL-based cleanup to manage. Missing delete permission prevents Kyverno from removing labeled resources.
The permission model is unified: the same aggregated ClusterRole that grants delete permissions for cleanup policies also covers TTL-based deletions. Grant the appropriate permissions once and both mechanisms will work. Reconciliation and timing guarantees A TTL like 90 seconds is respected, but deletion may not occur at the exact second the TTL expires. For efficiency, the Cleanup Controller reconciles periodically rather than continuously scanning all labeled resources. Example timeline:
  • Controller runs at 1 minute — sees the Pod but not expired.
  • TTL expires at 90 seconds — controller is not running at that exact moment.
  • Next controller run (e.g., 2 minutes) — controller detects the expired Pod and deletes it.
This periodic schedule is called the reconciliation interval and is configurable on the controller (default: 1m).
The image is titled "Fine-Tuning: The Reconciliation Interval" and features a question about TTL deletion timing, with an answer explaining that the Cleanup Controller runs on a schedule, not checking every second.
You can adjust the controller behavior with the --ttlReconciliationInterval flag (or corresponding configuration), for example:
Smaller intervals yield closer-to-exact deletion timing at the cost of more frequent controller reconciliation.
The image provides technical details about the "Reconciliation Interval," including its configuration using the --ttlReconciliationInterval flag in the Kyverno cleanup controller, and states that the default value is 1 minute.
When to use each cleanup method Use the method that best fits your workflow:
The image is a comparison table outlining when to use the methods "CleanupPolicy" and "cleanup.kyverno.io/ttl Label," detailing aspects such as how each works, triggers, who defines them, and best use cases.
Summary
  • Use cleanup policies for administrator-defined, rule-driven housekeeping across the cluster.
  • Use cleanup.kyverno.io/ttl for per-resource, explicit expiration when resources are known to be temporary at creation time.
Further reading and references

Watch Video