Webhook Configuration and Registration
What you'll learn: How to formally register your custom admission webhooks with Kubernetes so the API server knows when and how to call them.
The Missing Link
You've learned about validating and mutating webhooks—powerful tools to intercept and modify API requests. But Kubernetes doesn't magically discover these services. You must explicitly register them using two special configuration resources: ValidatingWebhookConfiguration and MutatingWebhookConfiguration.
Think of these configurations as contact cards you hand to the API server, telling it: "When someone tries to create or update these specific resources, call this HTTPS endpoint and wait for a response."
ValidatingWebhookConfiguration
This resource registers a validating webhook. You specify:
- Webhook name: A unique identifier
- Client config: Where to reach your webhook service (typically a Kubernetes Service with TLS)
- Rules: What operations (
CREATE,UPDATE,DELETE) and which resources (Pods, Deployments, etc.) trigger the webhook - Failure policy: What happens if the webhook is unreachable (
IgnoreorFail) - CA bundle: The certificate authority used to verify your webhook's TLS certificate
MutatingWebhookConfiguration
Nearly identical structure, but registers a mutating webhook instead. Because mutating webhooks can change objects, Kubernetes processes them before validating webhooks, ensuring mutations are validated too.
Both configurations support multiple webhooks in one resource and use label selectors to filter which namespaces trigger callbacks.
Registration Flow
- Deploy your webhook service with valid TLS certificates
- Create the configuration resource with
kubectl apply - The API server immediately begins calling your endpoint for matching requests
- Monitor logs to verify registration and invocation
Key Takeaway: ValidatingWebhookConfiguration and MutatingWebhookConfiguration are the bridge between your webhook services and Kubernetes' admission control pipeline—without proper registration, your webhooks remain invisible to the cluster.