Publish reference documentation on Kubernetes resource labels and annotations

marians commented 7 months ago

User story

As an engineer working with Kubernetes resources in Giant Swarm clusters, I want to understand why a label exists on a resource and what effect it has.

As an engineer creating charts for deployment in a Giant Swarm cluster, I want to know which labels resources are expected to have and why, and which values these should have.

Details

I propose creation of a single reference page where all labels we care about can be found. For each label, a description should be given. If possible, a link to further information should be added, pointing to the authoritative source for this item.

The page should be structured by label namespace (prefix).

For annotations, a very similar but separate page could be published.

This should be part of our reference docs at docs.giantswarm.io.

Status quo

Mistakes are being made already. Some examples:

https://github.com/giantswarm/giantswarm/issues/22473
app.giantswarm.io/* was changed to application.giantswarm.io/*, but the former is still more common.
https://github.com/giantswarm/giantswarm/issues/30178
While many resources have application.giantswarm.io/team, some have app.giantswarm.io/team
One app uses app.kubernetes.io/app, which is not documented upstream

Material we have

Previously we have gathered some info in this page:

https://github.com/giantswarm/fmt/blob/main/kubernetes/annotations_and_labels.md

Also we maintain a library https://github.com/giantswarm/k8smetadata

### Tasks
- [ ] Create labels and annotations stub pages in docs
- [ ] Collect data about labels in use, focused on CAPI
- [ ] Discuss whether we can consolidate the source of truth and remove [the fmt page](https://github.com/giantswarm/fmt/blob/main/kubernetes/annotations_and_labels.md)
- [ ] Promote knowledge about this effort in KaaS and Platform area, discuss how maintenance can work

pipo02mix commented 7 months ago

I really like the idea. It will perfectly fit in new reference doc section :)

marians commented 5 months ago

We have discussed this topic in SIG Dev on April 4.

I'm going to work on a suggestion how we can make the k8smetadata library the source of the generated documentation.

We may need a custom tag format, or structured comments, so that we can capture structured data regarding the label "consumers".

giantswarm / roadmap