2025 Updates Validating and Mutating Admission Controllers

This lesson explains Kubernetes admission controllers, how they run during API-server request processing, and how to implement and configure webhook-based admission controllers. You’ll learn the difference between validating and mutating controllers, the AdmissionReview protocol the API server uses to call webhooks, and the steps required to deploy and register your webhook. What are admission controllers?

Admission controllers are plugins invoked by the API server after authentication and authorization but before an object is persisted.
They can either mutate the incoming object (mutating admission controllers) or accept/deny the request (validating admission controllers). Some controllers perform both roles.

For example, the NamespaceExists controller validates that a referenced namespace exists; it will reject the request if it does not. The DefaultStorageClass controller mutates PVC creation requests by adding a storageClassName when none is supplied.

A diagram titled "Validating Admission Controllers" showing a Kubernetes request flow: kubelet → Authentication → Authorization → Admission Controllers (NamespaceExists) → Create Pod. The graphic illustrates the checks performed before a pod is created.

Mutating vs Validating — key differences

Type	Behavior	When it runs (convention)	Example
Mutating Admission Controller	Alters the incoming object (adds defaults, injects labels/annotations)	Typically invoked before validators so validators see the final object	`DefaultStorageClass`, `NamespaceAutoProvision`
Validating Admission Controller	Accepts or rejects the request based on policy; does not change the object	Runs after mutating controllers	`NamespaceExists`

Important ordering note: mutating controllers are invoked before validating ones. For instance, a mutating controller that auto-provisions a namespace (NamespaceAutoProvision) must run before NamespaceExists; otherwise, NamespaceExists could reject the request for a non-existent namespace. If any admission controller rejects a request, the API server returns an error and the request is not applied. Webhook-based admission controllers Kubernetes also supports webhook-based admission controllers to allow custom logic hosted as external services:

MutatingAdmissionWebhook — can modify the request using JSONPatch and return patches.
ValidatingAdmissionWebhook — only allows or denies the request.

The API server sends an AdmissionReview object (JSON) to the webhook and expects an AdmissionReview response with a matching uid and an allowed boolean. For mutating webhooks, the response can include a base64-encoded JSONPatch and patchType: "JSONPatch". AdmissionReview request (example)

{
  "apiVersion": "admission.k8s.io/v1",
  "kind": "AdmissionReview",
  "request": {
    "uid": "705ab4f5-6393-11e8-b7cc-42010a800002",
    "kind": { "group": "autoscaling", "version": "v1", "kind": "Scale" },
    "resource": { "group": "apps", "version": "v1", "resource": "deployments" },
    "subResource": "scale",
    "requestKind": { "group": "autoscaling", "version": "v1", "kind": "Scale" },
    "requestResource": { "group": "apps", "version": "v1", "resource": "deployments" }
  }
}

AdmissionReview response (allowed)

{
  "apiVersion": "admission.k8s.io/v1",
  "kind": "AdmissionReview",
  "response": {
    "uid": "705ab4f5-6393-11e8-b7cc-42010a800002",
    "allowed": true
  }
}

If allowed is false, you may include a status with a message explaining why the request was rejected. Two main steps to add a webhook-based admission controller

Deploy the admission webhook server (your logic).
Register the webhook with the API server using a MutatingWebhookConfiguration or ValidatingWebhookConfiguration object that points to your server.

Deploying the webhook server

Language: You can write the webhook server in any language that can accept and return AdmissionReview JSON objects.
Location: Host the webhook inside the cluster (Deployment + Service) or outside the cluster. If inside, the webhook registration can reference the in-cluster Service.
TLS: The API server calls webhooks over TLS. The webhook server must serve TLS and the webhook configuration must include the CA bundle that signed the webhook server certificate.

Compact Go example — webhook HTTP handler This Go snippet shows the shape of a webhook HTTP handler using the admission/v1 types. It reads and decodes the AdmissionReview request, calls an admit function, and writes back a matching AdmissionReview response.

package main

import (
	"encoding/json"
	"fmt"
	"io/ioutil"
	"net/http"

	admissionv1 "k8s.io/api/admission/v1"
	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
)

type admitFunc func(admissionv1.AdmissionReview) *admissionv1.AdmissionResponse

func toAdmissionResponse(err error) *admissionv1.AdmissionResponse {
	return &admissionv1.AdmissionResponse{
		Result: &metav1.Status{
			Message: err.Error(),
		},
	}
}

func serve(w http.ResponseWriter, r *http.Request, admit admitFunc) {
	var body []byte
	if r.Body != nil {
		if data, err := ioutil.ReadAll(r.Body); err == nil {
			body = data
		}
	}

	if len(body) == 0 {
		http.Error(w, "empty body", http.StatusBadRequest)
		return
	}

	var admissionReviewReq admissionv1.AdmissionReview
	if err := json.Unmarshal(body, &admissionReviewReq); err != nil {
		http.Error(w, fmt.Sprintf("could not unmarshal request: %v", err), http.StatusBadRequest)
		return
	}

	admissionResponse := admit(admissionReviewReq)
	admissionReviewResp := admissionv1.AdmissionReview{
		TypeMeta: admissionReviewReq.TypeMeta,
		Response: admissionResponse,
	}
	admissionReviewResp.Response.UID = admissionReviewReq.Request.UID

	respBytes, err := json.Marshal(admissionReviewResp)
	if err != nil {
		http.Error(w, fmt.Sprintf("could not marshal response: %v", err), http.StatusInternalServerError)
		return
	}

	w.Header().Set("Content-Type", "application/json")
	w.Write(respBytes)
}

// main and actual admit functions omitted for brevity

Python example — building and returning a JSONPatch for a mutating webhook This Flask example builds a JSONPatch to add a label, JSON-encodes it, base64-encodes the bytes, and returns it in the AdmissionReview response. Note: the patch must be JSON-encoded bytes before base64 encoding.

from flask import Flask, request, jsonify
import base64
import json

app = Flask(__name__)

@app.route("/mutate", methods=["POST"])
def mutate():
    req = request.json
    uid = req["request"]["uid"]
    user_name = req["request"]["userInfo"]["name"]

    # Build a JSONPatch to add a label users: <username>
    patch = [
        {"op": "add", "path": "/metadata/labels/users", "value": user_name}
    ]

    patch_bytes = json.dumps(patch).encode("utf-8")
    patch_b64 = base64.b64encode(patch_bytes).decode("utf-8")

    return jsonify({
        "response": {
            "uid": uid,
            "allowed": True,
            "patch": patch_b64,
            "patchType": "JSONPatch"
        }
    })

# run the Flask app (TLS termination should be handled for production)

From an exam perspective, you are not expected to implement webhook servers. Understand the concepts and how admission webhooks are invoked, and that the webhook must accept and respond with AdmissionReview objects.

Hosting considerations

In-cluster: deploy your webhook as a Deployment and expose it via a Service (for example, webhook-service).
TLS: the webhook must present a certificate whose Common Name (CN) or SAN matches the Service DNS name. The clientConfig.caBundle in the webhook configuration must contain the CA that signed the webhook server certificate (base64-encoded).
Out-of-cluster: register the external URL in the webhook configuration; TLS is still required.

A slide diagram titled "Configuring Admission Webhook" showing a Kubernetes cluster containing a webhook-service and a webhook-deployment, with an inner circle labeled "Admission Webhook Server." The components are represented by simple shapes (triangle for service, rounded square and circle for the deployment and server).

Configuring the API server to call your webhook

Use MutatingWebhookConfiguration for mutating webhooks and ValidatingWebhookConfiguration for validators.
Each webhook entry contains:
- name: unique webhook name.
- clientConfig: where the API server should call (Service or URL) and caBundle.
- rules: which resources, API groups, versions, and operations the API server should send to the webhook.
- admissionReviewVersions and sideEffects indicating supported review versions and side-effect semantics.

Configuration fields at a glance

Field	Purpose	Example
`name`	Unique webhook identifier	`pod-policy.example.com`
`clientConfig.service`	Service to call inside cluster	`name: webhook-service`
`clientConfig.url`	External URL to call (if outside cluster)	`https://my-webhook.example.com/validate`
`clientConfig.caBundle`	Base64-encoded CA that signed server cert	`"<base64-ca-bundle>"`
`rules`	Resource/operation filter	`operations: ["CREATE"], resources: ["pods"]`
`admissionReviewVersions`	API versions supported (`v1`, `v1beta1`)	`["v1"]`
`sideEffects`	Whether the webhook has side effects	`"None"` or `"NoneOnDryRun"`

Example ValidatingWebhookConfiguration Replace the caBundle value with your base64-encoded CA certificate.

apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
metadata:
  name: pod-policy.example.com
webhooks:
  - name: pod-policy.example.com
    clientConfig:
      service:
        name: webhook-service
        namespace: default
        path: "/validate"
      caBundle: "<base64-ca-bundle>"
    rules:
      - apiGroups: [""]
        apiVersions: ["v1"]
        operations: ["CREATE"]
        resources: ["pods"]
    admissionReviewVersions: ["v1"]
    sideEffects: "None"

TLS is required for webhook communication. Ensure the webhook server’s certificate matches the service DNS name and that the caBundle in the webhook configuration contains the CA that signed that server certificate.

Operation and lifecycle

After creating the webhook configuration, the API server evaluates matching requests against the rules and sends AdmissionReview objects to the webhook.
Mutating webhooks may return patches; the API server applies them and then runs validators against the mutated object.
Webhook responses control whether requests are admitted; failure to contact a webhook may cause requests to be denied depending on the failurePolicy (if configured).

Try it hands-on

Test webhooks in a dev cluster first. Use self-signed certs for experiments and ensure your webhook serves TLS.
Log AdmissionReview requests and responses in your webhook to debug matching and patch application.

Links and references

That concludes this lesson. Implement and register a webhook in a non-production environment to gain practical experience with AdmissionReview requests, TLS configuration, and webhook ordering.

Introduction

Core Concepts

Scheduling

Logging & Monitoring

Application Lifecycle Management

Cluster Maintenance

Security

Storage

Networking

Design and Install a Kubernetes Cluster

Install "Kubernetes the kubeadm way"

Troubleshooting

Helm Basics (2025 Updates)

Kustomize Basics (2025 Updates)

Other Topics

Mock Exams

2025 Updates Validating and Mutating Admission Controllers

Watch Video

Practice Lab