[k8s] Stabilise `k8s.pod` entity

[ChrsMark]

This issue tracks the stabilisation of the k8s.pod entity:

semantic-conventions/model/k8s/entities.yaml

Lines 39 to 51 in 330aaf5

	- id: entity.k8s.pod
	type: entity
	stability: development
	name: k8s.pod
	brief: >
	A Kubernetes Pod object.
	attributes:
	- ref: k8s.pod.uid
	- ref: k8s.pod.name
	- ref: k8s.pod.label
	requirement_level: opt_in
	- ref: k8s.pod.annotation
	requirement_level: opt_in

Required steps:

• Define identifying attributes
• Move to release_candidate
• Move to stable

[ChrsMark]

Identifying attributes proposal

To uniquely identify a Pod across clusters, the k8s.pod.uid and a cluster identifier is needed.

k8s.cluster.uid can be ambiguous though.

The k8sattributes processor of the Collector populates this using the uid of the kube-system namespace: https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/f562ab5d2aa8bdb3c11a205d072d99858116339f/processor/k8sattributesprocessor/documentation.md?plain=1#L13 (same for resourcedetection processor). This is approximately accurate but in theory there can be such k8s objects with same uids, since k8s.namespace.uid will only be unique per cluster if I'm not mistaken.

In this, probably we need to consider a new attribute for uniquely identifying a k8s cluster: k8s.cluster.url

k8s.cluster.url can be populated from the kubeadm-config configmap for clusters created using kube-adm while for clusters of cloud providers it can be collected from their APIs accordingly. We'd need to PoC this though before going on with making it part of the spec. But still, urls cannot 100% ensure uniqueness when local envs also come into the game.

@open-telemetry/semconv-k8s-approvers please share your thoughts on the above trade-off about using k8s.cluster.uid or k8s.cluster.url for ensuring uniqueness.

[dashpole]

since k8s.namespace.uid will only be unique per cluster if I'm not mistaken

Are you sure? https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#uids seems to imply the UUID is universally unique.

I think k8s.cluster.url would be much harder to populate consistently.

[ChrsMark]

Hmm, it seems you are right and I see it's already covered in SemConv:

semantic-conventions/model/k8s/registry.yaml

Lines 31 to 42 in 56b613e

	change if the cluster is rebuilt. Furthermore, Kubernetes UIDs are
	UUIDs as standardized by
	[ISO/IEC 9834-8 and ITU-T X.667](https://www.itu.int/ITU-T/studygroups/com17/oid.html).
	Which states:
	> If generated according to one of the mechanisms defined in Rec.
	> ITU-T X.667 | ISO/IEC 9834-8, a UUID is either guaranteed to be
	> different from all other UUIDs generated before 3603 A.D., or is
	> extremely likely to be different (depending on the mechanism chosen).
	Therefore, UIDs between clusters should be extremely unlikely to
	conflict.

(I was checking the k8s.cluster entity entry and missed the extensive description 🫤 ).

Based on this, we can claim that k8s.pod.uid is also universally unique and hence we don't need to include a cluster id too as an identifier? Not sure if this is already covered by entities' correlation though, a Pod belongs to a Cluster anyway.

[dashpole]

I believe that there will be some notion of entity relationships based on https://opentelemetry.io/docs/specs/otel/entities/data-model/, and based on previous conversations with @jsuereth.

Note: Entity relationship modelling will be refined in future specification work.

So I don't think identifying attributes are necessarily globally unique. But using k8s UIDs definitely seems like a good idea regardless.