Part of:k8s-homelab — a KVM-based Kubernetes lab running on Ubuntu
Every request to the Kubernetes API server passes through a chain of steps before it is persisted to etcd. Admission controllers sit at a critical point in that chain — after authentication and authorization, but before the object is stored. They are your last line of defense to enforce policy, inject defaults, and keep your cluster sane.
This guide walks through what admission controllers are, how the webhook mechanism works, and provides six progressively complex examples — three mutating, three validating — going from beginner-friendly to production-grade.
Press enter or click to view image in full size
Homelab Prerequisites
This guide assumes you are running on the k8s-homelab infrastructure:
Host: Ubuntu with KVM/libvirt
VMs: Created via vm/create-vms.sh (Ubuntu 22.04 cloud-init, 2 GB RAM / 20 GB disk each)
Cluster: Bootstrapped with kubeadm v1.33.0 (via cluster/cluster.sh or k8s/setup/control-plane-node.sh)
CRI: containerd
CNI: Calico (control-plane-node.sh) or Flannel (cluster.sh)
Nodes: At least 1 control plane + 1 worker (admission webhooks run as Pods on worker nodes and need the API server to reach them over the cluster network)
Verify your cluster is ready
# From your control plane VM (virsh console k8s-a, or SSH) kubectl get nodes # All nodes should be Ready
kubectl cluster-info # Kubernetes control plane is running at https://<control-plane-ip>:6443
Install Helm (needed for cert-manager, optional but recommended)
curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash helm version
Resource note: Each VM in this homelab has 2 GB RAM. Admission webhook Pods are lightweight (typically 20–50 MB), so they run fine. However, if you plan to run all six examples simultaneously alongside other workloads, consider adding a third worker node: ./cluster.sh --workers 3.
How the API Request Flows
kubectl apply ──▶ API Server │ Authentication │ Authorization (RBAC) │ Mutating Admission Webhooks ◀── modify the object │ Object Schema Validation │ Validating Admission Webhooks ◀── accept or reject │ Persist to etcd
Key takeaway: mutating webhooks run first and can change the object. Validating webhooks run second and can only say yes or no. A single webhook can technically do both, but separating concerns is best practice.
Anatomy of an Admission Webhook
There are two moving parts:
The webhook server — an HTTPS endpoint (a Pod in your cluster, or an external service) that receives an AdmissionReview request and returns an AdmissionReview response.
The webhook configuration — a MutatingWebhookConfiguration or ValidatingWebhookConfiguration resource that tells the API server when to call your webhook and where it lives.
AdmissionReview Request (what the API server sends you)
Every webhook must serve HTTPS. The API server verifies the certificate using the caBundle in the webhook configuration. In the examples below we use a self-signed CA. In production, use cert-manager.
The CN and SAN must match <service-name>.<namespace>.svc.
Mutating Admission Controller Examples
Mutating webhooks intercept API requests and modify the submitted object before it reaches validation and storage. They return a JSON Patch that the API server applies to the object.
Mutating Example 1 — Inject a Default Label
Scope: Any Pod created without a team label gets team: unassigned injected automatically.
Why this matters: Labeling is the backbone of cost allocation, RBAC scoping, and monitoring in multi-team clusters. Rather than rejecting unlabeled pods (which frustrates developers during iteration), a mutating webhook can silently add a safe default.
# Create a pod without a team label kubectl run bare-pod --image=nginx
# Verify the label was injected kubectl get pod bare-pod --show-labels # NAME READY STATUS LABELS # bare-pod 1/1 Running run=bare-pod,team=unassigned
Mutating Example 2 — Inject a Sidecar Container (Logging Agent)
Scope: Any Pod in a namespace labeled logging: enabled gets a Fluent Bit sidecar container injected. If the Pod already has a container named fluent-bit, skip injection.
Why this matters: Sidecar injection is one of the most powerful uses of mutating webhooks — Istio’s entire service mesh model is built on this pattern. This example shows how to conditionally inject a full container spec with volume mounts.
Notice reinvocationPolicy: IfNeeded — if another mutating webhook modifies the Pod after ours runs, the API server re-invokes our webhook so we can react to the new state.
Test It
# Label the namespace kubectl label namespace default logging=enabled
# Deploy a simple pod kubectl run app --image=nginx
# Inspect - should have 2 containers kubectl get pod app -o jsonpath='{.spec.containers[*].name}' # app fluent-bit
Mutating Example 3 — Production Pod Security Hardener
Scope: Enforce a security baseline by mutating every Pod at creation time:
Set runAsNonRoot: true and readOnlyRootFilesystem: true on every container that does not explicitly set them.
Drop all Linux capabilities and add back only NET_BIND_SERVICE if the container listens on a privileged port (port < 1024).
Set automountServiceAccountToken: false unless the Pod has the annotation iam.k8s.io/automount: "true".
Inject the annotation security.k8s.io/hardened: "true" so validating webhooks or audit pipelines can confirm the Pod passed through this webhook.
This is the kind of webhook that runs in production clusters alongside (or instead of) Pod Security Standards.
Webhook Server (Go)
Go is the production choice for admission webhooks — lower latency, strongly typed, and the same language as the Kubernetes ecosystem.
Get Weber Dubois’s stories in your inbox
Join Medium for free to get updates from this writer.
The objectSelector allows opting out individual Pods by adding the label skip-hardening: "true" — useful for debugging or for system Pods that genuinely need root.
Before and After
Before (what the user submits):
apiVersion: v1 kind: Pod metadata: name: harden-test namespace: default spec: containers: - name: web image: nginx:1.27 ports: - containerPort: 80
Validating webhooks inspect the final state of the object (after mutation) and return a binary allow or deny. They cannot modify the object.
Validating Example 1 — Block latest Image Tag
Scope: Reject any Pod that uses a container image without an explicit tag or with the tag :latest.
Why this matters::latest is mutable — the same tag can point to a completely different image digest tomorrow. This breaks reproducibility, makes rollbacks unreliable, and can silently introduce vulnerabilities.
Webhook Server (Python / Flask)
from flask import Flask, request, jsonify
app = Flask(__name__)
@app.route("/validate", methods=["POST"]) def validate(): review = request.get_json() req = review["request"] pod = req["object"] violations = [] all_containers = ( pod["spec"].get("containers", []) + pod["spec"].get("initContainers", []) ) for c in all_containers: image = c.get("image", "") if ":" not in image or image.endswith(":latest"): violations.append( f"container '{c['name']}' uses image '{image}' - " "a specific, immutable tag or digest is required" ) allowed = len(violations) == 0 status = {"code": 200} if allowed else { "code": 403, "message": "Image policy violation:\n" + "\n".join(violations), } return jsonify({ "apiVersion": "admission.k8s.io/v1", "kind": "AdmissionReview", "response": { "uid": req["uid"], "allowed": allowed, "status": status, }, })
if __name__ == "__main__": app.run(host="0.0.0.0", port=8443, ssl_context=("/tls/tls.crt", "/tls/tls.key"))
# This should be REJECTED kubectl run bad --image=nginx # Error: admission webhook "image-tag.webhook-ns.svc" denied the request: # container 'bad' uses image 'nginx' — a specific, immutable tag or digest is required # This should be ALLOWED kubectl run good --image=nginx:1.27.0
Validating Example 2 — Enforce Resource Requests, Limits, and Ratio Constraints
Scope: Reject any Pod where:
Any container is missing resources.requests or resources.limits for both CPU and memory.
The limits-to-requests ratio exceeds a configurable cap (e.g., memory limit cannot be more than 2x the request). This prevents “overcommit bombs” where a Pod requests 64Mi but limits to 8Gi.
Webhook Server (Python / Flask)
from flask import Flask, request, jsonify import re
def parse_quantity(q): """Convert Kubernetes resource quantity string to a base number.""" suffixes = { "m": 0.001, "K": 1e3, "M": 1e6, "G": 1e9, "T": 1e12, "Ki": 1024, "Mi": 1024**2, "Gi": 1024**3, "Ti": 1024**4, } match = re.match(r"^(\d+\.?\d*)\s*([A-Za-z]*)$", str(q)) if not match: return 0 value, suffix = float(match.group(1)), match.group(2) return value * suffixes.get(suffix, 1)
@app.route("/validate", methods=["POST"]) def validate(): review = request.get_json() req = review["request"] pod = req["object"] violations = [] for c in pod["spec"].get("containers", []): res = c.get("resources", {}) requests = res.get("requests", {}) limits = res.get("limits", {}) name = c["name"] for r in ["cpu", "memory"]: if r not in requests: violations.append(f"'{name}': missing resources.requests.{r}") if r not in limits: violations.append(f"'{name}': missing resources.limits.{r}") if r in requests and r in limits: req_val = parse_quantity(requests[r]) lim_val = parse_quantity(limits[r]) if req_val > 0: ratio = lim_val / req_val cap = MAX_LIMIT_TO_REQUEST_RATIO[r] if ratio > cap: violations.append( f"'{name}': {r} limit/request ratio is " f"{ratio:.1f}x (max {cap:.1f}x) - " f"requests={requests[r]}, limits={limits[r]}" ) allowed = len(violations) == 0 return jsonify({ "apiVersion": "admission.k8s.io/v1", "kind": "AdmissionReview", "response": { "uid": req["uid"], "allowed": allowed, "status": { "code": 200 if allowed else 403, "message": ( "OK" if allowed else "Resource policy violation:\n" + "\n".join(violations) ), }, }, })
if __name__ == "__main__": app.run(host="0.0.0.0", port=8443, ssl_context=("/tls/tls.crt", "/tls/tls.key"))
var allowedRegistries = []string{ "ghcr.io/myorg/", "registry.internal.io/", }
var requiredLabels = []string{ "app.kubernetes.io/name", "app.kubernetes.io/version", }
type ruleFunc func(pod *corev1.Pod) []string
var rules = []ruleFunc{ checkRegistries, checkRequiredLabels, checkHostNamespaces, checkRunAsRoot, checkPDBAnnotation, }
func checkRegistries(pod *corev1.Pod) []string { var v []string all := append(pod.Spec.Containers, pod.Spec.InitContainers...) for _, c := range all { ok := false for _, prefix := range allowedRegistries { if strings.HasPrefix(c.Image, prefix) { ok = true break } } if !ok { v = append(v, fmt.Sprintf( "[registry] container '%s' image '%s' is not from an allowed registry %v", c.Name, c.Image, allowedRegistries, )) } } return v }
func checkRequiredLabels(pod *corev1.Pod) []string { var v []string labels := pod.GetLabels() for _, l := range requiredLabels { if _, ok := labels[l]; !ok { v = append(v, fmt.Sprintf("[labels] missing required label '%s'", l)) } } return v }
func checkHostNamespaces(pod *corev1.Pod) []string { var v []string if pod.Spec.HostNetwork { v = append(v, "[host] hostNetwork is true — denied by policy") } if pod.Spec.HostPID { v = append(v, "[host] hostPID is true — denied by policy") } if pod.Spec.HostIPC { v = append(v, "[host] hostIPC is true — denied by policy") } return v }
func checkRunAsRoot(pod *corev1.Pod) []string { var v []string for _, c := range pod.Spec.Containers { if c.SecurityContext != nil && c.SecurityContext.RunAsUser != nil { if *c.SecurityContext.RunAsUser == 0 { v = append(v, fmt.Sprintf( "[uid] container '%s' explicitly runs as UID 0 (root)", c.Name, )) } } } return v }
func checkPDBAnnotation(pod *corev1.Pod) []string { ns := pod.GetNamespace() // The API server passes the namespace in the request, but for pods // created via higher-level controllers, the namespace label on the // namespace object tells us the environment tier. // We only enforce this rule when the webhook configuration's // namespaceSelector already filters for env=production namespaces. _ = ns ann := pod.GetAnnotations() if _, ok := ann["policy.k8s.io/pdb-name"]; !ok { return []string{ "[pdb] pods in production namespaces must have annotation " + "'policy.k8s.io/pdb-name' referencing an existing PodDisruptionBudget", } } return nil }
cat <<EOF | kubectl apply -f - apiVersion: v1 kind: Pod metadata: name: bad-pod spec: hostNetwork: true containers: - name: app image: docker.io/library/nginx:latest securityContext: runAsUser: 0 EOF # Error: 5 policy violation(s): # • [registry] container 'app' image 'docker.io/library/nginx:latest' is not from an allowed registry # • [labels] missing required label 'app.kubernetes.io/name' # • [labels] missing required label 'app.kubernetes.io/version' # • [host] hostNetwork is true - denied by policy # • [uid] container 'app' explicitly runs as UID 0 (root) # • [pdb] pods in production namespaces must have annotation 'policy.k8s.io/pdb-name'
Production Checklist
Press enter or click to view image in full size
Mutating vs. Validating — When to Use Which
Press enter or click to view image in full size
In practice, many organizations pair them: a mutating webhook adds safe defaults, and a validating webhook ensures the final state meets policy — defense in depth.
Summary
Admission controllers are one of the most powerful extension points in Kubernetes. They let you encode organizational policy directly into the API server’s request pipeline — no external enforcement needed.
Start simple (label injection, tag validation), grow into sidecar injection and resource governance, and eventually build a composable policy engine. The six examples in this guide cover that full arc.
The key principles to carry forward:
Mutate first, validate second — mirror the API server’s own ordering in your mental model.
Fail closed for security, fail open for convenience — choose failurePolicy deliberately.
Exclude your own namespace — or risk a deadlock where the webhook Pod can’t start because the webhook is down.
Test with AdmissionReview JSON — you don't need a full cluster to unit-test your logic.
Running These Examples on the Homelab
All six examples in this guide are designed to run on the k8s-homelab cluster. A few homelab-specific tips:
Build images locally with containerd: Since the homelab doesn’t have a registry by default, you can build images and import them directly into containerd on each node:
# On your host, build and save the image docker build -t label-injector:v1 . docker save label-injector:v1 -o label-injector.tar
# Copy to each VM and import into containerd scp label-injector.tar ubuntu@<node-ip>:/tmp/ ssh ubuntu@<node-ip> "sudo ctr -n k8s.io images import /tmp/label-injector.tar"
Alternatively, set up a local registry or use a free container registry (GHCR, Docker Hub).
Self-signed certs on a homelab cluster: The TLS setup in this guide uses self-signed certificates, which is fine for a homelab. For a more automated approach, install cert-manager:
