add docs about deleting specific machines when downscaling

[kranurag7]

What would you like to be added (User Story)?

As an operator, I want to downscale the number of machines but I want to remove certain machines only.

Consider a case where I've 10 machines object and I want to remove only 3 specific machines.

Detailed Description

As of now, I think CAPI docs doesn't cover this part.

Ref: https://main.cluster-api.sigs.k8s.io/tasks/automated-machine-management/scaling.html#scaling-nodes

I searched in slack and found the following information.

• https://kubernetes.slack.com/archives/C8TSNPY4T/p1605129002289200
  The deletion of the machines can be controlled by an annotation cluster.x-k8s.io/delete-machine
  It works for both machinedeployments and kubeadmcontrolplane objects.

NOTE: The annotation doesn't need a value and we can use empty string as well. "cluster.x-k8s.io/delete-machine" : ""

Anything else you would like to add?

happy to send a patch once it's triaged.

Label(s) to be applied

/kind feature
/area documentation

[Sunnatillo]

sounds interesting, and it is valid for us a provider as well.

[fabriziopandini]

/triage accepted
/help

@kranurag7 It will be great if you can improve https://main.cluster-api.sigs.k8s.io/tasks/automated-machine-management/scaling.html#scaling-nodes

NOTE: we have https://main.cluster-api.sigs.k8s.io/reference/labels_and_annotations, but I agree that putting all the info relevant for scaling in a single place is valuable

[k8s-ci-robot]

@fabriziopandini:
This request has been marked as needing help from a contributor.

Guidelines

Please ensure that the issue body includes answers to the following questions:

• Why are we solving this issue?
• To address this issue, are there any code changes? If there are code changes, what needs to be done in the code and what places can the assignee treat as reference points?
• Does this issue have zero to low barrier of entry?
• How can the assignee reach out to you for help?

For more details on the requirements of such an issue, please see here and ensure that they are met.

If this request no longer meets these requirements, the label can be removed
by commenting with the /remove-help command.

In response to this:

/triage accepted
/help

@kranurag7 It will be great if you can improve https://main.cluster-api.sigs.k8s.io/tasks/automated-machine-management/scaling.html#scaling-nodes

NOTE: we have https://main.cluster-api.sigs.k8s.io/reference/labels_and_annotations, but I agree that putting all the info relevant for scaling in a single place is valuable

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/test-infra repository.

[kranurag7]

/assign

[fabriziopandini]

/priority backlog