kubernetes/website
View on GitHubDocument (accidentally private) annotation `api-approved.kubernetes.io`
Open
#30,764 opened on Dec 6, 2021
help wantedkind/buglifecycle/frozenpriority/backlogsig/api-machinerysig/architecturetriage/accepted
Repository metrics
- Stars
- (4,127 stars)
- PR merge metrics
- (Avg merge 16d 13h) (160 merged PRs in 30d)
Description
This is a Bug Report
Problem: Annotation api-approved.kubernetes.io is used, but not documented.
https://github.com/kubernetes/enhancements/tree/master/keps/sig-api-machinery/2337-k8s.io-group-protection mentions a private annotation that you must use if you're developing a custom API extension that uses a Kubernetes-reserved API group.
Proposed Solution:
Document the private annotation api-approved.kubernetes.io and when you might need to use it.
As I understand it:
- We should mention this annotation specially within https://kubernetes.io/docs/reference/labels-annotations-taints/ because this is a private annotation (doesn't contain
/- see https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/#syntax-and-character-set) and is not part of the Kubernetes annotation namespace.- Explain that it's a private annotation and the Kubernetes project has no plans to fix that aspect.
- However, we are breaking API conventions by requiring use of a private label on certain CRDs.
- We should document that private annotation as part of the CRD documentation.
Pages to Update:
- https://kubernetes.io/docs/reference/labels-annotations-taints/
- https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/
Additional Information: /sig api-machinery