Webhooks

The webhooks in our mailgun provider are offered through tools in Controller Runtime and Controller Tools, which are the building blocks Kubebuilder relies on.

At high level, in order to add webhooks to the mailgun provider it is required to implement interfaces defined in Controller Runtime, while generation of manifests for the corresponding MutatingWebhookConfiguration and ValidatingWebhookConfiguration can be done using Controller Tools via Makefile targets generated by Kubebuilder.

Before taking a look at this in detail, let’s get an overview of the types of web hooks supported by Controller Runtime.

Validating webhooks

Validating webhooks are an implementation of a Kubernetes validating webhook.

A validating webhook allows developers to test whether values supplied by users are valid. e.g. the Cluster webhook ensures the Infrastructure reference supplied at the Cluster’s .spec.infrastructureRef is in the same namespace as the Cluster itself and rejects the object creation or update if not.

Defaulting webhooks

Defaulting webhooks are an implementation of a Kubernetes mutating webhook.

A defaulting webhook allows developers to set default values for a type before they are placed in etcd, the Kubernetes data store. e.g. the Cluster webhook will set the Infrastructure reference namespace to equal the Cluster namespace if .spec.infrastructureRef.namespace is empty.

Conversion webhooks

Conversion webhooks are also an implementation of a Kubernetes mutating webhook.

Conversion webhooks are what allow Cluster API to work with multiple API version of the same API type. It does this by converting the incoming version to a Hub version which is used internally by the controllers. To read more about conversion see the Kubebuilder documentation

For a walkthrough on implementing conversion webhooks see the video in the Developer Guide

Implementing webhooks with Controller Runtime, Controller Tools and Kubebuilder

The Kubebuilder book provide detailed description about how to implement interfaces defined in Controller Runtime for each of the above webhook types.

Webhook manifests instead are generated by Controller Tools via Makefile targets implemented by Kubebuilder.

In order to do so, it is required to add tags to API types in the codebase. Below, for example, are the tags on the the Cluster webhook:

// +kubebuilder:webhook:verbs=create;update;delete,path=/validate-cluster-x-k8s-io-v1beta1-cluster,mutating=false,failurePolicy=fail,matchPolicy=Equivalent,groups=cluster.x-k8s.io,resources=clusters,versions=v1beta1,name=validation.cluster.cluster.x-k8s.io,sideEffects=None,admissionReviewVersions=v1;v1beta1
// +kubebuilder:webhook:verbs=create;update,path=/mutate-cluster-x-k8s-io-v1beta1-cluster,mutating=true,failurePolicy=fail,matchPolicy=Equivalent,groups=cluster.x-k8s.io,resources=clusters,versions=v1beta1,name=default.cluster.cluster.x-k8s.io,sideEffects=None,admissionReviewVersions=v1;v1beta1

// Cluster implements a validating and defaulting webhook for Cluster.
type Cluster struct {
    Client client.Reader
}

A detailed guide on the purpose of each of these tags is here.