📖 docs: machinepool contract spec #12971

richardcase · 2025-11-07T14:35:15Z

What this PR does / why we need it:

This adds documentation that details the contract for providers when implementing an infrastructure machine pool.

This has been created retrospectively from looking at a number of providers and the MachinePool controller.

Which issue(s) this PR fixes (optional, in fixes #<issue number>(, fixes #<issue_number>, ...) format, will close the issue(s) when PR gets merged):
Fixes #12799

/area machinepool

linux-foundation-easycla · 2025-11-07T14:35:20Z

The committers listed above are authorized under a signed CLA.

✅ login: richardcase / name: Richard Case (3e61afd, 4d5a858, 6191a7e, c0f0cca, ed15af9)

fabriziopandini

Thanks for this PR!
This really helps folks like me to step up knowledge about MachinePools!

docs/book/src/developer/providers/contracts/infra-machinepool.md

sbueringer · 2025-11-10T06:53:50Z

/assign

Would like to review after Fabrizio lgtm and before merge

richardcase · 2025-11-10T14:34:02Z

Thanks for your feedback @fabriziopandini . I will make updates based on this.

k8s-ci-robot · 2025-11-10T15:34:05Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please ask for approval from sbueringer. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

richardcase · 2025-11-10T15:59:06Z

@fabriziopandini - i have updated the doc based on your feedback.

docs/book/src/developer/providers/contracts/infra-machinepool.md

bnallapeta · 2025-11-11T11:35:17Z

@richardcase are we not going to document anything on the upgrades? My understanding is that the status would change based on the update strategy. For example:

Atomic updates:

status.replicas temporarily drops to 0
All providerIDs disappear then reappear
InfrastructureReady may flip to False

Rolling updates:

status.replicas stays >= desired (with surge) or slightly below
providerIDs change gradually (old removed, new added)
InfrastructureReady stays True

Should providers declare their update strategy in the contract so CAPI can adapt behavior accordingly?

richardcase · 2025-11-11T11:43:46Z

Should providers declare their update strategy in the contract so CAPI can adapt behavior accordingly?

@bnallapeta - i think we should follow up on this as we are trying to document the current state of the contract. Providers declaring an "update strategy" would be a change to the current contract.

We are going to need to update the MachinePool controller document based on the introduction of this contract doc. Perhaps we should include behaviour type stuff when we do that?

bnallapeta · 2025-11-11T11:44:43Z

@richardcase quoting from #10496,

Furthermore I don't know if there is a documented contract as of today for MachinePools how BootstrapConfigs are supposed to be rolled out. I also don't know if MachinePools behave the same across providers today.

I think we should talk about this in the contract. A few questions on this:

Should providers watch for bootstrap config changes and trigger updates? If yes, what's the signal? Hash of the secret data? ConfigRef version?

richardcase · 2025-11-11T11:44:50Z

Note for the maintainers, i will squash the commits when we are all happy with the doc.

richardcase · 2025-11-11T11:47:57Z

Should providers watch for bootstrap config changes and trigger updates? If yes, what's the signal? Hash of the secret data? ConfigRef version?

I agree i do think we need to document this in the MachinPools documentation. However, i don't think this sits in the contract document. Lets add this elsewhere, perhaps where i suggested earlier: https://cluster-api.sigs.k8s.io/developer/core/controllers/machine-pool when we make changes to that.

chrischdi · 2025-11-11T12:42:54Z

Note for the maintainers, i will squash the commits when we are all happy with the doc.

no need to

/label tide/merge-method-squash

fabriziopandini

Changes look good to, but I think we should take a bolder step with regards to moving to the new contract, otherwise it will be confusing for users and complicated for us to handle

fabriziopandini · 2025-11-17T12:12:01Z

docs/book/src/developer/providers/contracts/infra-machinepool.md

+
+A provider can opt-in to MachinePool Machines (MPM). With MPM machines all the replicas in a MachinePool are represented by a Machine & InfraMachine. This enables core CAPI to perform common operations on single machines (and their Nodes), such as draining a node before scale down, integration with Cluster Autoscaler and also [MachineHealthChecks].
+
+If you want to adopt MPM then you MUST have an `status.infrastructureMachineKind` field and the field must contain the resource kind that represents the replicas in the pool. This is usually named InfraMachine if machine pool machines are representable like regular machines, or InfraMachinePoolMachine in other cases. For example, for the AWS provider the value would be set to `AWSMachine`.


I'm not entirely sure I grasp the meaning of

This is usually named InfraMachine if machine pool machines are representable like regular machines, or InfraMachinePoolMachine in other cases.

I have reworded this, hopefully it makes more sense now.

fabriziopandini · 2025-11-17T12:18:00Z

docs/book/src/developer/providers/contracts/infra-machinepool.md

+Currently this is done by setting `status.ready` to **true**.  The value returned here is stored in the MachinePool's `status.infraStructureReady` field.
+
+Additionally providers should set `initialization.provisioned` to **true**. This value isn't currently used by core CAPI for MachinePools. However, MachinePools will start to use this instead and `status.ready` will be deprecated. By setting both these fields it will make the future migration easier.


I'm not sure asking providers to have both provides benefit, e.g. for other contract we ask to have one, depending on the contract they declare the provider is supporting.

Also, do you have a timeline in mind for for this to happen?

(for sake of simplicity I would prefer if there is only one way to transition from one contract version to another; similarly it will be easier to manage if we can align the timeline to v1beta1 removal)

Updated this section as we discussed.

docs/book/src/developer/providers/contracts/infra-machinepool.md

sbueringer · 2025-11-26T04:03:16Z

@richardcase Do you have time to address the final findings so we can merge this PR? Thx!

richardcase · 2025-11-28T14:57:30Z

Do you have time to address the final findings so we can merge this PR? Thx!

I do. Sorry for the delay, i kind of got consumed by some downstream work. Chatting with Fabrizio in a bit to clarify a point, and then I'll get the last edits done today.

This adds documentation that details the contract for providers when implementing an infrastructure machine pool. This has been created retrospectively from looking at a number of providers and the MachinePool controller. Signed-off-by: Richard Case <richard.case@outlook.com>

Changes after the first review by Fabrizio. Signed-off-by: Richard Case <richard.case@outlook.com>

Some updates after an additional review by Andreas. Signed-off-by: Richard Case <richard.case@outlook.com>

Various updates after review by Fabrizio and Andreas. Specifically: - Making it clearer what is preferred state vs current deprecated - Rewording some parts to be clearer. Signed-off-by: Richard Case <richard.case@outlook.com>

richardcase · 2025-11-28T16:51:30Z

This should be good to go now.

AndiDog

LGTM

AndiDog · 2025-12-01T08:37:24Z

docs/book/src/developer/providers/contracts/infra-machinepool.md

+
+```
+
+Once `status.initialization.provisioned` is set the MachinePool "core" controller will bubble this info in the MachinePool's `status.initialization.infrastructureProvisioned`; also InfraMachinePools’s `spec.providerIDList` and `status.replicas` will be surfaced on MachinePool’s corresponding fields at the same time.


Suggested change

Once `status.initialization.provisioned` is set the MachinePool "core" controller will bubble this info in the MachinePool's `status.initialization.infrastructureProvisioned`; also InfraMachinePools’s `spec.providerIDList` and `status.replicas` will be surfaced on MachinePool’s corresponding fields at the same time.

Once `status.initialization.provisioned` is set, the MachinePool "core" controller will bubble this info in the MachinePool's `status.initialization.infrastructureProvisioned`; also InfraMachinePools’s `spec.providerIDList` and `status.replicas` will be surfaced on MachinePool’s corresponding fields at the same time.

k8s-ci-robot added do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. area/machinepool Issues or PRs related to machinepools labels Nov 7, 2025

k8s-ci-robot added the cncf-cla: no Indicates the PR's author has not signed the CNCF CLA. label Nov 7, 2025

k8s-ci-robot requested a review from elmiko November 7, 2025 14:35

k8s-ci-robot added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label Nov 7, 2025

k8s-ci-robot requested a review from sivchari November 7, 2025 14:35

richardcase force-pushed the machinepool_contract_doc branch from d1d60f8 to 271c8df Compare November 7, 2025 14:40

k8s-ci-robot added cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. and removed cncf-cla: no Indicates the PR's author has not signed the CNCF CLA. labels Nov 7, 2025

richardcase force-pushed the machinepool_contract_doc branch from 271c8df to 5cc7517 Compare November 7, 2025 15:00

k8s-ci-robot added size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. and removed size/L Denotes a PR that changes 100-499 lines, ignoring generated files. labels Nov 7, 2025

richardcase force-pushed the machinepool_contract_doc branch from 5cc7517 to 53b1241 Compare November 7, 2025 15:02

richardcase changed the title ~~[WIP] 📖 docs: machinepool contract spec~~ 📖 docs: machinepool contract spec Nov 7, 2025

k8s-ci-robot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Nov 7, 2025

chrischdi mentioned this pull request Nov 7, 2025

Minimal MachinePool support kubernetes-sigs/cluster-api-provider-gcp#1506

Open

fabriziopandini reviewed Nov 8, 2025

View reviewed changes

k8s-ci-robot assigned sbueringer Nov 10, 2025

richardcase force-pushed the machinepool_contract_doc branch from cbf9bc7 to 22f729e Compare November 10, 2025 15:44

AndiDog reviewed Nov 11, 2025

View reviewed changes

k8s-ci-robot added the tide/merge-method-squash Denotes a PR that should be squashed by tide when it merges. label Nov 11, 2025

fabriziopandini reviewed Nov 17, 2025

View reviewed changes

This was referenced Nov 28, 2025

Audit machinepool CRD #13069

Open

Clarify contract between MP API and cloud provider #13068

Open

richardcase added 5 commits November 28, 2025 16:40

doc: review changes

4d5a858

Changes after the first review by Fabrizio. Signed-off-by: Richard Case <richard.case@outlook.com>

doc: review changes

6191a7e

Changes after the first review by Fabrizio. Signed-off-by: Richard Case <richard.case@outlook.com>

docs: updates after second review

c0f0cca

Some updates after an additional review by Andreas. Signed-off-by: Richard Case <richard.case@outlook.com>

docs: incorporate feedback from review

ed15af9

Various updates after review by Fabrizio and Andreas. Specifically: - Making it clearer what is preferred state vs current deprecated - Rewording some parts to be clearer. Signed-off-by: Richard Case <richard.case@outlook.com>

richardcase force-pushed the machinepool_contract_doc branch from 3e1ec90 to ed15af9 Compare November 28, 2025 16:48

fabriziopandini mentioned this pull request Nov 28, 2025

📖 Improve v1.12 migration docs #13079

Open

AndiDog reviewed Dec 1, 2025

View reviewed changes


		A provider can opt-in to MachinePool Machines (MPM). With MPM machines all the replicas in a MachinePool are represented by a Machine & InfraMachine. This enables core CAPI to perform common operations on single machines (and their Nodes), such as draining a node before scale down, integration with Cluster Autoscaler and also [MachineHealthChecks].

		If you want to adopt MPM then you MUST have an `status.infrastructureMachineKind` field and the field must contain the resource kind that represents the replicas in the pool. This is usually named InfraMachine if machine pool machines are representable like regular machines, or InfraMachinePoolMachine in other cases. For example, for the AWS provider the value would be set to `AWSMachine`.

		Currently this is done by setting `status.ready` to true. The value returned here is stored in the MachinePool's `status.infraStructureReady` field.

		Additionally providers should set `initialization.provisioned` to true. This value isn't currently used by core CAPI for MachinePools. However, MachinePools will start to use this instead and `status.ready` will be deprecated. By setting both these fields it will make the future migration easier.


		```

		Once `status.initialization.provisioned` is set the MachinePool "core" controller will bubble this info in the MachinePool's `status.initialization.infrastructureProvisioned`; also InfraMachinePools’s `spec.providerIDList` and `status.replicas` will be surfaced on MachinePool’s corresponding fields at the same time.

📖 docs: machinepool contract spec #12971

Are you sure you want to change the base?

📖 docs: machinepool contract spec #12971

Conversation

richardcase commented Nov 7, 2025

Uh oh!

linux-foundation-easycla bot commented Nov 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

fabriziopandini left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sbueringer commented Nov 10, 2025

Uh oh!

richardcase commented Nov 10, 2025

Uh oh!

k8s-ci-robot commented Nov 10, 2025

Uh oh!

richardcase commented Nov 10, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bnallapeta commented Nov 11, 2025

Uh oh!

richardcase commented Nov 11, 2025

Uh oh!

bnallapeta commented Nov 11, 2025

Uh oh!

richardcase commented Nov 11, 2025

Uh oh!

richardcase commented Nov 11, 2025

Uh oh!

chrischdi commented Nov 11, 2025

Uh oh!

fabriziopandini left a comment

Choose a reason for hiding this comment

Uh oh!

fabriziopandini Nov 17, 2025

Choose a reason for hiding this comment

Uh oh!

richardcase Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

fabriziopandini Nov 17, 2025

Choose a reason for hiding this comment

Uh oh!

richardcase Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sbueringer commented Nov 26, 2025

Uh oh!

richardcase commented Nov 28, 2025

Uh oh!

richardcase commented Nov 28, 2025

Uh oh!

AndiDog left a comment

Choose a reason for hiding this comment

Uh oh!

AndiDog Dec 1, 2025

Choose a reason for hiding this comment

Uh oh!

linux-foundation-easycla bot commented Nov 7, 2025 •

edited

Loading