📖 Documentation for the chained upgrade feature

docs/book/src/SUMMARY.md

@@ -39,6 +39,7 @@
             - [Implementing Runtime Extensions](./tasks/experimental-features/runtime-sdk/implement-extensions.md)
             - [Implementing Lifecycle Hook Extensions](./tasks/experimental-features/runtime-sdk/implement-lifecycle-hooks.md)
             - [Implementing Topology Mutation Hook Extensions](./tasks/experimental-features/runtime-sdk/implement-topology-mutation-hook.md)
+            - [Implementing Upgrade Plan Runtime Extensions](./tasks/experimental-features/runtime-sdk/implement-upgrade-plan-hooks.md)
             - [Deploying Runtime Extensions](./tasks/experimental-features/runtime-sdk/deploy-runtime-extension.md)
         - [Ignition Bootstrap configuration](./tasks/experimental-features/ignition.md)
     - [Running multiple providers](./tasks/multiple-providers.md)

docs/book/src/reference/glossary.md

@@ -1,6 +1,6 @@
 # Table of Contents
 
-[A](#a) | [B](#b) | [C](#c) | [D](#d) | [E](#e) | [H](#h) | [I](#i) | [K](#k) | [L](#l)| [M](#m) | [N](#n) | [O](#o) | [P](#p) | [R](#r) | [S](#s) | [T](#t) | [W](#w)
+[A](#a) | [B](#b) | [C](#c) | [D](#d) | [E](#e) | [H](#h) | [I](#i) | [K](#k) | [L](#l)| [M](#m) | [N](#n) | [O](#o) | [P](#p) | [R](#r) | [S](#s) | [T](#t) | [U](#u) |[W](#w)
 
 # A
 ---
@@ -132,6 +132,15 @@ Cluster API IPAM Provider Metal3
 ### CAREX
 Cluster API Runtime Extensions Provider Nutanix
 
+### Chained upgrade
+An upgrade sequence that goes from one Kubernetes version to another by passing through a set of intermediate versions.
+E.g. upgrading from v1.31.0 (current state) to v1.34.0 (target version) requires
+a chained upgrade with the following steps: v1.32.0 (first intermediate version) -> v1.33.0 (second intermediate version) -> v1.34.0 (target version).
+
+The sequence of versions in a chained upgrade is also called [upgrade plan](#upgrade-plan).
+
+See also [efficient upgrade](#efficient-upgrade).
+
 ### Cloud provider
 
 Or __Cloud service provider__
@@ -219,6 +228,14 @@ A feature implementation offered as part of the Cluster API project and maintain
 # E
 ---
 
+### Efficient upgrade
+
+A [chained upgrade](#chained-upgrade) where worker nodes skip some of the intermediate versions,
+when allowed by the [Kubernetes version skew policy](https://kubernetes.io/releases/version-skew-policy/).
+
+When the chained upgrade is also an efficient upgrade, the [upgrade plan](#upgrade-plan) for worker machines is a subset 
+of the [upgrade plan](#upgrade-plan) for control plane machines.
+
 ### External patch
 
 [Patch](#patch) generated by an external component using [Runtime SDK](#runtime-sdk). Alternative to [inline patch](#inline-patch).
@@ -460,6 +477,16 @@ A [Runtime Hook](#runtime-hook) that allows external components to generate [pat
 
 See [Topology Mutation](../tasks/experimental-features/runtime-sdk/implement-topology-mutation-hook.md)
 
+# U
+---
+
+### Upgrade plan
+The sequence of intermediate versions ... target version that a Cluster must upgrade to when
+performing a [chained upgrade](#chained-upgrade).
+
+Notably, the upgrade plan for control plane machines might be a superset of the upgrade plan for
+workers machines.
+
 # W
 ---