K8s naming convention rational and additional documentation (#2252)

.chloggen/k8s-naming.yaml

@@ -0,0 +1,7 @@
+change_type: enhancement
+
+component: k8s
+
+note: Explains the rationale behind the Kubernetes resource naming convention.
+
+issues: [2245]

.github/CODEOWNERS

@@ -77,10 +77,11 @@
 /model/mobile/                    @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-client-approvers
 
 # K8s semantic conventions
-/docs/resource/k8s.md                 @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-k8s-approvers
-/model/k8s/                           @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-k8s-approvers
-/docs/non-normative/k8s-attributes.md @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-k8s-approvers
-/docs/non-normative/k8s-migration.md  @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-k8s-approvers
+/docs/resource/k8s.md                           @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-k8s-approvers
+/model/k8s/                                     @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-k8s-approvers
+/docs/non-normative/k8s-attributes.md           @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-k8s-approvers
+/docs/non-normative/k8s-migration.md            @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-k8s-approvers
+/docs/non-normative/naming-known-exceptions.md  @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-k8s-approvers
 
 # Container semantic conventions
 /docs/resource/container.md       @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-container-approvers

docs/general/naming.md

@@ -75,6 +75,8 @@ Names SHOULD follow these rules:
   words by underscores (i.e. use snake_case). For example
   `http.response.status_code` denotes the status code in the http namespace.
 
+  Known exceptions include [K8s API names](../non-normative/naming-known-exceptions.md#kubernetes-naming-exceptions) where a single word is used for consistency with the instrumented API.
+
   Use underscore only when using dot (namespacing) does not make sense or changes
   the semantic meaning of the name. For example, use `rate_limiting`
   instead of `rate.limiting`.

docs/non-normative/naming-known-exceptions.md

@@ -0,0 +1,20 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: Naming known exceptions 
+--->
+
+# Kubernetes naming exceptions
+
+Kubernetes users are accustomed to the single-word resource names used in the Kubernetes API (e.g., `replicaset`, `statefulset`, `daemonset`, `replicationcontroller`, `resourcequota`). Using these same names in telemetry data makes it easier for users to map the data to familiar Kubernetes concepts and commands (e.g., `kubectl get replicaset`).
+
+When naming entities, attributes, or metrics related to Kubernetes objects, prioritize using the exact single-word form from the official Kubernetes API object names (i.e., borrow the existing single-word term from the API when there is a 1:1 mapping). The official list of API object names can be found in the [Kubernetes API reference documentation](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.33/). For new terms or fields, follow the [general naming considerations](../general/naming.md).
+
+## Naming Recommendations
+
+- For resources that map 1:1 to Kubernetes API object names, use the exact single-word form from the Kubernetes API (no underscores, words concatenated as in the API).
+
+### Examples
+
+```text
+Use:    k8s.replicaset.uid      (not k8s.replica_set.uid)
+Use:    k8s.resourcequota.uid   (not k8s.resource_quota.uid)
+```

docs/resource/k8s.md

@@ -531,3 +531,4 @@ A ResourceQuota provides constraints that limit aggregate resource consumption p
 The following guidelines are specific to Kubernetes:
 
 - [Service in Kubernetes](../non-normative/k8s-attributes.md#service-attributes)
+- [Additional naming guidance for Kubernetes](../non-normative/naming-known-exceptions.md#kubernetes-naming-exceptions)