Skip to content

📖 docs: Consolidate MachinePool documentation #12810

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

Jump to bottom
Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

📖 docs: Consolidate MachinePool documentation #12810

wants to merge 1 commit into from
+126 −16

Conversation

bnallapeta
Copy link
Contributor

What this PR does / why we need it:

This PR consolidates and improves the MachinePool documentation structure to eliminate redundancy and create a better user experience.

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 #12794

  • Removed the duplicate "MachinePools vs MachineDeployments" section from the experimental features page
  • Added the new concepts/machinepool.md to the book navigation
  • Added cross-references between all the MachinePool docs so people can easily jump between concepts → how to enable → developer details
  • Made the experimental features page focus on actually enabling the feature instead of explaining concepts

/area documentation

@k8s-ci-robot k8s-ci-robot added area/documentation Issues or PRs related to documentation cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. labels Sep 30, 2025
@k8s-ci-robot
Copy link
Contributor

[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 assign sbueringer for approval. 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:

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

@k8s-ci-robot k8s-ci-robot added needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. size/L Denotes a PR that changes 100-499 lines, ignoring generated files. labels Sep 30, 2025
@k8s-ci-robot
Copy link
Contributor

Hi @bnallapeta. Thanks for your PR.

I'm waiting for a kubernetes-sigs member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

mboersma
mboersma reviewed Sep 30, 2025
View reviewed changes
Copy link
Contributor

@mboersma mboersma left a comment

Choose a reason for hiding this comment

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

This looks great! Just a few small comments.

docs/book/src/concepts/machinepool.md Outdated

### Use MachinePool when:

- **Cloud provider supports scaling group primitives**: AWS Auto Scaling Groups, Azure Virtual Machine Scale Sets, GCP Managed Instance Groups. These resources natively handle scaling, rolling upgrades, and health checks.
Copy link
Contributor

Choose a reason for hiding this comment

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

Should we perhaps mention OCI and Scaleway, the other two providers who support MachinePools? Also GCP isn't yet implemented so perhaps we shouldn't be listing it.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

GCP does have MachinePool references. And docs refer GCPManagedMachinePool. Can you help clarify?

Added the other two here and in the "What is a MachinePool" section too.

@mboersma
Copy link
Contributor

/ok-to-test

@k8s-ci-robot k8s-ci-robot added ok-to-test Indicates a non-member PR verified by an org member that is safe to test. and removed needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. labels Sep 30, 2025
mboersma
mboersma reviewed Sep 30, 2025
View reviewed changes
@bnallapeta
docs: add machinepool rationale doc
2d595db 
Signed-off-by: Bharath Nallapeta <[email protected]>
mboersma
mboersma approved these changes Oct 14, 2025
View reviewed changes
Copy link
Contributor

@mboersma mboersma left a comment

Choose a reason for hiding this comment

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

/lgtm

@k8s-ci-robot k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Oct 14, 2025
@k8s-ci-robot
Copy link
Contributor

LGTM label has been added.

Git tree hash: 04b34f16639523228b8b1b97160d41f7e1127d10

@sbueringer
Copy link
Member

Let me know once this ready for a final pass from my side (not sure who else might want to review this before merge)

@bnallapeta
Copy link
Contributor Author

Let me know once this ready for a final pass from my side (not sure who else might want to review this before merge)

It is ready. PTAL.

fabriziopandini
fabriziopandini reviewed Oct 15, 2025
View reviewed changes
docs/book/src/concepts/machinepool.md

- **Cloud provider supports scaling group primitives**: AWS Auto Scaling Groups, Azure Virtual Machine Scale Sets, GCP Managed Instance Groups, OCI Compute Instances, Scaleway Kapsule. These resources natively handle scaling, rolling upgrades, and health checks.
- **You want to leverage cloud provider-level features**: MachinePool enables direct use of cloud-native upgrade strategies (e.g., surge, maxUnavailable) and autoscaling behaviors.
- **You are operating medium-to-large node groups**: Managing 50+ nodes through individual Machine objects can add significant reconciliation overhead. MachinePool reduces this by consolidating the group into a single object.
Copy link
Member

@fabriziopandini fabriziopandini Oct 15, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

Q: Is this still correct?
With Machine Pool Machines, the load for core CAPI controller seems the same
Also there are features in CAPI designed to work at node level like MHC and reconciliation of providerID (so reconciliation overhead is the same also here)

Copy link
Member

@fabriziopandini fabriziopandini Oct 15, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

Also, there Cluster API users managing huge clusters (a few thousand of workers) with machine deployments, so I don't think that the size of node groups should be a differentiator
(same for "use MachineDeployment when")

docs/book/src/concepts/machinepool.md
Copy link
Member

Choose a reason for hiding this comment

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

I would suggest to merge this page in https://cluster-api.sigs.k8s.io/tasks/experimental-features/machine-pools instead of spreading knowledge relevant for the users in multiple places.

If this page becomes too complex/hard to read, let's create sub pages like we did for cluster class and runtime SDK

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@fabriziopandini fabriziopandini fabriziopandini left review comments

@elmiko elmiko Awaiting requested review from elmiko

@sivchari sivchari Awaiting requested review from sivchari

+1 more reviewer

@mboersma mboersma mboersma approved these changes

Reviewers whose approvals may not affect merge requirements

Assignees

@mboersma mboersma

Labels

area/documentation Issues or PRs related to documentation cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. lgtm "Looks good to me", indicates that a PR is ready to be merged. ok-to-test Indicates a non-member PR verified by an org member that is safe to test. size/L Denotes a PR that changes 100-499 lines, ignoring generated files.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Document rationale for machine pools

5 participants

@bnallapeta @k8s-ci-robot @mboersma @sbueringer @fabriziopandini