[release-1.2] 📖 book: add doc about Cluster API updates with ClusterClass

docs/book/src/tasks/experimental-features/cluster-class/operate-cluster.md

@@ -9,6 +9,7 @@ A managed Cluster can be used to:
 * [Add a MachineDeployment](#add-a-machinedeployment)
 * [Use variables in a Cluster](#use-variables)
 * [Rebase a Cluster to a different ClusterClass](#rebase-a-cluster)
+* [Upgrading Cluster API](#upgrading-cluster-api)
 * [Tips and tricks](#tips-and-tricks)
 
 ## Upgrade a Cluster
@@ -266,6 +267,104 @@ Please note that:
 
 </aside>
 
+# Upgrading Cluster API
+
+There are some special considerations for ClusterClass regarding Cluster API upgrades when the upgrade includes a bump
+of the apiVersion of infrastructure, bootstrap or control plane provider CRDs.
+
+The recommended approach is to first upgrade Cluster API and then update the apiVersions in the ClusterClass references afterwards.
+By following above steps, there won't be any disruptions of the reconciliation as the Cluster topology controller is able to reconcile the Cluster 
+even with the old apiVersions in the ClusterClass.
+
+Note: The apiVersions in ClusterClass cannot be updated before Cluster API because the new apiVersions don't exist in 
+the management cluster before the Cluster API upgrade.
+
+In general the Cluster topology controller always uses exactly the versions of the CRDs referenced in the ClusterClass.
+This means in the following example the Cluster topology controller will always use `v1beta1` when reconciling/applying 
+patches for the infrastructure ref, even if the `DockerClusterTemplate` already has a `v1beta2` apiVersion.
+
+```yaml
+apiVersion: cluster.x-k8s.io/v1beta1
+kind: ClusterClass
+metadata:
+  name: quick-start
+  namespace: default
+spec:
+  infrastructure:
+    ref:
+      apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
+      kind: DockerClusterTemplate
+...
+```
+
+<aside class="note warning">
+
+<h1>Bumping apiVersions in ClusterClass</h1>
+
+When upgrading the apiVersions in references in the ClusterClass the corresponding patches have to be changed accordingly.
+This includes bumping the apiVersion in the patch selector and potentially updating the JSON patch to changes in the new 
+apiVersion of the referenced CRD. The following example shows how to upgrade the ClusterClass in this case. 
+
+ClusterClass with the old apiVersion:
+```yaml
+apiVersion: cluster.x-k8s.io/v1beta1
+kind: ClusterClass
+metadata:
+  name: quick-start
+spec:
+  infrastructure:
+    ref:
+      apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
+      kind: DockerClusterTemplate
+...
+  patches:
+  - name: lbImageRepository
+    definitions:
+    - selector:
+        apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
+        kind: DockerClusterTemplate
+        matchResources:
+          infrastructureCluster: true
+      jsonPatches:
+      - op: add
+        path: "/spec/template/spec/loadBalancer/imageRepository"
+        valueFrom:
+          variable: lbImageRepository
+```
+
+ClusterClass with the new apiVersion:
+```yaml
+apiVersion: cluster.x-k8s.io/v1beta1
+kind: ClusterClass
+metadata:
+  name: quick-start
+spec:
+  infrastructure:
+    ref:
+      apiVersion: infrastructure.cluster.x-k8s.io/v1beta2 # apiVersion updated
+      kind: DockerClusterTemplate
+...
+  patches:
+  - name: lbImageRepository
+    definitions:
+    - selector:
+        apiVersion: infrastructure.cluster.x-k8s.io/v1beta2 # apiVersion updated
+        kind: DockerClusterTemplate
+        matchResources:
+          infrastructureCluster: true
+      jsonPatches:
+      - op: add
+        # Path has been updated, as in this example imageRepository has been renamed 
+        # to imageRepo in v1beta2 of DockerClusterTemplate.
+        path: "/spec/template/spec/loadBalancer/imageRepo"
+        valueFrom:
+          variable: lbImageRepository
+```
+
+If external patches are used in the ClusterClass, it has to be ensured that all external patches support the new apiVersion 
+before bumping apiVersions.
+
+</aside>
 
 [Quick Start guide]: ../../../user/quick-start.md
 [ClusterClass rebase]: ./change-clusterclass.md#rebase

docs/book/src/tasks/experimental-features/runtime-sdk/implement-topology-mutation-hook.md

@@ -188,3 +188,34 @@ function openSwaggerUI() {
   window.open("https://editor.swagger.io/?url=" + schemaURL)
 }
 </script>
+
+## Dealing with Cluster API upgrades with apiVersion bumps
+
+There are some special considerations regarding Cluster API upgrades when the upgrade includes a bump
+of the apiVersion of infrastructure, bootstrap or control plane provider CRDs.
+
+When calling external patches the Cluster topology controller is always sending the templates in the apiVersion of the references
+in the ClusterClass.
+
+While inline patches are always referring to one specific apiVersion, external patch implementations are more flexible. They can
+be written in a way that they are able to handle multiple apiVersions of a CRD. This can be done by calculating patches differently
+depending on which apiVersion is received by the external patch implementation.
+
+This allows users more flexibility during Cluster API upgrades:
+
+Variant 1: External patch implementation supporting two apiVersions at the same time
+
+1. Update Cluster API
+2. Update the external patch implementation to be able to handle custom resources with the old and the new apiVersion
+3. Update the references in ClusterClasses to use the new apiVersion
+
+**Note** In this variant it doesn't matter if Cluster API or the external patch implementation is updated first.
+
+Variant 2: Deploy an additional instance of the external patch implementation which can handle the new apiVersion
+
+1. Upgrade Cluster API
+2. Deploy the new external patch implementation which is able to handle the new apiVersion
+3. Update ClusterClasses to use the new apiVersion and the new external patch implementation
+4. Remove the old external patch implementation as it's not used anymore
+
+**Note** In this variant it doesn't matter if Cluster API is updated or the new external patch implementation is deployed first.