TTL Controller Lifecycle#

The TTL controller (pkg/controllers/ttl/) garbage-collects Kubernetes resources that carry the cleanup.kyverno.io/ttl label 1. It is a per-GVR controller: one instance is created for each GroupVersionResource that needs TTL-based cleanup.

Reconcile Loop#

The controller is started via Start, which delegates to controllerutils.Run. The reconcileFunc signature receives a cancellable ctx context.Context derived from the controller's root context.

The reconcile method follows this path:

1. Key parsing — splits the item key into namespace/name.
2. Lister lookup — fetches the object from the cache; returns early on NotFound.
3. Deletion guard — returns early if DeletionTimestamp is set (object already terminating) 2.
4. TTL label check — returns early if cleanup.kyverno.io/ttl label is absent 3.
5. Deletion time computation — parseDeletionTime resolves the label value as a duration (added to creation time), ISO 8601 datetime, or date-only string.
6. Branch on expiry:
   • Expired: calls client.Delete with an optional propagation policy derived from the cleanup.kyverno.io/propagation-policy annotation 4. On failure, records a RecordTTLFailure metric.
   • Not yet expired: records a RecordDeletedObject metric and re-enqueues the item with AddAfter for the remaining duration 5.

Context Lifecycle Bug (Fixed in PR #17032)#

Prior to PR #17032, both the client.Delete call and both metric recording calls used context.Background() rather than the reconcile-scoped ctx 67. This was a context leak: if the controller was shut down or the API server became unresponsive, those operations could not be cancelled, potentially causing the controller to hang.

The fix — replacing all three context.Background() calls with ctx — ensures:

• Resource deletion respects controller shutdown signals.
• RecordTTLFailure and RecordDeletedObject metric calls are tied to the reconcile context 8.

Note: The source file snapshot in this KB (commit b3ce4ae) still shows the unfixed context.Background() pattern. The corrected behaviour is in the current main branch after PR #17032 merged on 2026-08-10.

Lifecycle Methods#

Event handlers are registered only for Add and Update events — Delete events are intentionally omitted (passing nil) 9, because a deleted object will simply be absent from the lister on the next reconcile.

Metrics#

The metrics.TTLInfoMetrics interface 10 exposes:

• RecordDeletedObject(ctx, gvr, namespace) — emitted when a living (not-yet-expired) resource is re-enqueued for a future check.
• RecordTTLFailure(ctx, gvr, namespace) — emitted when a Delete API call fails.

Both are OpenTelemetry-backed counters accessed via metrics.GetTTLInfoMetrics() 11.

Key Source Files#