Skip to main content
In this lesson we’ll explore Kyverno’s architecture and how it integrates with the Kubernetes API server during admission control. This installment focuses on request flow (authentication → authorization → admission) and where Kyverno plugs into that lifecycle. We will not write policies here — instead, we’ll understand how API requests are intercepted, mutated, or validated by Kyverno.
Lesson goal: Understand how the Kubernetes API server routes admission requests to Kyverno webhooks, what webhook configuration controls, and how mutation and validation are ordered during admission.
When a client submits an API request (for example, creating a Pod or Deployment), the Kubernetes API server performs:
  1. Authentication — verifies the identity of the caller.
  2. Authorization — checks whether the caller is allowed to perform the requested action.
  3. Admission — a pluggable phase where requests can be mutated or validated before persistence.
Kyverno participates in the admission phase using admission webhooks. It registers MutatingWebhookConfiguration and ValidatingWebhookConfiguration resources so the API server knows which requests to forward to Kyverno.
The image explains Kyverno's role in admission control, detailing how an API server calls Kyverno using mutating and validating webhooks for changes and checks. It includes a flowchart of the admission controller phases, showing interactions with webhooks during mutating and validating admissions.
How Kyverno handles a forwarded request:
  • The API server sends the request payload to Kyverno’s webhook endpoint.
  • Kyverno locates policies that match the resource kind, namespace, and operation.
  • For mutating policies, Kyverno computes patches and returns them so the API server applies the mutation.
  • For validating policies, Kyverno returns an allow or deny decision.
  • The API server proceeds using Kyverno’s response (apply mutation, accept, or reject).
The image outlines Kyverno's role in admission control, showing how the API server interacts with Kyverno via MutatingWebhookConfiguration and ValidatingWebhookConfiguration. It also illustrates the phases of the admission controller process including mutating and validating admissions.
Webhook configuration essentials Webhook resources are regular Kubernetes objects. They instruct the API server:
  • WHAT to intercept (which resources, operations, API groups/versions).
  • WHERE to send the request (the service/endpoint hosting the webhook).
  • WHAT IF the webhook does not respond (failure behavior and timeouts).
The image explains webhook configuration with three steps: intercepting specific resources and operations, specifying the service endpoint for Kyverno, and handling failures with a failure policy.
Choosing a failure policy
  • failurePolicy: Fail — if Kyverno is unavailable, the API server rejects the request (more secure).
  • failurePolicy: Ignore — if Kyverno doesn’t respond, the API server continues without enforcement (more available).
Set failurePolicy: Fail only when Kyverno is deployed with sufficient high availability. Using Fail in single-replica or unstable Kyverno setups can block legitimate requests during outages.
Ordering: mutation before validation Admission webhooks run in phases. Mutating webhooks are invoked first (and can change the object), followed by validating webhooks which evaluate the final object state. This ordering ensures validation policies assess the object after all mutations have been applied. Example scenario:
  • Mutating policy: add a label to every new Deployment.
  • Validating policy: reject Deployments with more than 2 replicas.
When a Deployment is created, Kyverno will first add the label (mutating phase), then validate the final Deployment object (validating phase). If the replica count exceeds 2, the API server will reject the request.
The image illustrates a workflow for deployment mutation and validation, detailing two policies: one for mutating deployments to add a label and another for validating the replica count. It involves steps using mutating and validating webhook configurations to ensure proper validation.
Example ValidatingWebhookConfiguration Below is a simplified ValidatingWebhookConfiguration demonstrating the WHAT / WHERE / WHAT IF mapping. Note how rules selects requests, clientConfig points to the Kyverno service endpoint, and failurePolicy/timeoutSeconds control error handling.
Automatic webhook registration by Kyverno You do not need to create these webhook configurations manually. Kyverno automatically inspects policies you apply and generates or updates the appropriate MutatingWebhookConfiguration and ValidatingWebhookConfiguration objects. When policies are removed, Kyverno cleans up the webhook rules it created.
The image outlines the automatic webhook registration process with four steps: writing a Kyverno policy, examining resource kinds, creating configurations, and instructing the API server.
References and further reading Summary
  • Kyverno integrates with the API server via Mutating and Validating webhooks during the admission phase.
  • Webhook configuration controls WHAT is intercepted, WHERE the API server sends requests, and WHAT IF the webhook fails.
  • Mutations run before validations, so validation policies evaluate the final mutated object.
  • Kyverno automatically manages webhook registration based on the policies you create.
This concludes Part 1 of the Kyverno architecture series.

Watch Video