ImageValidatingPolicy Webhook Architecture#

ImageValidatingPolicy (ivpol) uses a two-phase webhook design: a mutating webhook first evaluates policies and writes outcomes into resource annotations; a validating webhook then reads those annotations back to make enforcement decisions. This split exists because Kubernetes API server runs mutating webhooks before validating webhooks, guaranteeing the annotations are present by the time enforcement runs. Both cluster-scoped (ImageValidatingPolicy) and namespace-scoped (NamespacedImageValidatingPolicy) policies share the same handler implementations, just served under different URL prefixes.

HTTP Route Registration#

Four routes handle ivpol admission in pkg/webhooks/server.go:

The policy name is embedded in the URL path, allowing the webhook controller to route requests to only the matching subset of policies.

Phase 1 — Mutating Webhook: Evaluate and Record#

The mutating handler (handler.Mutate) calls engine.HandleMutating, which:

1. Matches each policy against the incoming resource using CEL MatchResources constraints.
2. Compiles and evaluates matched policies using the CEL compiler, calling actual image verification functions (cosign/notary signature and attestation verification via pkg/cel/libs/imageverify/impl.go).
3. Handles PolicyExceptions: if a matching exception is found, the result is set to RuleSkip with the exception name in the message 1, recording the skip in the outcome rather than requiring a separate path.
4. Serializes outcomes: MakeImageVerifyOutcomePatch converts all ImageVerifyPolicyResponse results into a JSON map keyed by policy name and produces a JSON Patch that writes the value to the kyverno.io/image-verification-outcomes annotation 2. If the object has no annotations yet, a patch to create the metadata/annotations object is prepended first 3.

The mutating response is always allowed — the mutating phase never blocks admission. Warn-action policies emit warnings on Fail or Error results at this stage 4.

Outcome Annotation Schema#

Each policy maps to an ImageVerificationOutcome object 5:

kyverno.io/image-verification-outcomes: |
  {"my-policy": {"name": "...", "status": "pass|fail|skip|error", "message": "...", "properties": {...}}}

status maps to engineapi.RuleStatus and carries the full pass/fail/skip/error distinction, including exception skips.

Phase 2 — Validating Webhook: Read and Enforce#

The validating handler (handler.Validate) calls engine.HandleValidating, which:

1. Requires the annotation to be present — missing annotations produce an immediate error: "annotations not present on object, image verification failed" 6.
2. Unmarshals the kyverno.io/image-verification-outcomes annotation into a map[string]ImageVerificationOutcome 7.
3. Reconstructs rule responses for each matched policy from the stored outcome, via engineapi.NewRuleResponse(o.Name, o.RuleType, o.Message, o.Status, o.Properties) 8. If a policy is matched but has no entry in the annotation, it is treated as a hard failure ("policy not evaluated").
4. Enforces based on ValidationAction: policies with Deny action cause the admission to be rejected on Fail or Error status; policies with Warn action emit warnings instead 9.

The validating phase also triggers asynchronous side effects: admission report creation and Kubernetes event emission 10.

Hard dependency: The validating webhook unconditionally expects the outcome annotation. If the mutating webhook is disabled or removed for a policy (e.g., because MutateDigest and VerifyDigest are both false), the validating webhook will error on every matching request. Ensure both webhooks are registered or both are absent for a given policy.

Conditional Mutating Webhook Registration#

Not all ivpol policies require a mutating webhook. The webhook controller filters using ivpolsNeedingMutation: a policy is included only if MutateDigest or VerifyDigest is enabled in spec.validationConfigurations (both default to true when unset). Policies with both set to false skip the mutation phase entirely — they rely on a different mechanism and do not need annotation-based outcome recording.

Key Source Files#