Registry /
observability / opentelemetry-resourcedetector-kubernetes
Install & Compatibility
Where this runs
tested against v0.3.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.188s · 21.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.0s · import 0.176s · 22MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
KubernetesResourceDetector
✓ from opentelemetry_resourcedetector_kubernetes import KubernetesResourceDetector
KubernetesDownwardAPIEnvironmentResourceDetector
✓ from opentelemetry_resourcedetector_kubernetes import KubernetesDownwardAPIEnvironmentResourceDetector
KubernetesDownwardAPIVolumeResourceDetector
✓ from opentelemetry_resourcedetector_kubernetes import KubernetesDownwardAPIVolumeResourceDetector
get_aggregated_resources
✓ from opentelemetry.sdk.resources import get_aggregated_resources
Resource
✓ from opentelemetry.sdk.resources import Resource
This quickstart demonstrates how to instantiate and use the `KubernetesResourceDetector` to gather Kubernetes-specific resource attributes. The detected attributes are then printed. In a full OpenTelemetry setup, this `resource` object would be passed to a `TracerProvider`, `MeterProvider`, or `LoggerProvider` to enrich all emitted telemetry.
import os
from opentelemetry.sdk.resources import get_aggregated_resources, Resource
from opentelemetry_resourcedetector_kubernetes import KubernetesResourceDetector
# Create a base resource (optional, but good practice for service name)
base_resource = Resource.create({
"service.name": os.environ.get("OTEL_SERVICE_NAME", "my-kubernetes-app"),
"service.version": "0.1.0"
})
# Aggregate resources from the Kubernetes detector and other potential detectors
# In a real Kubernetes environment, this will detect k8s.pod.uid, container.id, etc.
resource = get_aggregated_resources([
KubernetesResourceDetector(),
# Add other detectors here if needed, e.g., HostDetector(), OSDetector()
], initial_resource=base_resource)
print("Detected Resource Attributes:")
for key, value in resource.attributes.items():
print(f" {key}: {value}")
# The 'resource' object is then passed to a TracerProvider, MeterProvider, or LoggerProvider
# Example (conceptual, requires OpenTelemetry SDK tracing/metrics packages):
# from opentelemetry.sdk.trace import TracerProvider
# tracer_provider = TracerProvider(resource=resource)
Debug
Known issues
gotchaThe `KubernetesDownwardAPIEnvironmentResourceDetector` and `KubernetesDownwardAPIVolumeResourceDetector` require explicit configuration in your Kubernetes manifests (e.g., defining environment variables or volume mounts) to populate additional attributes. Without this, they will only provide basic pod UID and container ID information.fixEnsure your Kubernetes pod manifests are configured with the necessary Downward API environment variables or volume mounts as per OpenTelemetry documentation for the attributes you wish to collect.
affects: All versions
gotchaThe Downward API detectors are designed specifically for `k8s.*` and `container.*` OpenTelemetry attributes and are not a general-purpose mechanism for collecting arbitrary metadata.fixUse other resource detectors or custom attributes for non-Kubernetes or non-container related metadata.
affects: All versions
gotchaResource detection, particularly when aggregating multiple detectors or interacting with external services (like cloud metadata), can introduce startup latency.fixIn production environments, consider explicitly enabling only the necessary detectors using the `OTEL_EXPERIMENTAL_RESOURCE_DETECTORS` environment variable to minimize overhead. For example, `export OTEL_EXPERIMENTAL_RESOURCE_DETECTORS="kubernetes,env,host"`.
affects: All versions
deprecatedOpenTelemetry Kubernetes semantic conventions are actively evolving and have recently been promoted to release candidate status. While this library aims to adhere to these conventions, future updates could potentially introduce changes to attribute names or structures, which might impact existing monitoring dashboards or correlation logic.fixStay informed about OpenTelemetry semantic convention updates and be prepared to adapt your telemetry consumption or dashboard configurations if attribute names change. Regularly review the `opentelemetry-semantic-conventions` repository.
affects: Potentially future versions (from 0.3.0 onwards as conventions stabilize)
Errors
Common errors & fixes
Failed to detect Kubernetes metadata: unable to read /var/run/secrets/kubernetes.io/serviceaccount/namespace
The application running in the Kubernetes pod does not have the necessary permissions to read the service account token or the token files are not correctly mounted, preventing the detector from accessing Kubernetes metadata.
fixEnsure your Kubernetes deployment includes a service account with `read` permissions for pod metadata, and that the service account token is correctly mounted to `/var/run/secrets/kubernetes.io/serviceaccount/`.
ModuleNotFoundError: No module named 'opentelemetry_resourcedetector_kubernetes'
The `opentelemetry-resourcedetector-kubernetes` package has not been installed in your Python environment.
fixInstall the package using pip: `pip install opentelemetry-resourcedetector-kubernetes`.
from opentelemetry.sdk.resources import KubernetesResourceDetector
The `KubernetesResourceDetector` class is part of the specific `opentelemetry_resourcedetector_kubernetes` package, not the generic `opentelemetry.sdk.resources` module.
fixUse the correct import statement: `from opentelemetry_resourcedetector_kubernetes import KubernetesResourceDetector`.
Error: Failed to detect Kubernetes metadata
This general error indicates that the resource detector could not retrieve Kubernetes metadata, often due to insufficient Kubernetes RBAC permissions for the service account used by the application/collector, or network connectivity issues to the Kubernetes API server.
fixGrant the service account used by your application or OpenTelemetry Collector appropriate RBAC permissions (e.g., `get` for pods, namespaces, and nodes) and verify network connectivity to the Kubernetes API server endpoint within your cluster.
Upgrade
Version history
0.3.0latest on PyPI · released Sep 18, 2022
Audit
Dependencies
opentelemetry-sdkrequiredRequired for core OpenTelemetry SDK functionalities like `get_aggregated_resources` and `Resource`.