kubernetes / kubernetes/website

Document (accidentally private) annotation `api-approved.kubernetes.io`

Open
#30,764 31 comments 0 reactions 1 assignee Claimed by @deads2k View on GitHub
help wanted kind/bug lifecycle/frozen priority/backlog sig/api-machinery sig/architecture triage/accepted
Dominant language
HTML
Stars
5.4k
Forks
15.7k
Avg merge
4d 18h
Merged PRs (30d)
204

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

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.