> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Kyverno Architecture Part 1
> Overview of Kyverno's integration with the Kubernetes API server via mutating and validating admission webhooks, request flow, webhook configuration, failure policies, and mutation before validation
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.
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).
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).
| Concept | Purpose | Example field |
| ------------------------- | ------------------------------------------------------------------------------- | --------------------------------- |
| WHAT to intercept | Limit which requests are sent to the webhook (improves performance and scoping) | `rules` |
| WHERE to send requests | Kubernetes Service and path that receives admission calls | `clientConfig.service` |
| WHAT IF it doesn't answer | Decide how the API server behaves on webhook failure or timeout | `failurePolicy`, `timeoutSeconds` |
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.
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.
```yaml theme={null}
apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
metadata:
name: kyverno-resource-validating-webhook-cfg
webhooks:
- name: validate.kyverno.svc-fail
rules: # WHAT to intercept
- apiGroups: ["apps"]
apiVersions: ["v1"]
operations: ["CREATE"]
resources: ["deployments"]
clientConfig: # WHERE to send it
service:
name: kyverno-svc
namespace: kyverno
path: /validate/fail
port: 443
timeoutSeconds: 10 # How long to wait for Kyverno
failurePolicy: Fail # WHAT IF it fails (options: Fail, Ignore)
```
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.
References and further reading
* Kubernetes Admission Controllers and Webhooks: [https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/)
* Kyverno documentation: [https://kyverno.io/docs/](https://kyverno.io/docs/)
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.