Kubernetes Admission Webhooks

Kubernetes Admission Webhooks as the name suggests are a kind of webhooks that do some processing based on some events.

If you’ve worked with Kubernetes, you know it’s great at managing containers. But what if you want to control what gets deployed in your cluster? That’s where Admission Webhooks come in!

Think of them as security guards of k8s which checks incoming requests before they enter a Kubernetes cluster. They can approve, modify, or reject resources like Pods, Deployments, and more.

The Problem

We were facing an issue where we wanted to add specific labels to all the pods for monitoring purposes. Now, it is not possible to ask every developer to include these pod labels in their YAML files and as the new changes or the new YAML files come up, developers might forget to add the same.

Hence, now the problem occurs how can we resolve this – There comes the role of Admission Webhooks.

The Solution

• Create a webhook that will check for the pod creation request.
• Add labels on pod creation requests.

In this blog, we’ll break down:
✅ What Admission Webhooks are
✅ The two types of webhooks
✅ How to enable Mutating Admission Webhooks?
✅ Architecture

What Are Kubernetes Admission Webhooks?

Admission Webhooks are custom webhooks that let you control and modify API requests before Kubernetes stores them. They act as gatekeepers, ensuring that only valid and secure configurations are deployed.

They are part of the Kubernetes Admission Controllers, which evaluate requests after authentication and authorization but before they are stored in etcd (the Kubernetes database).

Types of Admission Webhooks

1️⃣ Mutating Admission Webhooks

• As the name suggests, it modifies a request before saving it in Kubernetes.
• For Example: Automatically adding labels or sidecar containers to a Pod.

2️⃣ Validating Admission Webhooks

• Verify and Validate a request before storing it.
• Example: Rejecting Pods that use the root user for security reasons.

In simple words, we can think of mutating webhooks as “fixing errors” before submission, while validating webhooks as “checking if the request is allowed.”

🔹 Webhook Request (How Kubernetes Calls the Webhook)

• The API server sends a POST request with Content-Type: application/json.
• This request contains an AdmissionReview object, which provides details about the API request being checked.
• This request asks the webhook whether the action (scaling my-deployment) should be allowed or modified.

🔹 Webhook Response (How the Webhook Replies to Kubernetes)

The webhook must reply with:
✅ HTTP 200 status
✅ A response in JSON format
✅ An AdmissionReview object with a decision (allow or deny)

📌 Minimal Response to Allow a Request:

When a Mutating Admission Webhook modifies a request, it must use JSON Patch (patchType: JSONPatch) in its response. Kubernetes does not support other patch formats for this purpose.

Key Points:

✅ The patchType must be JSONPatch (other patch types are not supported).
✅ The patch field contains a Base64-encoded JSON Patch array describing the modifications.
✅ JSON Patch follows RFC 6902, using operations like "add", "replace", and "remove".

Understanding JSON Patch in Simple Terms 🚀

Imagine you have a document written in JSON, like a to-do list. A JSON Patch is a way to make specific changes to that document without rewriting the whole thing.

🔹 How JSON Patch Works

JSON Patch is like a set of instructions that tells Kubernetes:
✅ What to change
✅ Where to change it
✅ How to change it

Instead of sending a new version of the whole document, we only send the changes! This makes updates faster and more efficient.

Example: Modifying an Incoming Request

If a user submits a Deployment without a label, the webhook can inject a default label using JSON Patch:

[
  {
    "op": "add",
    "path": "/metadata/labels/environment",
    "value": "production"
  }
]

📌 This operation adds "environment": "production" to the labels.

How to enable Mutating Admission Webhooks?

If your Mutating Admission Webhooks are not enabled, you need to ensure that the MutatingAdmissionWebhook plugin is included in the Kubernetes API server configuration.

By default, most Kubernetes distributions enable this, but if it’s missing, you can enable it manually.

To do this, modify the API server startup flags and add MutatingAdmissionWebhook to the --enable-admission-plugins list.

kube-apiserver --enable-admission-plugins=NamespaceLifecycle,LimitRanger ...

If you are using kubeadm, edit the API server manifest file located at /etc/kubernetes/manifests/kube-apiserver.yaml and update the command section like this:

spec:
  containers:
  - command:
    - kube-apiserver
    - --enable-admission-plugins=MutatingAdmissionWebhook,ValidatingAdmissionWebhook

After making the changes, restart the API server by running:

sudo systemctl restart kubelet

Architecture of Admission Webhooks

Conclusion

Kubernetes Admission Webhooks provide a powerful way to enforce security policies, automate resource modifications, and enhance cluster governance. By leveraging Mutating Webhooks, you can dynamically modify workloads before they are created while Validating Webhooks helps enforce compliance by rejecting misconfigured resources.

Simran Gera

I’m a DevOps Engineer with 3 years of experience, passionate about building scalable and automated infrastructure. I write about Kubernetes, cloud automation, cost optimization, and DevOps tooling, aiming to simplify complex concepts with real-world insights. Outside of work, I enjoy exploring new DevOps tools, reading tech blogs, and play badminton.