add k8s.cluster.uid resource attribute semconv (#3267)

Fixes #3266

## Changes

Kubernetes doesn't have a formal way to identify a cluster, but a
pseudo-id can be derived by taking the `uid` of the `kube-system`
namespace. This PR adds a convention for `k8s.cluster.uid` to be set to
the `kube-system` namespace uid.

CHANGELOG.md

@@ -101,6 +101,8 @@ release.
 
 ### Semantic Conventions
 
+- Add k8s.cluster.uid semantic convention
+  ([#3267](https://github.com/open-telemetry/opentelemetry-specification/pull/3267))
 - Clarify that attribute requirement levels apply to the instrumentation library
   ([#3289](https://github.com/open-telemetry/opentelemetry-specification/pull/3289))
 - Fix grammatical number of metric units.

semantic_conventions/resource/k8s.yaml

@@ -10,6 +10,35 @@ groups:
         brief: >
           The name of the cluster.
         examples: ['opentelemetry-cluster']
+      - id: uid
+        type: string
+        brief: >
+          A pseudo-ID for the cluster, set to the UID of the `kube-system`
+          namespace.
+        note: |
+          K8s does not have support for obtaining a cluster ID. If this is ever
+          added, we will recommend collecting the `k8s.cluster.uid` through the
+          official APIs. In the meantime, we are able to use the `uid` of the
+          `kube-system` namespace as a proxy for cluster ID. Read on for the
+          rationale.
+
+          Every object created in a K8s cluster is assigned a distinct UID. The
+          `kube-system` namespace is used by Kubernetes itself and will exist
+          for the lifetime of the cluster. Using the `uid` of the `kube-system`
+          namespace is a reasonable proxy for the K8s ClusterID as it will only
+          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.
+        examples: ['218fc5a9-a5f1-4b54-aa05-46717d0ab26d']
 
   - id: k8s.node
     prefix: k8s.node

specification/resource/semantic_conventions/k8s.md

@@ -25,6 +25,30 @@ Kubernetes object, but "name" is usually more user friendly so can be also set.
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
 | `k8s.cluster.name` | string | The name of the cluster. | `opentelemetry-cluster` | Recommended |
+| `k8s.cluster.uid` | string | A pseudo-ID for the cluster, set to the UID of the `kube-system` namespace. [1] | `218fc5a9-a5f1-4b54-aa05-46717d0ab26d` | Recommended |
+
+**[1]:** K8s does not have support for obtaining a cluster ID. If this is ever
+added, we will recommend collecting the `k8s.cluster.uid` through the
+official APIs. In the meantime, we are able to use the `uid` of the
+`kube-system` namespace as a proxy for cluster ID. Read on for the
+rationale.
+
+Every object created in a K8s cluster is assigned a distinct UID. The
+`kube-system` namespace is used by Kubernetes itself and will exist
+for the lifetime of the cluster. Using the `uid` of the `kube-system`
+namespace is a reasonable proxy for the K8s ClusterID as it will only
+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.
 <!-- endsemconv -->
 
 ## Node