Background Controller Trigger Validation#

The background controller resolves trigger resources for UpdateRequest processing using a multi-tier fallback strategy. The entry point is GetTrigger(), which routes to operation-specific helpers or directly to GetResource() depending on whether an AdmissionRequest is present and what operation it represents.

How Trigger Resolution Works#

GetResource() implements the core lookup in three ordered tiers 1:

1. UID-based list-and-scan (lines 95–105): If the ResourceSpec carries a non-empty UID, the function calls client.ListResource() for the given API version, kind, and namespace, then scans items for a UID match.

2. Name-based direct fetch (lines 106–121): If UID is absent or if the UID scan returns no match, the function falls through to a client.GetResource() call by name. There is no error or warning emitted when the UID scan fails to match — execution silently proceeds to the name lookup.

3. Admission request raw body (lines 123–136): If neither lookup returns a resource and an AdmissionRequest is attached to the UpdateRequestSpec, the trigger is reconstructed from the raw object bytes in the request body.

The Silent Fallback: A Correctness Concern#

When a UID is present but no live resource matches it (e.g., the triggering resource was deleted, or the admission request was rejected by the API server), GetResource() does not surface an error — it silently falls through to the name-based lookup 2. This means the controller may act on a different resource that shares the trigger's name but not its UID.

This creates a known correctness bug 3. Consider the following scenario:

• A CREATE Namespace admission request is issued by helm install --create-namespace against an already-existing namespace.
• Before the API server rejects the request with AlreadyExists, Kyverno's admission webhook has already processed it: a mutate policy defaults a label (e.g., layer: business) onto the phantom object, which then matches a generate rule and enqueues an UpdateRequest.
• The UR stores the phantom UID (spec.ruleContext[].trigger.uid) — different from the live namespace's UID.
• The API server rejects the CREATE; the UR survives.
• The background controller calls GetResource(), finds no UID match for the phantom UID, and silently falls back to the name-based fetch — returning the live namespace, which has layer: operational and does not satisfy the rule's selector.
• The generate rule executes and creates the downstream resource (e.g., a LimitRange) in the live namespace.

The UpdateRequest itself contains all data needed to detect the mismatch — spec.context.admissionRequestInfo.admissionRequest.object.metadata.uid — but no comparison is performed before UR execution 3.

Downstream Cleanup: The Same Pattern#

The same UID → name fallback exists in the generate cleanup path. getDownstreams() builds a label selector that includes generate.kyverno.io/trigger-uid 4, then calls fetch(). If FindDownstream() returns an empty list for the UID selector, fetch() removes the trigger-uid label, substitutes generate.kyverno.io/trigger-name, and re-queries 5 — with no validation that the name-matched resources actually belong to the original trigger. An identical fallback applies to CloneList resources 6.

The trigger labels themselves are stamped onto generated resources via TriggerInfo(), which sets both the trigger-uid and trigger-name labels. The 63-character label value limit causes trigger names to be trimmed — this is the historical reason the name-based fallback exists, to handle resources whose trimmed name-label would not match a full UID search.

Key Files#

Known Issue & Workarounds#

Issue #16566 3 documents the bug. Confirmed in Kyverno v1.16.x through v1.18.1; no fix merged as of July 2026.

Suggested fix (from issue): before executing a generate UR, the background controller should fetch the trigger object from the cluster, compare its UID to the UR's stored trigger UID, and mark the UR Skipped or Failed on mismatch rather than proceeding.

Operational workarounds 3:

• Guard mutate defaults with an apiCall precondition that checks whether the resource already exists in the cluster, so phantom objects never receive matching labels.
• Use apiCall-based preconditions in generate rules that read live resource labels instead of relying on request.object.