From 42c685f8ed59e5c4b83146c0d3f8b39d6d6329a9 Mon Sep 17 00:00:00 2001
From: Christian Schlotter <christi.schlotter@gmail.com>
Date: Fri, 8 Jul 2022 10:39:01 +0200
Subject: [PATCH] add note ClusterClass compatibility info to validating
 webhooks section

---
 docs/book/src/developer/providers/webhooks.md | 24 ++++++++++++++++++-
 1 file changed, 23 insertions(+), 1 deletion(-)

diff --git a/docs/book/src/developer/providers/webhooks.md b/docs/book/src/developer/providers/webhooks.md
index 264cac1efeb3..6fe05179cbed 100644
--- a/docs/book/src/developer/providers/webhooks.md
+++ b/docs/book/src/developer/providers/webhooks.md
@@ -5,6 +5,28 @@ Cluster API provides support for three kinds of webhooks: validating webhooks, d
 ## Validating webhooks
 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.
 
+<aside class="note">
+
+<h1> ClusterClass and managed topology support in validating webhooks </h1>
+
+Validating webhooks implemented for a `InfrastructureMachineTemplate` or `BootstrapConfigTemplate` resource
+are required to not block due to immutability checks when the controller for managed
+topology and ClusterClass does [Server Side Apply] dry-run requests.
+[Server Side Apply] implementation in ClusterClass and managed topologies requires to dry-run changes on templates.
+If infrastructure or bootstrap providers have implemented immutability checks in their InfrastructureMachineTemplate
+or BootstrapConfigTemplate webhooks, it is required to implement the following changes in order to prevent dry-run
+to return errors. The implementation requires sigs.k8s.io/controller-runtime in version >= v0.12.3.
+In order to do so it is required to use a controller runtime CustomValidator.
+This will allow to skip the immutability check only when the topology controller is dry running while preserving the
+validation behavior for all other cases.
+
+See [the DockerMachineTemplate webhook] as a reference for a compatible implementation.
+
+[Server Side Apply]: https://kubernetes.io/docs/reference/using-api/server-side-apply/
+[the DockerMachineTemplate webhook]: https://github.com/kubernetes-sigs/cluster-api/blob/main/test/infrastructure/docker/api/v1beta1/dockermachinetemplate_webhook.go
+
+</aside>
+
 ## Defaulting webhooks
 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.
 
@@ -35,4 +57,4 @@ type Cluster struct {
 A detailed guide on the purpose of each of these tags is [here](https://book.kubebuilder.io/reference/markers/webhook.html).
 
 <!-- links -->
-[the Cluster webhook]: https://github.com/kubernetes-sigs/cluster-api/blob/release-1.1/internal/webhooks/cluster.go
+[the Cluster webhook]: https://github.com/kubernetes-sigs/cluster-api/blob/main/internal/webhooks/cluster.go