Package: opentelemetry-resourcedetector-kubernetes
opentelemetry-resourcedetector-kubernetesAn OpenTelemetry package to populates Resource attributes for Kubernetes pods.Usagefromopentelemetry.sdk.resourcesimportget_aggregated_resourcesfromopentelemetry_resourcedetector_kubernetesimportKubernetesResourceDetector...resource=get_aggregated_resources([KubernetesResourceDetector(),SomeOtherResourceDetector()])...passthereturned`resource`toaTracerProvder,forexample...TheKubernetesResourceDetectoris able to detect the basic identifying information
for aPod, returning asResourcewith these attributes populated:container.runtime- always the string"kubernetes"container.id- the unique ID of the container (a string of hexadecimal characters)k8s.pod.uid- the UUID of the pod where your container and code is runningThis resource detector is the base class for the others in this package, and so you
will always get these three attributes in your traces, using any of the more detailed
detectors below.Detecting more attributes with The "Downward API"The Kubernetes "Downward API" is a safe way to to pass Kubernetes metadata about your
pod to itself, as either:environment variables,
implemented byKubernetesDownwardAPIEnvironmentResourceDetector, orfiles in a volume mounted to your pod,
implemented byKubernetesDownwardAPIVolumeResourceDetectorFor either of these methods to work, you will need to add the appropriate configuration
to your Kubernetes manifests, and you'll configure the detector accordingly.Theopentelemetry_resourcedetector_kubernetesclasses using the Downward API will only
detect and populate attributes from thestandard OpenTelemetry Kubernetes Resource Attributethat you choose to provide by configuring them in your manifests.  These detectors will
only reportk8s.*andcontainer.*OpenTelemetry attributes, and are not intended to
be a general-purpose collection mechanism for other types of attributes.The Downward API only supports asubset of all the possible attributesyou could
provide.  Depending on your needs, you can also provide hard-coded environment variables
following the same naming conventino in your Kubernetes manifest, or mix the environment
and volume approaches to paint a more complete picture.KubernetesDownwardAPIEnvironmentResourceDetectorFor an example of using environment variables, you can pass a Pod's namespace and name:apiVersion:v1kind:Podmetadata:namespace:cool-appname:example-podspec:containers:-name:a-containerimage:my-image:1.0.0command:["run-my-cool-app"]env:-name:OTEL_RD_K8S_NAMESPACE_NAMEvalueFrom:fieldRef:fieldPath:metadata.namespace-name:OTEL_RD_K8S_POD_NAMEvalueFrom:fieldRef:fieldPath:metadata.nameThen, your running pod will see these environment variables populated:OTEL_RD_K8S_NAMESPACE_NAME=cool-appOTEL_RD_K8S_POD_NAME=example-podWhen configuring your telemetry, you'll establish a "contract" for the names of the
environment variables, indicating that they will be prefixed withOTEL_RD.  The
prefix is up to you, but the default isOTEL_RD.  From there, the resource detector
will look for each environment variables prefixed withOTEL_RD_, and if the rest of
its name matches astandard OpenTelemetry Kubernetes Resource Attribute,
it will be used during resource detection.fromopentelemetry.sdk.resourcesimportget_aggregated_resourcesfromopentelemetry_resourcedetector_kubernetesimportKubernetesDownwardAPIEnvironmentResourceDetector...resource=get_aggregated_resources([KubernetesDownwardAPIEnvironmentResourceDetector(prefix='OTEL_RD'),SomeOtherResourceDetector()])...passthereturned`resource`toaTracerProvder,forexample...In this example, theResourcefor all traces would include the attributes:container.runtime = "kubernetes"
k8s.pod.uid = "...the UUID of the pod..."
container.id = "...the id of the container..."

k8s.namespace.name = "cool-app"
k8s.pod.name = "example-pod"KubernetesDownwardAPIVolumeResourceDetectorFor an example of using a Downward API volume, you can pass a Pod's namespace and name:apiVersion:v1kind:Podmetadata:namespace:cool-appname:example-podspec:containers:-name:a-containerimage:my-image:1.0.0command:["run-my-cool-app"]volumeMounts:# this is at the *Container* level-name:otelrdmountPath:/etc/otelrdvolumes:# this is at the *Pod* level-name:otelrddownwardAPI:items:-path:k8s.namespace.namefieldRef:fieldPath:metadata.namespace-path:k8s.pod.namefieldRef:fieldPath:metadata.nameThen, your running pod will see these environment variables populated:$cat/etc/otelrd/k8s.namespace.name
cool-app
$cat/etc/otelrd/k8s.pod.name
example-podWhen configuring your telemetry, you'll establish a "contract" by indicating the
directory into which you are mounting the Downward API metadata files (/etc/otelrdby default).  From there, the resource detector will look for files matching the names
ofstandard OpenTelemetry Kubernetes Resource Attributes.fromopentelemetry.sdk.resourcesimportget_aggregated_resourcesfromopentelemetry_resourcedetector_kubernetesimportKubernetesDownwardAPIEnvironmentResourceDetector...resource=get_aggregated_resources([KubernetesDownwardAPIVolumeResourceDetector(directory='/etc/otelrd'),SomeOtherResourceDetector()])...passthereturned`resource`toaTracerProvder,forexample...In this example, theResourcefor all traces would include the attributes:container.runtime = "kubernetes"
k8s.pod.uid = "...the UUID of the pod..."
container.id = "...the id of the container..."

k8s.namespace.name = "cool-app"
k8s.pod.name = "example-pod"