docs: document ClusterClass rotation behavior for MachinePool objects

bnallapeta · bnallapeta · commit 2ee5e9173e8d · 2026-02-04T07:47:21.000+05:30
Signed-off-by: Bharath Nallapeta &lt;nr.bharath97@gmail.com&gt;
diff --git a/docs/book/src/developer/providers/contracts/bootstrap-config.md b/docs/book/src/developer/providers/contracts/bootstrap-config.md
@@ -55,8 +55,10 @@ repo or add an item to the agenda in the [Cluster API community meeting](https:/
 | [BootstrapConfig: terminal failures]                                       | No        |                                      |
 | [BootstrapConfigTemplate, BootstrapConfigTemplateList resource definition] | Yes       |                                      |
 | [BootstrapConfigTemplate: support for SSA dry run]                         | No        | Mandatory for ClusterClasses support |
+| [ClusterClass topology controller behavior for MachinePools]               | No        | Mandatory for ClusterClasses support |
 | [Sentinel file]                                                            | No        |                                      |
 | [Taint Nodes at creation]                                                  | No        |                                      |
+| [Infrastructure provider watching for bootstrap changes]                   | No        |                                      |
 | [Support for running multiple instances]                                   | No        | Mandatory for clusterctl CLI support |
 | [Clusterctl support]                                                       | No        | Mandatory for clusterctl CLI support |
 | [BootstrapConfig: pausing]                                                 | No        |                                      |
@@ -420,6 +422,33 @@ validation behavior for all other cases.
 
 See [the DockerMachineTemplate webhook] as a reference for a compatible implementation.
 
+### ClusterClass topology controller behavior for MachinePools
+
+When using ClusterClass and managed topologies with MachinePools, the topology controller creates BootstrapConfig objects
+from BootstrapConfigTemplates. Unlike templates (which are immutable), these BootstrapConfig objects have mutable specs,
+but the topology controller handles spec changes through a **rotation strategy** rather than in-place updates.
+
+When the topology controller detects that the BootstrapConfigTemplate has changed (e.g., from template updates
+in ClusterClass), it performs a **rotation**:
+
+1. Creates a new BootstrapConfig object with a new name
+2. Updates the MachinePool's `spec.template.spec.bootstrap.configRef` to reference the new object
+3. The old BootstrapConfig is garbage collected when no longer referenced
+
+<aside class="note">
+
+<h1>Provider expectations for rotation</h1>
+
+Bootstrap providers SHOULD be aware that when used with MachinePools, the BootstrapConfig object may be rotated
+(replaced with a new object) rather than updated in-place when spec changes occur.
+
+</aside>
+
+Metadata-only changes (labels, annotations) MUST NOT trigger rotation; they are patched in-place on the existing object.
+
+Note: This rotation behavior is specific to MachinePools. For individual Machines (e.g., in MachineDeployments), BootstrapConfig
+objects are created per-Machine and follow the standard Machine lifecycle.
+
 ### Sentinel file
 
 A bootstrap provider's bootstrap data must create `/run/cluster-api/bootstrap-success.complete` 
@@ -433,6 +462,13 @@ This taint is used to prevent workloads to be scheduled on Nodes before the node
 As of today the Node initialization consists of syncing labels from Machines to Nodes. Once the labels have been
 initially synced the taint is removed from the Node.
 
+### Infrastructure provider watching for bootstrap changes
+
+Infrastructure providers watching for bootstrap changes SHOULD monitor the MachinePool's `spec.template.spec.bootstrap.configRef.name`
+field. When the reference name changes, this indicates a rotation has occurred and may require triggering a node rollout.
+
+This pattern is consistent with how MachineDeployments handle BootstrapTemplate rotations.
+
 ### Support for running multiple instances
 
 Cluster API does not support running multiples instances of the same provider, which someone can
@@ -502,8 +538,10 @@ The following diagram shows the typical logic for a bootstrap provider:
 [BootstrapConfig: terminal failures]: #bootstrapconfig-terminal-failures
 [BootstrapConfigTemplate, BootstrapConfigTemplateList resource definition]: #bootstrapconfigtemplate-bootstrapconfigtemplatelist-resource-definition
 [BootstrapConfigTemplate: support for SSA dry run]: #bootstrapconfigtemplate-support-for-ssa-dry-run
+[ClusterClass topology controller behavior for MachinePools]: #clusterclass-topology-controller-behavior-for-machinepools
 [Sentinel file]: #sentinel-file
 [Taint Nodes at creation]: #taint-nodes-at-creation
+[Infrastructure provider watching for bootstrap changes]: #infrastructure-provider-watching-for-bootstrap-changes
 [Support for running multiple instances]: #support-for-running-multiple-instances
 [Support running multiple instances of the same provider]: ../../core/support-multiple-instances.md
 [Clusterctl support]: #clusterctl-support
diff --git a/docs/book/src/developer/providers/contracts/infra-machinepool.md b/docs/book/src/developer/providers/contracts/infra-machinepool.md
@@ -55,6 +55,7 @@ To provide feedback or open a discussion about the provider contract please [ope
 | [InfraMachinePool: terminal failures]                                | No        |                                      |
 | [InfraMachinePoolTemplate, InfraMachineTemplatePoolList resource definition] | No | Mandatory for ClusterClasses support |
 | [InfraMachinePoolTemplate: support for SSA dry run]                  | No        | Mandatory for ClusterClasses support |
+| [ClusterClass topology controller behavior]                          | No        | Mandatory for ClusterClasses support |
 | [Multi tenancy]                                                      | No        | Mandatory for clusterctl CLI support |
 | [Clusterctl support]                                                 | No        | Mandatory for clusterctl CLI support |
 
@@ -495,6 +496,36 @@ The implementation requires to use controller runtime's `CustomValidator`, avail
 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.
 
+### ClusterClass topology controller behavior
+
+When using ClusterClass and managed topologies, the topology controller creates InfraMachinePool objects from InfraMachinePoolTemplates.
+Unlike templates (which are immutable), these InfraMachinePool objects have mutable specs, but the topology controller
+handles spec changes through a **rotation strategy** rather than in-place updates.
+
+When the topology controller detects that the InfraMachinePoolTemplate has changed (e.g., from template updates in ClusterClass), it performs
+a **rotation**:
+
+1. Creates a new InfraMachinePool object with a new name
+2. Copies `spec.providerIDList` from the old InfraMachinePool to the new one (to preserve instance tracking)
+3. Updates the MachinePool's `spec.template.spec.infrastructureRef` to reference the new object
+4. The old InfraMachinePool is garbage collected when no longer referenced
+
+<aside class="note">
+
+<h1>Provider expectations for rotation</h1>
+
+Providers SHOULD watch for changes to the MachinePool's `spec.template.spec.infrastructureRef.name` field.
+When the reference name changes, this indicates a rotation has occurred and the provider SHOULD:
+
+- Use the `spec.providerIDList` from the new InfraMachinePool to identify existing instances
+- Trigger any necessary rollout or reconciliation based on the spec changes
+
+This pattern is consistent with how MachineDeployments handle InfrastructureMachineTemplate rotations.
+
+</aside>
+
+Metadata-only changes (labels, annotations) MUST NOT trigger rotation; they are patched in-place on the existing object.
+
 ### Multi tenancy
 
 Multi tenancy in Cluster API defines the capability of an infrastructure provider to manage different credentials,
@@ -532,6 +563,7 @@ The clusterctl command is designed to work with all the providers compliant with
 [InfraMachinePool: terminal failures]: #inframachinepool-terminal-failures
 [InfraMachinePoolTemplate, InfraMachineTemplatePoolList resource definition]: #inframachinepooltemplate-inframachinetemplatepoollist-resource-definition
 [InfraMachinePoolTemplate: support for SSA dry run]: #inframachinepooltemplate-support-for-ssa-dry-run
+[ClusterClass topology controller behavior]: #clusterclass-topology-controller-behavior
 [MachinePoolMachines support]: #machinepoolmachines-support
 [Multi tenancy]: #multi-tenancy
 [Clusterctl support]: #clusterctl-support
