Skip to content

📖 document ClusterClass rotation behavior for MachinePool objects #13280

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
bnallapeta wants to merge 1 commit into
base: main
Choose a base branch
from
+70 −0
Open

📖 document ClusterClass rotation behavior for MachinePool objects #13280

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions docs/book/src/developer/providers/contracts/bootstrap-config.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 | |
Expand Down Expand Up @@ -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`
Expand All @@ -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
Copy link
Member

@sbueringer sbueringer Feb 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This page here is a description of the contract for bootstrap providers. I think we should not specify the infrastructure provider contract on this page


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
Expand Down Expand Up @@ -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
Expand Down
32 changes: 32 additions & 0 deletions docs/book/src/developer/providers/contracts/infra-machinepool.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |

Expand Down Expand Up @@ -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
Copy link
Member

@sbueringer sbueringer Feb 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@AndiDog @mboersma @richardcase Do we have consensus across InfraMachinePool providers that rotation is the right thing to do here?

I would have expected that just in-place updating the InfraMachinePool is much easier to implement for infra providers

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,
Expand Down Expand Up @@ -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
Expand Down
Loading