Kubernetes

Status: Development

Useful resources to understand Kubernetes objects and metadata:

The “name” of a Kubernetes object is unique for that type of object within a “namespace” and only at a specific moment of time (names can be reused over time). The “uid” is unique across your whole cluster, and very likely across time. Because of this it is recommended to always set the UID for every Kubernetes object, but “name” is usually more user friendly so can be also set.

Cluster

Status: Development

type: k8s.cluster

Description: A Kubernetes Cluster.

AttributeTypeDescriptionExamplesRequirement LevelStability
k8s.cluster.namestringThe name of the cluster.opentelemetry-clusterRecommendedDevelopment
k8s.cluster.uidstringA pseudo-ID for the cluster, set to the UID of the kube-system namespace. [1]218fc5a9-a5f1-4b54-aa05-46717d0ab26dRecommendedDevelopment

[1] k8s.cluster.uid: K8s doesn’t 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. 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.

Node

Status: Development

type: k8s.node

Description: A Kubernetes Node object.

AttributeTypeDescriptionExamplesRequirement LevelStability
k8s.node.namestringThe name of the Node.node-1RecommendedDevelopment
k8s.node.uidstringThe UID of the Node.1eb3a0c6-0477-4080-a9cb-0cb7db65c6a2RecommendedDevelopment
k8s.node.annotation.<key>stringThe annotation placed on the Node, the <key> being the annotation name, the value being the annotation value, even if the value is empty. [1]0; ``Opt-InDevelopment
k8s.node.label.<key>stringThe label placed on the Node, the <key> being the label name, the value being the label value, even if the value is empty. [2]arm64; ``Opt-InDevelopment

[1] k8s.node.annotation.<key>: Examples:

  • An annotation node.alpha.kubernetes.io/ttl with value 0 SHOULD be recorded as the k8s.node.annotation.node.alpha.kubernetes.io/ttl attribute with value "0".
  • An annotation data with empty string value SHOULD be recorded as the k8s.node.annotation.data attribute with value "".

[2] k8s.node.label.<key>: Examples:

  • A label kubernetes.io/arch with value arm64 SHOULD be recorded as the k8s.node.label.kubernetes.io/arch attribute with value "arm64".
  • A label data with empty string value SHOULD be recorded as the k8s.node.label.data attribute with value "".

Namespace

Namespaces provide a scope for names. Names of objects need to be unique within a namespace, but not across namespaces.

Status: Development

type: k8s.namespace

Description: A Kubernetes Namespace.

AttributeTypeDescriptionExamplesRequirement LevelStability
k8s.namespace.namestringThe name of the namespace that the pod is running in.defaultRecommendedDevelopment
k8s.namespace.annotation.<key>stringThe annotation key-value pairs placed on the Namespace. [1]k8s.namespace.annotation.ttl=0; k8s.namespace.annotation.data=Opt-InDevelopment
k8s.namespace.label.<key>stringThe label key-value pairs placed on the Namespace. [2]k8s.namespace.label.kubernetes.io/metadata.name=default; k8s.namespace.label.data=Opt-InDevelopment

[1] k8s.namespace.annotation.<key>: The <key> being the annotation name, the value being the annotation value, even if the value is empty.

[2] k8s.namespace.label.<key>: The <key> being the label name, the value being the label value, even if the value is empty.

Pod

The smallest and simplest Kubernetes object. A Pod represents a set of running containers on your cluster.

Status: Development

type: k8s.pod

Description: A Kubernetes Pod object.

AttributeTypeDescriptionExamplesRequirement LevelStability
k8s.pod.namestringThe name of the Pod.opentelemetry-pod-autoconfRecommendedDevelopment
k8s.pod.uidstringThe UID of the Pod.275ecb36-5aa8-4c2a-9c47-d8bb681b9affRecommendedDevelopment
k8s.pod.annotation.<key>stringThe annotation placed on the Pod, the <key> being the annotation name, the value being the annotation value. [1]true; x64; ``Opt-InDevelopment
k8s.pod.label.<key>stringThe label placed on the Pod, the <key> being the label name, the value being the label value. [2]my-app; x64; ``Opt-InDevelopment

[1] k8s.pod.annotation.<key>: Examples:

  • An annotation kubernetes.io/enforce-mountable-secrets with value true SHOULD be recorded as the k8s.pod.annotation.kubernetes.io/enforce-mountable-secrets attribute with value "true".
  • An annotation mycompany.io/arch with value x64 SHOULD be recorded as the k8s.pod.annotation.mycompany.io/arch attribute with value "x64".
  • An annotation data with empty string value SHOULD be recorded as the k8s.pod.annotation.data attribute with value "".

[2] k8s.pod.label.<key>: Examples:

  • A label app with value my-app SHOULD be recorded as the k8s.pod.label.app attribute with value "my-app".
  • A label mycompany.io/arch with value x64 SHOULD be recorded as the k8s.pod.label.mycompany.io/arch attribute with value "x64".
  • A label data with empty string value SHOULD be recorded as the k8s.pod.label.data attribute with value "".

Container

A container specification in a Pod template. This type is intended to be used to capture information such as name of a container in a Pod template which is different from the name of the running container.

Note: This type is different from container, which corresponds to a running container.

Status: Development

type: k8s.container

Description: A container in a PodTemplate.

AttributeTypeDescriptionExamplesRequirement LevelStability
k8s.container.namestringThe name of the Container from Pod specification, must be unique within a Pod. Container runtime usually uses different globally unique name (container.name).redisRecommendedDevelopment
k8s.container.restart_countintNumber of times the container was restarted. This attribute can be used to identify a particular container (running or stopped) within a container spec.RecommendedDevelopment
k8s.container.status.last_terminated_reasonstringLast terminated reason of the Container.Evicted; ErrorRecommendedDevelopment

ReplicaSet

Status: Development

type: k8s.replicaset

Description: A Kubernetes ReplicaSet object.

AttributeTypeDescriptionExamplesRequirement LevelStability
k8s.replicaset.namestringThe name of the ReplicaSet.opentelemetryRecommendedDevelopment
k8s.replicaset.uidstringThe UID of the ReplicaSet.275ecb36-5aa8-4c2a-9c47-d8bb681b9affRecommendedDevelopment
k8s.replicaset.annotation.<key>stringThe annotation key-value pairs placed on the ReplicaSet. [1]k8s.replicaset.annotation.replicas=0; k8s.replicaset.annotation.data=Opt-InDevelopment
k8s.replicaset.label.<key>stringThe label key-value pairs placed on the ReplicaSet. [2]k8s.replicaset.label.app=guestbook; k8s.replicaset.label.injected=Opt-InDevelopment

[1] k8s.replicaset.annotation.<key>: The <key> being the annotation name, the value being the annotation value, even if the value is empty.

[2] k8s.replicaset.label.<key>: The <key> being the label name, the value being the label value, even if the value is empty.

Deployment

An API object that manages a replicated application, typically by running Pods with no local state. Each replica is represented by a Pod, and the Pods are distributed among the nodes of a cluster.

Status: Development

type: k8s.deployment

Description: A Kubernetes Deployment object.

AttributeTypeDescriptionExamplesRequirement LevelStability
k8s.deployment.namestringThe name of the Deployment.opentelemetryRecommendedDevelopment
k8s.deployment.uidstringThe UID of the Deployment.275ecb36-5aa8-4c2a-9c47-d8bb681b9affRecommendedDevelopment
k8s.deployment.annotation.<key>stringThe annotation key-value pairs placed on the Deployment. [1]k8s.deployment.annotation.replicas=1; k8s.deployment.annotation.data=Opt-InDevelopment
k8s.deployment.label.<key>stringThe label key-value pairs placed on the Deployment. [2]k8s.deployment.label.app=guestbook; k8s.deployment.label.injected=Opt-InDevelopment

[1] k8s.deployment.annotation.<key>: The <key> being the annotation name, the value being the annotation value, even if the value is empty.

[2] k8s.deployment.label.<key>: The <key> being the label name, the value being the label value, even if the value is empty.

StatefulSet

Manages the deployment and scaling of a set of Pods, and provides guarantees about the ordering and uniqueness of these Pods.

Status: Development

type: k8s.statefulset

Description: A Kubernetes StatefulSet object.

AttributeTypeDescriptionExamplesRequirement LevelStability
k8s.statefulset.namestringThe name of the StatefulSet.opentelemetryRecommendedDevelopment
k8s.statefulset.uidstringThe UID of the StatefulSet.275ecb36-5aa8-4c2a-9c47-d8bb681b9affRecommendedDevelopment
k8s.statefulset.annotation.<key>stringThe annotation key-value pairs placed on the StatefulSet. [1]k8s.statefulset.annotation.replicas=1; k8s.statefulset.annotation.data=Opt-InDevelopment
k8s.statefulset.label.<key>stringThe label key-value pairs placed on the StatefulSet. [2]k8s.statefulset.label.app=guestbook; k8s.statefulset.label.injected=Opt-InDevelopment

[1] k8s.statefulset.annotation.<key>: The <key> being the annotation name, the value being the annotation value, even if the value is empty.

[2] k8s.statefulset.label.<key>: The <key> being the label name, the value being the label value, even if the value is empty.

DaemonSet

A DaemonSet ensures that all (or some) Nodes run a copy of a Pod.

Status: Development

type: k8s.daemonset

Description: A Kubernetes DaemonSet object.

AttributeTypeDescriptionExamplesRequirement LevelStability
k8s.daemonset.namestringThe name of the DaemonSet.opentelemetryRecommendedDevelopment
k8s.daemonset.uidstringThe UID of the DaemonSet.275ecb36-5aa8-4c2a-9c47-d8bb681b9affRecommendedDevelopment
k8s.daemonset.annotation.<key>stringThe annotation key-value pairs placed on the DaemonSet. [1]k8s.daemonset.annotation.replicas=1; k8s.daemonset.annotation.data=Opt-InDevelopment
k8s.daemonset.label.<key>stringThe label key-value pairs placed on the DaemonSet. [2]k8s.daemonset.label.app=guestbook; k8s.daemonset.label.injected=Opt-InDevelopment

[1] k8s.daemonset.annotation.<key>: The <key> being the annotation name, the value being the annotation value, even if the value is empty.

[2] k8s.daemonset.label.<key>: The <key> being the label name, the value being the label value, even if the value is empty.

Job

A Job creates one or more Pods and ensures that a specified number of them successfully terminate.

Status: Development

type: k8s.job

Description: A Kubernetes Job object.

AttributeTypeDescriptionExamplesRequirement LevelStability
k8s.job.namestringThe name of the Job.opentelemetryRecommendedDevelopment
k8s.job.uidstringThe UID of the Job.275ecb36-5aa8-4c2a-9c47-d8bb681b9affRecommendedDevelopment
k8s.job.annotation.<key>stringThe annotation key-value pairs placed on the Job. [1]k8s.job.annotation.number=1; k8s.job.annotation.data=Opt-InDevelopment
k8s.job.label.<key>stringThe label key-value pairs placed on the Job. [2]k8s.job.label.jobtype=ci; k8s.job.label.automated=Opt-InDevelopment

[1] k8s.job.annotation.<key>: The <key> being the annotation name, the value being the annotation value, even if the value is empty.

[2] k8s.job.label.<key>: The <key> being the label name, the value being the label value, even if the value is empty.

CronJob

A CronJob creates Jobs on a repeating schedule.

Status: Development

type: k8s.cronjob

Description: A Kubernetes CronJob object.

AttributeTypeDescriptionExamplesRequirement LevelStability
k8s.cronjob.namestringThe name of the CronJob.opentelemetryRecommendedDevelopment
k8s.cronjob.uidstringThe UID of the CronJob.275ecb36-5aa8-4c2a-9c47-d8bb681b9affRecommendedDevelopment
k8s.cronjob.annotation.<key>stringThe cronjob annotation placed on the CronJob, the <key> being the annotation name, the value being the annotation value. [1]4; ``Opt-InDevelopment
k8s.cronjob.label.<key>stringThe label placed on the CronJob, the <key> being the label name, the value being the label value. [2]weekly; ``Opt-InDevelopment

[1] k8s.cronjob.annotation.<key>: Examples:

  • An annotation retries with value 4 SHOULD be recorded as the k8s.cronjob.annotation.retries attribute with value "4".
  • An annotation data with empty string value SHOULD be recorded as the k8s.cronjob.annotation.data attribute with value "".

[2] k8s.cronjob.label.<key>: Examples:

  • A label type with value weekly SHOULD be recorded as the k8s.cronjob.label.type attribute with value "weekly".
  • A label automated with empty string value SHOULD be recorded as the k8s.cronjob.label.automated attribute with value "".

ReplicationController

A ReplicationController ensures that a specified number of pod replicas are running at any one time.

Status: Development

type: k8s.replicationcontroller

Description: A Kubernetes ReplicationController object.

AttributeTypeDescriptionExamplesRequirement LevelStability
k8s.replicationcontroller.namestringThe name of the replication controller.opentelemetryRecommendedDevelopment
k8s.replicationcontroller.uidstringThe UID of the replication controller.275ecb36-5aa8-4c2a-9c47-d8bb681b9affRecommendedDevelopment

HorizontalPodAutoscaler

A HorizontalPodAutoscaler (HPA for short) automatically updates a workload resource (such as a Deployment or StatefulSet), with the aim of automatically scaling the workload to match demand.

Status: Development

type: k8s.hpa

Description: A Kubernetes HorizontalPodAutoscaler object.

AttributeTypeDescriptionExamplesRequirement LevelStability
k8s.hpa.namestringThe name of the horizontal pod autoscaler.opentelemetryRecommendedDevelopment
k8s.hpa.uidstringThe UID of the horizontal pod autoscaler.275ecb36-5aa8-4c2a-9c47-d8bb681b9affRecommendedDevelopment

ResourceQuota

A ResourceQuota provides constraints that limit aggregate resource consumption per namespace.

Status: Development

type: k8s.resourcequota

Description: A Kubernetes ResourceQuota object.

AttributeTypeDescriptionExamplesRequirement LevelStability
k8s.resourcequota.namestringThe name of the resource quota.opentelemetryRecommendedDevelopment
k8s.resourcequota.uidstringThe UID of the resource quota.275ecb36-5aa8-4c2a-9c47-d8bb681b9affRecommendedDevelopment

Kubernetes specific guidelines

The following guidelines are specific to Kubernetes: