📖 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 (22f729e, 3e1ec90, 53b1241, 9e1b9fb)

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>

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

fabriziopandini · 2025-11-08T14:31:32Z

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

+
+The value from this field is surfaced via the MachinePool's `status.replicas` field.
+
+### InfraMachinePool: terminal failures


I think we should align ASAP to other CAPI resources WRT to terminal failures (deprecated, not anymore relevant for the controller)

I agree and slightly changed the wording.

Also in this case, I suggest to try to catch up with the rest of CAPI, otherwise it will be confusing for users when we have to explain e.g. "failureReason is gone everywhere but in MP things are different..."

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

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

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

AndiDog · 2025-11-11T07:34:59Z

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

+
+The goal of an InfraMachinePool is to manage the lifecycle of a provider-specific pool of machines using a provider specific service (like auto-scale groups in AWS & virtual machine scalesets in Azure).
+
+The machines in the pool may be physical or virtual instances (although most likely virtual), and they represent the infrastructure for Kubernetes nodes.


Suggested change

The machines in the pool may be physical or virtual instances (although most likely virtual), and they represent the infrastructure for Kubernetes nodes.

The machines in the pool may be physical or virtual instances, and they represent the infrastructure for Kubernetes nodes.

(comment is not relevant for the contract)

Theres a few lines in this document that are not directly relevant to the contract, but which instead provide background or hints. So i'm inclined to keep this as is.

AndiDog · 2025-11-11T08:30:02Z

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

+
+The [MachinePool's controller](../../core/controllers/machine-pool.md) is responsible to coordinate operations of the InfraMachinePool, and the interaction between the MachinePool's controller and the InfraMachinePool is based on the contract rules defined in this page.
+
+Once contract rules are satisfied by an InfraMachinePool implementation, other implementation details


What does this sentence mean? Can it be removed? Should we explicitly mention optional features such as single machine deletion here?

This sentence needs to stay as it's stating that the MachinePool controller coordinates with the InfraMachinePool and that this interaction is governed by the contract.

Its also consistent with the contract docs for InfraMachine: https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/book/src/developer/providers/contracts/infra-machine.md?plain=1#L10

Should we explicitly mention optional features such as single machine deletion here?

Is there something that is exposed via the contract that is relevant to this feature? There are general features of MachinePools that are not covered here (and should be covered in the general MachinePool docs IMHO).

It would be great to reword the sentence somehow, since I don't get the point that you mentioned for InfraMachine when reading this one.

Regarding single machine deletion – if you think it's out of scope here, maybe we can indeed then document it elsewhere as it's fully optional and has no implication on the contract IMO.

The line originally is based on something from the Machine contract. But i will reword to make it more clear, having the feedback that it snot clear what point is being made is really helpful. Thanks @AndiDog , i will try and get that rewording done today.

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?

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>

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.

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)

fabriziopandini · 2025-11-17T12:26:23Z

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

+
+The value from this field is surfaced via the MachinePool's `status.replicas` field.
+
+### InfraMachinePool: terminal failures


Also in this case, I suggest to try to catch up with the rest of CAPI, otherwise it will be confusing for users when we have to explain e.g. "failureReason is gone everywhere but in MP things are different..."

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

doc: review changes

22f729e

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

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

richardcase added 2 commits November 11, 2025 11:35

doc: review changes

9e1b9fb

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

docs: updates after second review

3e1ec90

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

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


		The value from this field is surfaced via the MachinePool's `status.replicas` field.

		### InfraMachinePool: terminal failures


		The goal of an InfraMachinePool is to manage the lifecycle of a provider-specific pool of machines using a provider specific service (like auto-scale groups in AWS & virtual machine scalesets in Azure).

		The machines in the pool may be physical or virtual instances (although most likely virtual), and they represent the infrastructure for Kubernetes nodes.


		The [MachinePool's controller](../../core/controllers/machine-pool.md) is responsible to coordinate operations of the InfraMachinePool, and the interaction between the MachinePool's controller and the InfraMachinePool is based on the contract rules defined in this page.

		Once contract rules are satisfied by an InfraMachinePool implementation, other implementation details


		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.

📖 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

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

edited

Loading