sigs.k8s.io/cluster-api@v1.7.1/docs/book/src/developer/providers/webhooks.md (about)

     1  # Webhooks
     2  
     3  Cluster API provides support for three kinds of webhooks: validating webhooks, defaulting webhook and conversion webhooks. 
     4  
     5  ## Validating webhooks
     6  Validating webhooks are an implementation of a [Kubernetes validating webhook](https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#validatingadmissionwebhook). 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.
     7  
     8  <aside class="note">
     9  
    10  <h1> ClusterClass and managed topology support in validating webhooks </h1>
    11  
    12  Validating webhooks implemented for a `InfrastructureMachineTemplate` or `BootstrapConfigTemplate` resource
    13  are required to not block due to immutability checks when the controller for managed
    14  topology and ClusterClass does [Server Side Apply] dry-run requests.
    15  [Server Side Apply] implementation in ClusterClass and managed topologies requires to dry-run changes on templates.
    16  If infrastructure or bootstrap providers have implemented immutability checks in their InfrastructureMachineTemplate
    17  or BootstrapConfigTemplate webhooks, it is required to implement the following changes in order to prevent dry-run
    18  to return errors. The implementation requires sigs.k8s.io/controller-runtime in version >= v0.12.3.
    19  In order to do so it is required to use a controller runtime CustomValidator.
    20  This will allow to skip the immutability check only when the topology controller is dry running while preserving the
    21  validation behavior for all other cases.
    22  
    23  See [the DockerMachineTemplate webhook] as a reference for a compatible implementation.
    24  
    25  [Server Side Apply]: https://kubernetes.io/docs/reference/using-api/server-side-apply/
    26  [the DockerMachineTemplate webhook]: https://github.com/kubernetes-sigs/cluster-api/blob/main/test/infrastructure/docker/internal/webhooks/dockermachinetemplate_webhook.go
    27  
    28  </aside>
    29  
    30  ## Defaulting webhooks
    31  Defaulting webhooks are an implementation of a [Kubernetes mutating webhook](https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#mutatingadmissionwebhook). A defaulting webhook allows developers to set default values for a type before they are placed in 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.
    32  
    33  ## Conversion webhooks
    34  Conversion webhooks are what allow Cluster API to work with multiple API types without requiring different versions. 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](https://book.kubebuilder.io/multiversion-tutorial/conversion.html)
    35  
    36  For a walkthrough on implementing conversion webhooks see the video in the [Developer Guide](../guide.md#videos-explaining-capi-architecture-and-code-walkthroughs)
    37  
    38  ## Implementing webhooks with Controller Runtime and Kubebuilder
    39  The webhooks in Cluster API are offered through tools in Controller Runtime and Kubebuilder. The webhooks implement interfaces defined in Controller Runtime, while generation of manifests can be done using Kubebuilder.
    40  
    41  For information on how to create webhooks [refer to the Kubebuilder book](https://book.kubebuilder.io/cronjob-tutorial/webhook-implementation.html).
    42  
    43  
    44  Webhook manifests are generated using Kubebuilder in Cluster API. This is done by adding tags to the webhook implementation in the codebase. Below, for example, are the tags on the [the Cluster webhook]:
    45  
    46  ```go
    47  
    48  // +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
    49  // +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
    50  
    51  // Cluster implements a validating and defaulting webhook for Cluster.
    52  type Cluster struct {
    53      Client client.Reader
    54  }
    55  ```
    56  
    57  A detailed guide on the purpose of each of these tags is [here](https://book.kubebuilder.io/reference/markers/webhook.html).
    58  
    59  <!-- links -->
    60  [the Cluster webhook]: https://github.com/kubernetes-sigs/cluster-api/blob/main/internal/webhooks/cluster.go