docs: document ClusterClass rotation behavior for MachinePool objects

Signed-off-by: Bharath Nallapeta <nr.bharath97@gmail.com>

Author: bnallapeta

docs/book/src/developer/providers/contracts/bootstrap-config.md

@@ -55,6 +55,7 @@ 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        |                                      |
 | [Support for running multiple instances]                                   | No        | Mandatory for clusterctl CLI support |
@@ -420,6 +421,38 @@ 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 are treated as
+**effectively immutable for spec changes**.
+
+When the topology controller detects spec changes to a BootstrapConfig used by a MachinePool (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.
+
+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.
+
+</aside>
+
+Note: Metadata-only changes (labels, annotations) do 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` 
@@ -502,6 +535,7 @@ 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
 [Support for running multiple instances]: #support-for-running-multiple-instances

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,35 @@ 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 are treated as **effectively immutable for spec changes**.
+
+When the topology controller detects spec changes to an InfraMachinePool (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>
+
+Note: Metadata-only changes (labels, annotations) do 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 +562,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