Kubernetes: How to populate resource attributes based on attributes, labels and transformation

.chloggen/k8s-label-recommendations.yaml

@@ -0,0 +1,9 @@
+change_type: enhancement
+
+component: k8s
+
+note: How to populate resource attributes based on attributes, labels and transformation
+
+issues: [236]
+
+subtext:

docs/resource/README.md

@@ -22,6 +22,11 @@ This document defines standard attributes for resources. These attributes are ty
   - [Semantic Attributes with Dedicated Environment Variable](#semantic-attributes-with-dedicated-environment-variable)
   - [Semantic Attributes with SDK-provided Default Value](#semantic-attributes-with-sdk-provided-default-value)
 - [Service](#service)
+  - [Service in Kubernetes](#service-in-kubernetes)
+    - [How `service.namespace` is calculated](#how-servicenamespace-is-calculated)
+    - [How `service.name` is calculated](#how-servicename-is-calculated)
+    - [How `service.version` is calculated](#how-serviceversion-is-calculated)
+    - [How `service.instance.id` is calculated](#how-serviceinstanceid-is-calculated)
 - [Telemetry SDK](#telemetry-sdk)
 - [Telemetry Distro](#telemetry-distro)
 - [Compute Unit](#compute-unit)
@@ -143,6 +148,72 @@ namespace = Company
 service.name = Shop.shoppingcart
 ```
 
+### Service in Kubernetes
+
+The following [service resource attributes](../attributes-registry/service.md) are recommended for Kubernetes services.
+
+There are different ways to calculate the service attributes.
+
+1. [Well-Known Labels](https://kubernetes.io/docs/reference/labels-annotations-taints/)
+2. Annotations on the pod template that have the `resource.opentelemetry.io/` prefix as described above
+3. A function of the Kubernetes resource attributes defined above
+
+This translation can typically be done by an OpenTelemetry Collector component like the
+[Kubernetes Attribute Processor](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/k8sattributesprocessor).
+
+Tools offering this functionality should provide an opt-in flag for the use of well-known labels,
+since users may not be aware that their labels are being used for this purpose.
+
+Each attribute has a priority order for how it should be calculated as described below.
+
+#### How `service.namespace` is calculated
+
+Choose the first value found:
+
+1. `pod.annotation[resource.opentelemetry.io/service.namespace]`
+2. `k8s.namespace.name`
+
+#### How `service.name` is calculated
+
+Choose the first value found:
+
+- `pod.annotation[resource.opentelemetry.io/service.name]`
+- `pod.label[app.kubernetes.io/instance]` (well-known label
+  [app.kubernetes.io/instance](https://kubernetes.io/docs/reference/labels-annotations-taints/#app-kubernetes-io-instance))
+- `pod.label[app.kubernetes.io/name]` (well-known label
+  [app.kubernetes.io/name](https://kubernetes.io/docs/reference/labels-annotations-taints/#app-kubernetes-io-name))
+- `k8s.deployment.name`
+- `k8s.replicaset.name`
+- `k8s.statefulset.name`
+- `k8s.daemonset.name`
+- `k8s.cronjob.name`
+- `k8s.job.name`
+- `k8s.pod.name`
+- `k8s.container.name`
+
+#### How `service.version` is calculated
+
+Choose the first value found:
+
+- `pod.annotation[resource.opentelemetry.io/service.version]`
+- `pod.label[app.kubernetes.io/version]` (well-known label
+  [app.kubernetes.io/version](https://kubernetes.io/docs/reference/labels-annotations-taints/#app-kubernetes-io-version))
+- calculate the version using algorithm described below
+
+1. calculate tag and digest using the algorithm described in the
+   [reference library](https://github.com/distribution/reference/blob/main/reference.go)
+2. choose the first value found:
+   - `<tag>@<digest>`
+   - `<digest>`
+   - `<tag>`
+
+#### How `service.instance.id` is calculated
+
+Choose the first value found:
+
+- `pod.annotation[resource.opentelemetry.io/service.instance.id]`
+- `concat([k8s.namespace.name, k8s.pod.name, k8s.container.name], '.')`
+
 ## Telemetry SDK
 
 <!-- semconv resource.telemetry.sdk -->

docs/resource/k8s.md

@@ -354,3 +354,11 @@ A CronJob creates Jobs on a repeating schedule.
 <!-- endsemconv -->
 
 [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status
+
+## Specify resource attributes using Kubernetes annotations
+
+All annotations with the `resource.opentelemetry.io/` prefix should be translated into the corresponding resource
+attributes.
+
+For example, the annotation `resource.opentelemetry.io/service.name` should be translated into the `service.name`
+attribute.