Last updated: June 15, 2026
Kubernetes Resources
This page documents how Dash0 identifies and names Kubernetes resources using Kubernetes semantic conventions from OpenTelemetry.
For real-world examples of how these rules solve fragmentation issues, see Why Resource Equality?
Equality Rules
Kubernetes resources are identified using a hierarchy of rules that prioritize the most stable and unique identifiers.
Kubernetes Workload Equality
For applications running in pods:
- By Pod UID:
k8s.pod.uid(unique across clusters)
The k8s.pod.uid attribute uniquely identifies a pod throughout its entire lifecycle, even across node migrations or restarts. This is the only pod-based equality rule. If k8s.pod.uid is not present, the resource will fall back to workload-level equality rules (deployment, daemonset, etc.) or service triplet equality.
Kubernetes Resource Equality
Cluster-level resources, such as namespaces and deployments, are identified separately from pod-level resources.
For aggregate metrics and events about Kubernetes resources (not pods):
- Workload Schedulers:
k8s.daemonset.uidORk8s.deployment.uidORk8s.replicaset.uidORk8s.statefulset.uidORk8s.cronjob.uidORk8s.job.uidORk8s.replicationcontroller.uid - Autoscaling:
k8s.hpa.uid - Storage:
k8s.persistentvolume.uidORk8s.persistentvolumeclaim.uid - Networking:
k8s.service.uid - Policy:
k8s.resourcequota.uid - Namespaces:
k8s.namespace.uidORk8s.namespace.name - Clusters:
k8s.cluster.uidORk8s.cluster.nameORaws.eks.cluster.arn
Generic Kubernetes Objects (k8s.object)
When Kubernetes telemetry comes from objects that do not have a dedicated semantic convention (e.g., custom resources, ConfigMaps, Secrets, Ingresses, or other objects collected via the k8sobjectsreceiver), Dash0 falls back to identifying them by k8s.object.uid. This prevents these resources from being incorrectly merged into the parent namespace, while still giving them a stable identity and a human-readable name from k8s.object.name.
This rule is evaluated only when no per-Kind workload attribute (Pod, Deployment, Service, etc.) is present on the resource.
Kubernetes Node Equality
Nodes are identified only when pod and workload attributes are absent, preventing node metrics from merging with pod metrics.
When k8s.node.name or k8s.node.id is set AND no pod/workload attributes are present:
- By Node ID:
k8s.node.idORk8s.node.name
Naming Rules
Kubernetes resource names are derived from Kubernetes-specific attributes, preferring human-readable names over UIDs.
| Condition | Name |
|---|---|
k8s.pod.name or k8s.pod.uid set | Pod name or UID |
k8s.job.name or k8s.job.uid set | Job name or UID |
k8s.cronjob.name or k8s.cronjob.uid set | CronJob name or UID |
k8s.daemonset.name or k8s.daemonset.uid set | DaemonSet name or UID |
k8s.replicaset.name or k8s.replicaset.uid set | ReplicaSet name or UID |
k8s.deployment.name or k8s.deployment.uid set | Deployment name or UID |
k8s.statefulset.name or k8s.statefulset.uid set | StatefulSet name or UID |
k8s.replicationcontroller.name or k8s.replicationcontroller.uid set | ReplicationController name or UID |
k8s.hpa.name or k8s.hpa.uid set | HorizontalPodAutoscaler name or UID |
k8s.persistentvolume.name or k8s.persistentvolume.uid set | PersistentVolume name or UID |
k8s.persistentvolumeclaim.name or k8s.persistentvolumeclaim.uid set | PersistentVolumeClaim name or UID |
k8s.service.name or k8s.service.uid set | Service name or UID |
k8s.resourcequota.name or k8s.resourcequota.uid set | ResourceQuota name or UID |
k8s.object.name or k8s.object.uid set (no namespace UID and no Kind-specific attrs) | Generic Kubernetes object name or UID |
k8s.namespace.name or k8s.namespace.uid set | Namespace name |
k8s.node.name or k8s.node.uid set (no workload attrs) | Node name or UID |
k8s.cluster.name, aws.eks.cluster.arn, or k8s.cluster.uid set | Cluster name, ARN, or UID |
The k8s.object.* naming rule is skipped when k8s.namespace.uid is present on the same resource. This ensures that a Namespace record carrying both attributes is named from k8s.namespace.*, not from the generic k8s.object.* keys.
Typing Rules
Kubernetes resource types are assigned based on the presence of specific Kubernetes attributes. Types enable filtering and visualization by resource category in Dash0.
| Condition | Type | UI Label |
|---|---|---|
k8s.pod.name or k8s.pod.uid set | k8s.pod | Pod |
k8s.cronjob.name or k8s.cronjob.uid set | k8s.cronjob | CronJob |
k8s.job.name or k8s.job.uid set | k8s.job | Job |
k8s.replicaset.name or k8s.replicaset.uid set | k8s.replicaset | ReplicaSet |
k8s.daemonset.name or k8s.daemonset.uid set | k8s.daemonset | DaemonSet |
k8s.deployment.name or k8s.deployment.uid set | k8s.deployment | Deployment |
k8s.statefulset.name or k8s.statefulset.uid set | k8s.statefulset | StatefulSet |
k8s.replicationcontroller.name or k8s.replicationcontroller.uid set | k8s.replicationcontroller | ReplicationController |
k8s.hpa.name or k8s.hpa.uid set | k8s.hpa | HorizontalPodAutoscaler |
k8s.persistentvolume.name or k8s.persistentvolume.uid set | k8s.persistentvolume | PersistentVolume |
k8s.persistentvolumeclaim.name or k8s.persistentvolumeclaim.uid set | k8s.persistentvolumeclaim | PersistentVolumeClaim |
k8s.service.name or k8s.service.uid set | k8s.service | Service |
k8s.resourcequota.name or k8s.resourcequota.uid set | k8s.resourcequota | ResourceQuota |
k8s.object.uid set (no Kind-specific attrs) | k8s.object | Other Kubernetes object |
k8s.namespace.name or k8s.namespace.uid set | k8s.namespace | Namespace |
k8s.node.name or k8s.node.uid set (no workload attrs) | k8s.node | Node |
k8s.cluster.name, aws.eks.cluster.arn, or k8s.cluster.uid set | k8s.cluster | Cluster |
Best Practices
- Use resource detectors in OpenTelemetry SDKs to automatically populate Kubernetes attributes
- Use the K8sAttributes processor in the OpenTelemetry Collector to enrich telemetry with Kubernetes metadata
- Configure log agents to include Kubernetes metadata when collecting pod logs
- Prioritize
k8s.pod.uidas it uniquely identifies pods across the cluster lifecycle
When using service meshes like Istio or Linkerd, pod association mechanisms based on IP address lookups may be unreliable due to sidecar proxies. For reliable resource correlation in service mesh environments, ensure your instrumentation includes k8s.pod.uid directly from the Downward API rather than relying on IP-based association. See Kubernetes Attributes Best Practices for detailed guidance.
Further Reading
For more information on resource equality and Kubernetes-specific configurations, explore the following resources.
Related Topics in This Section
- About Resources: Overview of resources in Dash0
- Explore Resources: Get started exploring resources in Dash0
- Why Resource Equality?: Practical examples of resource fragmentation scenarios
Dash0 Guides & Knowledge
- What are OpenTelemetry Resources?: Deep dive into how resources describe which system is generating telemetry data
- Service Attributes Best Practices: Learn what resource attributes are and how they can be categorized
- Kubernetes Attributes Best Practices: Best practices for Kubernetes resource attributes
OpenTelemetry Resources
- Kubernetes Semantic Conventions: Official specification for Kubernetes resource attributes
- k8sattributesprocessor: Enrich telemetry with Kubernetes metadata
- OpenTelemetry Collector: Learn about the OpenTelemetry Collector and processors