Kubernetes - Webhook

Last Updated: 2023-08-20

Webhooks may run as containers in k8s; webhooks can be used to extend admission control. e.g. istio / linkerd has registered admission hooks: user submits normal yaml configs, and "Mutating Admission" stage will add the sidecar container to it.


  • one per Kind that is reconciled.
  • provides methods to build and bootstrap a webhook server.
  • same as controllers, a Webhook Server is a Runable (https://pkg.go.dev/sigs.k8s.io/controller-runtime/pkg/manager#Runnable) (i.e. both controller and webhook server implement Start(ctx context.Context)) which needs to be registered to a manager. Arbitrary number of Runables can be registered to a manager, so a webhook server can run with other controllers in the same manager. They will share the same dependencies provided by the manager. For example, shared cache, client, scheme, etc.
  • Admission Webhooks: the API server will send AdmissionRequests to Webhook, Admission Webhooks require Handler(s) to be provided to process the received AdmissionReview requests.
  • Conversion Webhooks: When API clients, like kubectl or your controller, request a particular version of your resource, the Kubernetes API server needs to return a result that’s of that version. However, that version might not match the version stored by the API server. In that case, the API server needs to know how to convert between the desired version and the stored version. Since the conversions aren’t built in for CRDs, the Kubernetes API server calls out to a webhook to do the conversion instead. For Kubebuilder, this webhook is implemented by controller-runtime, and performs the hub-and-spoke conversions.

Webhook Server

Webhook server will start a httpserver (sigs.k8s.io/controller-runtime/pkg/internal/httpserver) it is similar to a controller in that it also implements Runnable interface.

The business logic for a Webhook exists in a Handler. A Handler implements the admission.Handler interface, which contains a single Handle method.

hookServer.Register(): register a handler.

It is recommended to put webhook server together for following benefits:

  • Less resource overhead (fewer pod, ip usage and sometimes client cache).
  • If webhook and controller are separate deployments, then when webhook is running but controller is down, custom resources will be accepted by API server but not reconciled, this behavior is confusing.

3 kinds of webhooks

  • admission webhook. 2 types of admission webhook: mutating and validating admission webhook.
  • authorization webhook.
  • CRD conversion webhook.

Webhook vs Binary Plugin

  • Webhook model: Kubernetes makes a network request to a remote service.
  • Binary Plugin model: Kubernetes executes a binary (program). Binary plugins are used by the kubelet and by kubectl.


Gatekeeper deploys one Validating webhook and one Mutating webhook that watches all kinds in all apigroups.

It’s basically one big webhook that checks all constraints created via Gatekeeper yamls.

We cannot use Gatekeeper when the validation logic requires queries to the APIServer. For those more complicated policies, we need to write our own webhook.

How to delete Webhooks

Delete the Webhook Configurations:

$ kubectl delete mutatingwebhookconfigurations --all
$ kubectl delete validatingwebhookconfigurations --all