Kubernetes - Webhooks

Last Updated: 2024-01-21

Types of webhooks

• Admission webhook
  • Validating webhook
  • Mutating webhook
• Conversion webhook

Admission Webhooks

Webhooks can be used to extend admission control.

How does it work?

• The webhooks are configured by ValidatingWebhookConfiguration or MutatingWebhookConfiguration.
• The configurations specify the Services in webhook.clientConfig.service
• The Service specifies app.kubernetes.io/name in .spec.selector, from which you can find the Deployment and Pods.
• The Pod runs the webhook backends.
• When user submit YAML changes, the kube-apiserver sends AdmissionRequests to Webhook, Admission Webhooks require Handler(s) to be provided to process the received AdmissionReview requests.

How to create a Webhook backend?

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.

Webhook server will start a httpserver (sigs.k8s.io/controller-runtime/pkg/internal/httpserver).

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 the webhook server together with the controllers in the same manager (and thus the same binary / image) 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.

How to delete Adminssion Webhooks

Delete the Webhook Configurations:

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

Adminssion Control: Webhook vs Plugin

• Webhook model: Kubernetes makes a network request to a remote service.
• Plugin model: Kubernetes executes a binary (program).

Conversion webhook

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.

Gatekeeper

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.