Background Controller UpdateRequest Processing#

Overview#

The Kyverno background controller processes UpdateRequest (UR) CRDs to execute mutateExisting and generateExisting rules against live cluster resources — outside the admission webhook flow. This article covers how URs are initialized (by the policy controller on policy add/update), how triggers are matched against policy criteria (including the operations field), and key bugs and fixes specific to CEL-based (MutatingPolicy/GeneratingPolicy) pipelines.

UpdateRequest Types and Creation#

There are three UR types relevant to background processing:

CEL mutate URs (CELMutate) are created by newCELMutateUR() / newCELMutateURFromNamespacedPolicy() in pkg/policy/mpol.go, added by PR #16255.

All URs live in the Kyverno namespace with a ur- generateName prefix 1. Mutate URs are deduplicated via label-based lookup with MutateLabelsSet(policyKey, trigger) before creation 2. Generate URs do not have an equivalent per-trigger dedup guard 3.

Policy Controller: Initializing URs on Policy Events#

mutateExisting#

handleMutate() fires when a ClusterPolicy/Policy is added or updated. For each rule with HasMutateExisting() and MutateExistingOnPolicyUpdate: true, it:

1. Calls getTriggers() to list candidate trigger resources by kind/namespace selector.
2. Calls listMutateURs(policyKey, trigger) and skips creation if a UR already exists (deduplication).
3. Calls handleUpdateRequest() → engine.ApplyBackgroundChecks() to validate the trigger actually matches the rule before creating the UR.

generateExisting#

handleGenerateForExisting() iterates rules with generateExisting: true (rule-level or policy-level). Per trigger it builds a PolicyContext via common.NewBackgroundContext() and calls engine.ApplyBackgroundChecks() 4 to filter non-matching resources before appending to the UR's RuleContext. URs are then batched at 100 entries (generateBatchSize) to avoid etcd size limits 5.

PolicyContext Construction: NewBackgroundContext()#

NewBackgroundContext() builds the engine.PolicyContext for background rule evaluation:

• With an AdmissionRequest in the UR context: calls engine.NewPolicyContextFromAdmissionRequest(), extracting new/old resources from the raw request body .
• Without an AdmissionRequest: calls engine.NewPolicyContext() using the operation stored in urContext.AdmissionRequestInfo.Operation 7.
• Validates the admission-request resource matches the live trigger resource (name/namespace/kind/apiVersion check via check()).
• Sets WithAdmissionOperation(false) to mark the context as background 8.

Operation Field Handling in Match/Exclude#

MatchesResourceDescription() is the entry point for matching a resource against a rule's match/exclude blocks. It delegates to doesResourceMatchConditionBlock(), which checks the operations field first 9:

if len(conditionBlock.Operations) > 0 {
    if !slices.Contains(conditionBlock.Operations, operation) {
        return []error{"operation does not match"}
    }
}

In background contexts, the operation value comes from urContext.AdmissionRequestInfo.Operation — which for policy-controller-initiated URs is typically empty/"". If a rule's match block specifies operations: [CREATE], the resource will fail to match unless the UR carries a valid Operation. This is the root cause of the CEL-policy operation field bug fixed by PR #16255.

CEL-Based Policy Fixes (PR #16255)#

PR #16255 wired MutatingPolicy and NamespacedMutatingPolicy into the background controller's UR pipeline and fixed three specific issues:

1. Synthetic AdmissionRequest for Background URs#

Background-scan URs carry no admission request. The fix in pkg/background/mpol/processor.go constructs a synthetic AdmissionRequest per target resource, setting Operation: Update and populating Object.Raw, Kind, Resource, Namespace, and Name. This ensures CEL variables like request.object correctly reflect the target 10.

2. NamespacedMutatingPolicy API Routing#

The cluster-scoped MutatingPolicy API rejects "namespace/name" keys with a 404. GetPolicy() now routes namespace/name keys directly to the NamespacedMutatingPolicy API. For backward compatibility with older URs that store bare policy names, a fallback uses AdmissionRequest.Namespace to locate the namespaced policy 10.

3. Scope Predicate from Resolved Policy Object#

The processor derives the scopePredicate from the resolved policy object, not from the UR key. This prevents a same-named MutatingPolicy (cluster-scoped) and NamespacedMutatingPolicy from cross-matching each other's targets 10.

CEL Namespace Resolution Bug (Issue #16953)#

A separate, still-open bug affects MutatingPolicy background evaluation. Evaluate() (called by pkg/background/mpol/processor.go) passes nil as the namespace argument to handlePolicy(), while the admission-path Handle() resolves the namespace via nsResolver. Consequently 11:

• namespaceSelector is silently ignored during background mutation — the selector is evaluated against a nil namespace and always passes.
• The namespaceObject CEL variable is always null in background contexts.

The proposed fix mirrors Handle()'s namespace resolution in Evaluate() 11.

Trigger Validation and the UID/Name Fallback#

GetTrigger() resolves the trigger resource in three ordered tiers: UID-based list-and-scan → name-based direct fetch → raw AdmissionRequest body 12. The UID fallback is silent: if no live resource matches the UR's stored UID, the controller proceeds with any same-named resource. This can cause generate rules to fire against the wrong resource (Issue #16566, unfixed as of v1.18.1) 12.

Key Files#