Missing documentation: Supported annotations and labels

[randomvariable]

What steps did you take and what happened:

Have had a number of customer issues that could have been alleviated if people knew about the use of the pause annotations. The pause annotation for example is mentioned with regards to the machine health check but it has broader applicability.

In addition, when doing a code walkthrough, I stumbled across the interruptible node label, which is documented in one of the CAEPs but appears nowhere in the book with a concise summary as to why you want to use it.

/help

What did you expect to happen:

Annotations and labels are documented.

Anything else you would like to add:
[Miscellaneous information that will assist in solving the issue.]

It is probably worth having one reference document with all of the annotations and labels.

Environment:

• Cluster-api version:
• Minikube/KIND version:
• Kubernetes version: (use kubectl version):
• OS (e.g. from /etc/os-release):

/kind bug
[One or more /area label. See https://github.com/kubernetes-sigs/cluster-api/labels?q=area for the list of labels]

/help

[k8s-ci-robot]

@randomvariable:
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:

What steps did you take and what happened:

Have had a number of customer issues that could have been alleviated if people knew about the use of the pause annotations. The pause annotation for example is mentioned with regards to the machine health check but it has broader applicability.

In addition, when doing a code walkthrough, I stumbled across the interruptible node label, which is documented in one of the CAEPs but appears nowhere in the book with a concise summary as to why you want to use it.

/help

What did you expect to happen:

Annotations and labels are documented.

Anything else you would like to add:
[Miscellaneous information that will assist in solving the issue.]

It is probably worth having one reference document with all of the annotations and labels.

Environment:

• Cluster-api version:
• Minikube/KIND version:
• Kubernetes version: (use kubectl version):
• OS (e.g. from /etc/os-release):

/kind bug
[One or more /area label. See https://github.com/kubernetes-sigs/cluster-api/labels?q=area for the list of labels]

/help

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.

[randomvariable]

/good-first-issue

[k8s-ci-robot]

@randomvariable:
This request has been marked as suitable for new contributors.

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-good-first-issue command.

In response to this:

/good-first-issue

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.

[randomvariable]

/kind documentation

[chetak123]

/assign @chetak123

[vincepri]

/milestone v1.1

[k8s-triage-robot]

The Kubernetes project currently lacks enough contributors to adequately respond to all issues and PRs.

This bot triages issues and PRs according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue or PR as fresh with /remove-lifecycle stale
• Mark this issue or PR as rotten with /lifecycle rotten
• Close this issue or PR with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

[fabriziopandini]

/lifecycle frozen

[mehabhalodiya]

Hey @randomvariable
I would like to document "annotation and labels".
Will you please give me a brief idea on resolving this by providing some reference links?
Thanks.

[fabriziopandini]

Hi @mehabhalodiya thanks for picking up this work!
I think that a good starting point for this effort is to look at the labels/annotations defined in our API packages:

• https://pkg.go.dev/sigs.k8s.io/cluster-api/api/v1beta1
• https://pkg.go.dev/sigs.k8s.io/cluster-api/bootstrap/kubeadm/api/v1beta1
• https://pkg.go.dev/sigs.k8s.io/cluster-api/controlplane/kubeadm/api/v1beta1
• https://pkg.go.dev/sigs.k8s.io/cluster-api/exp/api/v1beta1
• https://pkg.go.dev/sigs.k8s.io/cluster-api/exp/addons/api/v1beta1

[SubhasmitaSw]

Hey @mehabhalodiya are you still working on it or may I pick this up?

[mehabhalodiya]

@SubhasmitaSw you can work on it.
Thanks!

[SubhasmitaSw]

Thanks @mehabhalodiya
/assign

[killianmuldoon]

@SubhasmitaSw have you had any time to work on this?

[killianmuldoon]

#6966 Related - we should document spec fields and annotations together if possible.

[fabriziopandini]

/triage accepted
/unassign @SubhasmitaSw

[hackeramitkumar]

@fabriziopandini , I would like to work on this issue. Can you please assign it to me? And If possible show me a sample list So that I can get a basic idea.

[fabriziopandini]

/assign @hackeramitkumar
(I think you can assign yourself)

I will start bu adding a page in the book under reference with two paragraphs, one for supported labels and the other for supported annotations.
Each paragraph should have a table with label/annotation and note.

then you have to search in the locations listed in #5394 (comment)

for things like

cluster-api/api/v1beta1/common_types.go

Lines 25 to 27 in bb6df67

	// ClusterLabelName is the label set on machines linked to a cluster and
	// external objects(bootstrap and infrastructure providers).
	ClusterLabelName = "cluster.x-k8s.io/cluster-name"

and grab the label/annotation name + the description, something like

label	note
cluster.x-k8s.io/cluster-name	this label is set on machines linked to a cluster and external objects(bootstrap and infrastructure providers)