Explain group/kind and GVK in relation to name clashes

[thernstig]

Within a namespace, only one object of a given kind can have a given name at a time.

The term kind above should be replaced by type. At least if I read it correctly according to the terminology:

• A resource type is the name used in the URL (pods, namespaces, services)
• All resource types have a concrete representation (their object schema) which is called a kind

[sftim]

/language en

What actually matters is the tuple of API group and resource type; we should clarify that. You can have two objects with the same name and same resource type if someone has - unhelpfully - set up the cluster to have the same type in different - unrelated - API groups. We usually recommend avoiding this.

/retitle Suggestion for Kubernetes API Concepts page

[thernstig]

@sftim that is something I was not aware about, and I have read a lot of Kubernetes docs. Is this explicitly stated somewhere? At least in the above page I linked it should be explicit then, so maybe that is the correct location to mention this.

I assume the API version does not matter in this case? I.e. in /apis/GROUP/VERSION/*?

[sftim]

We have a concept of a group-version-kind (GVK). https://book.kubebuilder.io/cronjob-tutorial/gvks.html has more on this.

If you create a v1 HorizontalPodAutoscaler named example you can't make a v2 HorizontalPodAutoscaler named example in the same namespace.

These are really .../autoscaling/v1/horizontalpodautoscalers/example and .../autoscaling/v1/horizontalpodautoscalers/example at the HTTP level (assuming I got the paths right) but both of those URLs lets you access the same object. If you delete .../autoscaling/v1/horizontalpodautoscalers/example then .../autoscaling/v2/horizontalpodautoscalers/example also goes. If you watch for v2 autoscalers, you see the outcome of updates using the v1 API. And vice versa.

I think we should update https://kubernetes.io/docs/reference/using-api/api-concepts/ to clarify the point.

[sftim]

/triage accepted /retitle Explain group/kind and GVK in relation to name clashes /wg api-expression /language en /priority backlog /lifecycle frozen

[k8s-triage-robot]

This issue has not been updated in over 1 year, and should be re-triaged.

You can:

• Confirm that this issue is still relevant with /triage accepted (org members only)
• Close this issue with /close

For more details on the triage process, see https://www.kubernetes.dev/docs/guide/issue-triage/

/remove-triage accepted