Skip to content

📖 docs: add delete-machine info to Scaling Nodes page #13195

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
Merged
k8s-ci-robot merged 3 commits into from
Jan 5, 2026
Merged

📖 docs: add delete-machine info to Scaling Nodes page #13195

k8s-ci-robot merged 3 commits into from
Jan 5, 2026

Conversation

@Kausheel
Copy link
Contributor

@Kausheel Kausheel commented Dec 28, 2025

What this PR does:

The change adds a brief description of using cluster.x-k8s.io/delete-machine labels to control Machine scaling on the Scaling Nodes page. The label is mentioned in the supported labels but I think it's relevant to include it in the Scaling Nodes page too.

Which issue(s) this PR fixes

Fixes #10306

@k8s-ci-robot k8s-ci-robot added do-not-merge/invalid-commit-message Indicates that a PR should not merge because it has an invalid commit message. do-not-merge/needs-area PR is missing an area label labels Dec 28, 2025
@k8s-ci-robot k8s-ci-robot added size/XS Denotes a PR that changes 0-9 lines, ignoring generated files. needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. labels Dec 28, 2025
@k8s-ci-robot
Copy link
Contributor

k8s-ci-robot commented Dec 28, 2025

Hi @Kausheel. Thanks for your PR.

I'm waiting for a github.com 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.

Details

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.

@Kausheel
Copy link
Contributor Author

Kausheel commented Dec 28, 2025

/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. and removed do-not-merge/needs-area PR is missing an area label labels Dec 28, 2025
@Kausheel Kausheel mentioned this pull request Dec 28, 2025
Closed
@Kausheel
docs: add delete-machine info to Scaling Nodes page
e15292e 
The change adds a brief description of using `cluster.x-k8s.io/delete-machine` labels to control Machine scaling on
the [Scaling Nodes](https://cluster-api.sigs.k8s.io/tasks/automated-machine-management/scaling) page.
The label is mentioned in the [supported labels](https://main.cluster-api.sigs.k8s.io/reference/api/labels-and-annotations.html?highlight=labels#supported-labels) but I think it's relevant to include it in the Scaling Nodes page too.
@Kausheel Kausheel force-pushed the docs/add-delete-machine branch from a3c1b64 to e15292e Compare December 28, 2025 04:10
@k8s-ci-robot k8s-ci-robot removed the do-not-merge/invalid-commit-message Indicates that a PR should not merge because it has an invalid commit message. label Dec 28, 2025
@sbueringer
Copy link
Member

sbueringer commented Dec 29, 2025

/ok-to-test

We should probably add a disclaimer that the label only acts on the MachineSet level.
This means that if a MachineDeployment has multiple MachineSets there is no guarantee that the MachineDeployment will scale down the MS with the Machine with the annotation and accordingly that Machine gets deleted next.

I mention this because this misunderstanding lead to a major bug in the autoscaler

@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 Dec 29, 2025
fabriziopandini
fabriziopandini reviewed Dec 30, 2025
View reviewed changes
docs/book/src/tasks/automated-machine-management/scaling.md Outdated

You can scale MachineSets and MachineDeployments in or out by expressing intent via `.spec.replicas` or updating the scale subresource e.g `kubectl scale machinedeployment foo --replicas=5`.

If you need to prioritize which Machines get deleted during scale down, add the `cluster.x-k8s.io/delete-machine` label to the Machine. KCP or a MachineSet will delete labeled control plane or worker Machines first, and this label has top priority over all delete policies.
Copy link
Member

@fabriziopandini fabriziopandini Dec 30, 2025

Choose a reason for hiding this comment

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

I would suggest to add a note that explains that the annotation is considered only when scaling down a machine set; the decision about which machine set to scale down in a machine deployment is driven by other factors (e.g. primarily the fact that the MachineSet spec is UpToDate or not).

@Kausheel Kausheel force-pushed the docs/add-delete-machine branch from 628e113 to 6b19f38 Compare January 4, 2026 05:50
@Kausheel
Copy link
Contributor Author

Kausheel commented Jan 4, 2026

Thank you @fabriziopandini and @sbueringer for the suggestion, I've adding a small note to the delete-machine snippet now to clarify the label behavior.

hackeramitkumar
hackeramitkumar reviewed Jan 4, 2026
View reviewed changes
docs/book/src/tasks/automated-machine-management/scaling.md Outdated

You can scale MachineSets and MachineDeployments in or out by expressing intent via `.spec.replicas` or updating the scale subresource e.g `kubectl scale machinedeployment foo --replicas=5`.

If you need to prioritize which Machines get deleted during scale-down, add the `cluster.x-k8s.io/delete-machine` label to the Machine. KCP or a MachineSet will delete labeled control plane or worker Machines first, and this label has top priority over all delete policies. Note: The label only affects MachineSet scale-down; in a MachineDeployment, the choice of MachineSet to scale-down may bypass labeled Machines.
Copy link
Member

@hackeramitkumar hackeramitkumar Jan 4, 2026

Choose a reason for hiding this comment

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

Should we move this note to a new line?

Suggested change
If you need to prioritize which Machines get deleted during scale-down, add the `cluster.x-k8s.io/delete-machine` label to the Machine. KCP or a MachineSet will delete labeled control plane or worker Machines first, and this label has top priority over all delete policies. Note: The label only affects MachineSet scale-down; in a MachineDeployment, the choice of MachineSet to scale-down may bypass labeled Machines.
If you need to prioritize which Machines get deleted during scale-down, add the `cluster.x-k8s.io/delete-machine` label to the Machine. KCP or a MachineSet will delete labeled control plane or worker Machines first, and this label has top priority over all delete policies.
**Note:** The label only affects MachineSet scale-down. In a MachineDeployment, the choice of MachineSet to scale down may bypass labeled Machines.

Copy link
Contributor Author

@Kausheel Kausheel Jan 4, 2026

Choose a reason for hiding this comment

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

Thanks for the suggestion @hackeramitkumar , I've added the line spacing now.

@sbueringer sbueringer added the tide/merge-method-squash Denotes a PR that should be squashed by tide when it merges. label Jan 5, 2026
@sbueringer
Copy link
Member

sbueringer commented Jan 5, 2026

Thx!

/lgtm
/approve

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

k8s-ci-robot commented Jan 5, 2026

LGTM label has been added.

DetailsGit tree hash: cc4d628c7332ddf46b7af22c334c8718f6710638

@k8s-ci-robot
Copy link
Contributor

k8s-ci-robot commented Jan 5, 2026

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: sbueringer

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

The pull request process is described here

Details 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 the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Jan 5, 2026
@k8s-ci-robot k8s-ci-robot merged commit b932d9b into kubernetes-sigs:main Jan 5, 2026
17 checks passed
@k8s-ci-robot k8s-ci-robot added this to the v1.13 milestone Jan 5, 2026
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

@hackeramitkumar hackeramitkumar hackeramitkumar left review comments

Reviewers whose approvals may not affect merge requirements

Assignees

@sbueringer sbueringer

Labels

approved Indicates a PR has been approved by an approver from all required OWNERS files. 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/XS Denotes a PR that changes 0-9 lines, ignoring generated files. tide/merge-method-squash Denotes a PR that should be squashed by tide when it merges.

Projects

None yet

Milestone

v1.13

Development

Successfully merging this pull request may close these issues.

add docs about deleting specific machines when downscaling

5 participants

@Kausheel @k8s-ci-robot @sbueringer @fabriziopandini @hackeramitkumar