Admission Webhook Good Practices [page]deterministic

This page provides good practices and considerations when designing _admission webhooks_ in Kubernetes. This information is intended for cluster operators who run admission webhook servers or third-party applications that modify or validate your API requests.

Before reading this page, ensure that you're familiar with the following concepts:

* [Admission controllers](/docs/reference/access-authn-authz/admission-controllers/) * [Admission webhooks](/docs/reference/access-authn-authz/extensible-admission-controllers/#what-are-admission-webhooks)

## Importance of good webhook design {#why-good-webhook-design-matters}

Admission control occurs when any create, update, or delete request is sent to the Kubernetes API. Admission controllers intercept requests that match specific criteria that you define. These requests are then sent to mutating admission webhooks or validating admission webhooks. These webhooks are often written to ensure that specific fields in object specifications exist or have specific allowed values.

Webhooks are a powerful mechanism to extend the Kubernetes API. Badly-designed webhooks often result in workload disruptions because of how much control the webhooks have over objects in the cluster. Like other API extension mechanisms, webhooks are challenging to test at scale for compatibility with all of your workloads, other webhooks, add-ons, and plugins.

Additionally, with every release, Kubernetes adds or modifies the API with new features, feature promotions to beta or stable status, and deprecations. Even stable Kubernetes APIs are likely to change. For example, the `Pod` API changed in v1.29 to add the [Sidecar containers](/docs/concepts/workloads/pods/sidecar-containers/) feature. While it's rare for a Kubernetes object to enter a broken state because of a new Kubernetes API, webhooks that worked as expected with earlier versions of an API might not be able to reconcile more recent changes to that API. This can result in unexpected behavior after you upgrade your clusters to newer versions.

This page describes common webhook failure scenarios and how to avoid them by cautiously and thoughtfully designing and implementing your webhooks.

## Identify whether you use admission webhooks {#identify-admission-webhooks}

Even if you don't run your own admission webhooks, some third-party applications that you run in your clusters might use mutating or validating admission webhooks.

To check whether your cluster has any mutating admission webhooks, run the following command:

```shell kubectl get mutatingwebhookconfigurations ``` The output lists any mutating admission controllers in the cluster.

To check whether your cluster has any validating admission webhooks, run the following command:

```shell kubectl get validatingwebhookconfigurations ``` The output lists any validating admission controllers in the cluster.

## Choose an admission control mechanism {#choose-admission-mechanism}

Kubernetes includes multiple admission control and policy enforcement options. Knowing when to use a specific option can help you to improve latency and performance, reduce management overhead, and avoid issues during version upgrades. The following table describes the mechanisms that let you mutate or validate resources during admission:

<table> <caption>Mutating and validating admission control in Kubernetes</caption> <thead> <tr> <th>Mechanism</th> <th>Description</th> <th>Use cases</th> </tr> </thead> <tbody> <tr> <td><a href="/docs/reference/access-authn-authz/extensible-admission-controllers/">Mutating admission webhook</a></td> <td>Intercept API requests before admission and modify as needed using custom logic.</td> <td><ul> <li>Make critical modifications that must happen before resource admission.</li> <li>Make complex modifications that require advanced logic, like calling external APIs.</li> </ul>< …(trimmed)