Skip to main content

Webhooks: Intercepting the API

Key Takeaways for AI & Readers
  • API Interception: Admission Webhooks allow external services to intercept and modify (Mutating) or approve/reject (Validating) API requests before they are persisted in etcd.
  • Mutating vs. Validating: Mutating webhooks can alter resource definitions (e.g., inject sidecars), while validating webhooks enforce policies and can only allow or deny requests.
  • Dynamic Policy Enforcement: Webhooks provide a dynamic and extensible way to enforce custom policies and automate resource modifications without recompiling the Kubernetes API server.
  • Availability Risk: A failing webhook server can severely impact cluster operations; failurePolicy settings balance security requirements with cluster reliability.

How does Istio automatically inject a sidecar container into your Pod? How does your cluster know to block a Pod that doesn't have a cost-center label? The answer is Admission Webhooks.

1. The Interception Point​

When you run kubectl apply, your request passes through several stages in the API Server before it is saved to etcd.

Your YAML
kind: Pod
metadata:
name: nginx
➡️
Mutating Webhook
⚡

Injecting Sidecar...

➡️
Saved to etcd
kind: Pod
spec:
containers:
- name: nginx
- name: sidecar-proxy
Webhooks are HTTP callbacks that catch API requests. **Mutating webhooks** can modify your YAML (like injecting Linkerd proxies) before it's ever saved.

Mutating Admission Webhook​

Called FIRST. It can change the YAML you sent.

  • Example: Adding a sidecar, adding environment variables, or adding default resource limits.

Validating Admission Webhook​

Called LAST. It can only say Yes or No.

  • Example: Checking for security signatures or verifying that you have the right labels.

2. Dynamic vs. Static​

Unlike standard Kubernetes controllers that are compiled into the binary, Webhooks are Dynamic. They are separate HTTP servers running inside or outside your cluster that the API Server calls over the network.

The Danger: Cluster Lock-up​

If your Webhook server is slow or crashes, what happens to your cluster?

  1. failurePolicy: Fail (Standard Security): If the webhook is down, NO ONE can create or update pods. The cluster is essentially frozen.
  2. failurePolicy: Ignore (Standard Reliability): If the webhook is down, Kubernetes skips the check. Reliability is high, but security is bypassed.

Best Practice: Always run at least 3 replicas of your Webhook server and ensure it has high priority!