ValidatingPolicy Engine (vpolengine)#

Kyverno maintains two separate validation pipelines: the legacy engine for Policy/ClusterPolicy resources, and a distinct CEL-based engine (vpolengine) for ValidatingPolicy and NamespacedValidatingPolicy resources. They diverge in their type systems, response structures, and how enforcement intent is expressed. Understanding this split is essential when adding features, wiring admission handlers, or processing policy evaluation results.

Location#

The vpolengine lives under pkg/cel/policies/vpol/engine/:

The shared generic building blocks (Engine[T], EngineRequest, EngineResponse) are in pkg/cel/engine/.

Generic Engine Interface#

The engine is built on a Go generic interface defined in pkg/cel/engine/engine.go. For ValidatingPolicies the concrete alias instantiates the generic over policiesv1beta1.ValidatingPolicyLike 1. The predicate parameter (func(T) bool) lets callers filter which policies are evaluated at call time.

EngineResponse — vpolengine vs. legacy#

These two response types are not interchangeable:

The legacy api.EngineResponse exposes GetValidationFailureAction() which walks kyvernov1.Spec.ValidationFailureAction and override lists 2. For VAP-based resources (including ValidatingAdmissionPolicy), this method explicitly returns an empty string 3.

ValidationAction vs. ValidationFailureAction#

ValidationAction values are sourced from spec.ValidationActions() on the ValidatingPolicySpec 4. The legacy ValidationFailureAction is declared in api/kyverno/v1/spec_types.go, with Enforce and Audit as the canonical casing and deprecated lowercase aliases.

Internal Policy Struct#

Each compiled policy carried by the vpolengine is represented as a Policy struct with three fields: Actions (sets.Set[admissionregistrationv1.ValidationAction]), Policy (the API object), and CompiledPolicy (CEL-compiled rules). Actions is pre-computed at reconcile time so the Handle() hot-path does not re-read the spec on every request. The same action set is echoed into ValidatingPolicyResponse.Actions so consumers can apply enforcement decisions without re-fetching the policy.

Provider and Reconciliation#

Two provider modes are available 5:

• NewProvider — static list, compiles all policies upfront (used in CLI / background scan pipelines).
• NewKubeProvider — spins up two controller-runtime controllers, one for ValidatingPolicy and one for NamespacedValidatingPolicy, with optional PolicyException watch 6.

The reconciler skips policies whose status.generated == true (auto-generated policies are managed separately) and compiles autogen variants using autogen.Autogen() 7.

Evaluation Flow#

When Handle() is called 8:

1. Fetches all compiled policies from the Provider.
2. For JSON payload requests, evaluates directly without admission attributes.
3. For admission requests, builds admission.Attributes from the AdmissionRequest, resolves the namespace object, then calls handlePolicy per policy.
4. handlePolicy runs match constraints, calls CompiledPolicy.Evaluate(), and maps the EvaluationResult to engineapi.RulePass, RuleSkip, RuleFail, or RuleError.
5. On a fail with a known validation index, the zero-based index of the failing CEL expression is stored in the cel.validationIndex annotation 9.

Exceptions are resolved during compilation (reconcile time), not at evaluation time. When exceptions are present the highest-priority exception (by label LabelPolicyExceptionPriority) determines whether the rule is skipped or passed 10.