MutatingPolicy Resource Targeting#

Overview#

Kyverno supports two distinct MutatingPolicy resource kinds:

1. MutatingPolicy / NamespacedMutatingPolicy — CEL-based policy types from github.com/kyverno/api/api/policies.kyverno.io/v1beta1. These are the newer, dedicated mutation-only resources.
2. Mutation rules inside Policy / ClusterPolicy — The classic Kyverno v1 approach where mutation is one rule type (mutate) within a unified policy.

This article covers both. The CEL-based MutatingPolicy is the newer, purpose-built kind; the v1 Policy/ClusterPolicy remains the established approach for patch-based mutations.

CEL-based MutatingPolicy (policies.kyverno.io/v1beta1)#

Resource Kinds and Scope#

Both share the same MutatingPolicySpec (defined in v1alpha1, re-exported as type aliases in v1beta1) 1.

MutatingPolicySpec Fields#

Source: api/policies.kyverno.io/v1alpha1/mutating_policy.go 2. Note that v1beta1 re-exports MutatingPolicySpec and related types as aliases from v1alpha1 1.

matchConstraints (Admission Resource Targeting)#

matchConstraints maps directly to the Kubernetes admissionregistrationv1.MatchResources type 2. It contains:

• resourceRules — []NamedRuleWithOperations: specifies apiGroups, apiVersions, resources, operations (CREATE, UPDATE, etc.), and optional resourceNames.
• excludeResourceRules — same structure; resources matching these rules are excluded.
• namespaceSelector — *metav1.LabelSelector: filters by namespace labels.
• objectSelector — *metav1.LabelSelector: filters by object labels.
• matchPolicy — Exact or Equivalent (how API versions are matched).

This is identical to the matchConstraints field on a Kubernetes MutatingAdmissionPolicy.

targetMatchConstraints (MutateExisting Targeting)#

targetMatchConstraints is a TargetMatchConstraints struct that extends admissionregistrationv1.MatchResources with an additional CEL expression field 2:

type TargetMatchConstraints struct {
    Expression string `json:"expression,omitempty"` // CEL expression for target selection
    admissionregistrationv1.MatchResources `json:",inline"`
}

When spec.evaluation.mutateExisting.enabled is true, this field identifies existing resources to mutate. If targetMatchConstraints is absent, Kyverno uses matchConstraints to select existing targets 2.

matchConditions#

CEL expressions evaluated after resource matching. A request is only processed if all conditions evaluate to true. Useful for fine-grained filtering that can't be expressed with label selectors alone 2.

Evaluation Configuration#

spec.evaluation (MutatingPolicyEvaluationConfiguration) controls when the policy runs 2:

• admission.enabled — default true; toggles admission-time mutation.
• background.enabled — default true; toggles background scan mutations.
• mutateExisting.enabled — default false; must be set to true to activate existing-resource mutation via targetMatchConstraints.
• skipBackgroundRequests — default true; skips requests from the background controller.

Classic Policy/ClusterPolicy Mutation Rules (kyverno.io/v1)#

In the v1 API, mutation is configured via a mutate block inside a Rule. The Rule.match field drives resource targeting.

MatchResources (Rule-level)#

Defined in match_resources_types.go. The MatchResources struct supports two patterns:

The any/all pattern is preferred. any and all cannot be used simultaneously 3.

ResourceDescription Fields#

Defined in resource_description_types.go:

Mutation Targets (mutateExisting)#

For existing-resource mutation (outside of admission), the Mutation struct has a targets field 4:

Targets []TargetResourceSpec `json:"targets,omitempty"`

TargetResourceSpec (defined in resource_spec_types.go) contains:

The presence of targets is what distinguishes a mutateExisting rule — r.Mutation.Targets != nil 5. For namespaced policies, target namespaces must match the policy's own namespace 6.

GenericPolicy Abstraction#

Both kinds are unified under the GenericPolicy interface in pkg/engine/api/policy.go. The engine calls AsMutatingPolicyLike() to retrieve a MutatingPolicy or NamespacedMutatingPolicy, and AsKyvernoPolicy() for v1 Policy/ClusterPolicy objects. Constructor functions NewMutatingPolicy, NewNamespacedMutatingPolicy, and NewMutatingPolicyFromLike wrap these types.

Key Source Files#