book: Add note about clusterctl skip-level upgrades

Signed-off-by: Stefan Büringer [email protected]

Author: sbueringer

docs/book/src/clusterctl/commands/upgrade.md

@@ -7,7 +7,6 @@ installed into a management cluster.
 
 The `clusterctl upgrade plan` command can be used to identify possible targets for upgrades.
 
-
 ```bash
 clusterctl upgrade plan
 ```
@@ -28,7 +27,9 @@ control-plane-kubeadm   capi-kubeadm-control-plane-system   ControlPlaneProvider
 cluster-api             capi-system                         CoreProvider             v0.4.0           v1.0.0
 infrastructure-docker   capd-system                         InfrastructureProvider   v0.4.0           v1.0.0
 ```
+
 You can now apply the upgrade by executing the following command:
+
 ```bash
    clusterctl upgrade apply --contract v1beta1
 ```
@@ -67,6 +68,7 @@ Please note that clusterctl does not upgrade Cluster API objects (Clusters, Mach
 such objects are the responsibility of the provider's controllers.
 
 It is also possible to explicitly upgrade one or more components to specific versions.
+
 ```bash
 clusterctl upgrade apply \
     --core cluster-api:v1.2.4 \
@@ -75,6 +77,26 @@ clusterctl upgrade apply \
 
 <aside class="note warning">
 
+<h1>Clusterctl upgrade test coverage</h1>
+
+Cluster API only tests a subset of possible clusterctl upgrade paths as otherwise the test matrix would be overwhelming.
+Untested upgrade paths are not blocked by clusterctl and should work in general, they are just not tested. Users 
+intending to use an upgrade path not tested by us should do their own validation to ensure the operation works correctly.
+
+The following is an example of the tested upgrade paths while v1.4 is being developed:
+
+| From | To     | Note                                                                                                                                                                                    |
+|------|--------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| v0.3 | latest | v0.3 is the latest supported minor release with the v1alpha3 contract (v0.3 is EOL since 2022-02-23). This test will be removed once the v1alpha3 apiVersion has been entirely removed. |
+| v0.4 | latest | v0.4 is the latest supported minor release with the v1alpha4 contract (v0.4 is EOL since 2022-04-06). This test will be removed once the v1alpha4 apiVersion has been entirely removed. |
+| v1.0 | latest | v1.0 is the first release with the v1beta1 contract.                                                                                                                                    |
+| v1.2 | latest | v1.2 is a currently supported release. This test will be removed when v1.4 is released and a new test for v1.4 is added.                                                                |
+| v1.3 | latest | v1.3 is a currently supported release. This test will be removed when v1.5 is released and a new test for v1.5 is added.                                                                |
+
+</aside>
+
+<aside class="note warning">
+
 <h1>Warning!</h1>
 
 The current implementation of the upgrade process does not preserve controllers flags that are not set through the