OpenTelemetry’s Kubernetes attributes processor reached v1.0.0 on September 16, 2026. The milestone makes the processor’s API stable for redistribution without API breakage, but it does not make every existing telemetry pipeline automatically compatible: the stable Kubernetes semantic conventions use renamed attributes that can break dashboards, alerts, queries, and processing rules.
What does v1.0.0 stability mean?
OpenTelemetry says the processor’s promotion reflects its criteria for testing, benchmarking, documentation, and telemetry stability. It also permits redistribution of the component as a Go library or inclusion in binaries without API breakage. That is a stability commitment for the component, not a guarantee that every backend or existing Collector configuration will interpret emitted attributes the same way. The OpenTelemetry announcement by Christos Markou and Pablo Baeyens explicitly warns of breakage for existing users because the semantic-convention names changed.
As an Amazon Associate I earn from qualifying purchases.
Why did the conventions have to mature first?
A processor can be stable as software while still emitting telemetry whose names are subject to change. For Kubernetes attributes, the Collector SIG’s “Stable by Default” effort therefore depended on stabilizing the semantic conventions the processor uses. Focused work by the Kubernetes Semantic Conventions SIG began in November 2025; the conventions reached release-candidate status in March 2026, then became stable in Semantic Conventions v1.42.0 in June 2026. The processor’s v1.0.0 promotion followed in September.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitchesThis sequence matters because attribute names are part of the contract between telemetry producers and consumers. Stable conventions make that contract more durable, while the component’s migration controls give existing users a way to handle the transition.
#1 Best Overall
Which Kubernetes attributes were renamed?
The most visible changes for users of this processor are the label and annotation namespaces: plural labels and annotations become singular label and annotation.
| Legacy attribute pattern | Stable attribute pattern |
|---|---|
k8s.pod.labels.<key> |
k8s.pod.label.<key> |
k8s.pod.annotations.<key> |
k8s.pod.annotation.<key> |
k8s.node.labels.<key> |
k8s.node.label.<key> |
k8s.node.annotations.<key> |
k8s.node.annotation.<key> |
k8s.namespace.labels.<key> |
k8s.namespace.label.<key> |
k8s.namespace.annotations.<key> |
k8s.namespace.annotation.<key> |
These are attribute-key changes, not changes to the Kubernetes label or annotation values themselves. Any consumer that selects a key by its old full name may need an update.
How can you emit legacy and stable attributes?
The upstream k8sattributes processor README documents two processor-specific feature gates:
processor.k8sattributes.EmitV1K8sConventionsenables stable semantic-convention attributes.processor.k8sattributes.DontEmitV0K8sConventionsdisables legacy semantic-convention attributes.
In the current upstream documentation, both gates are enabled by default and remain beta during the v1.x period. Together, they support emitting stable attributes, legacy attributes, or both, and allow users to switch back to the old unstable schema if necessary. Defaults and availability may differ in older Collector versions or vendor distributions, so verify the documentation for the exact build you run before relying on them.
Do not assume the general OTEL_SEMCONV_STABILITY_OPT_IN environment variable controls this processor. The official Kubernetes semantic-convention migration guide says the processor uses its own gates. The guide also describes a separate staged opt-in for existing Kubernetes instrumentations: k8s emits stable conventions only, while k8s/dup emits both sets; without an opt-in, instrumentation continues with its previous conventions. That instrumentation guidance is distinct from the processor’s controls.
What should you check before upgrading?
Attribute renames matter wherever a pipeline or observability tool refers to an exact key. Use a test environment to inspect emitted resource attributes and verify that consumers can read the schema mode you plan to use.
- Confirm the installed Collector build. Record its version and distribution, then check that build’s k8sattributes documentation for gate availability and defaults.
- Find references to legacy keys. Review dashboards, saved queries, alert expressions, processors, exporters, sampling rules, routing logic, and ingestion mappings for the plural label or annotation names.
- Choose a transition mode. Use the processor’s documented gates for the legacy, stable, or dual-emission behavior available in your build. Test the result rather than inferring it from defaults documented for upstream
main. - Update and validate consumers. Change references to the stable names where appropriate, then check that dashboards, alerts, and downstream processing still behave as intended against emitted telemetry.
- Roll out deliberately. Move production workloads only after the Collector configuration and its consumers have been checked together. If reverting to legacy attributes, confirm that the build’s documented gates support that mode.
The migration guide’s advice to maintain existing major versions for at least six months after starting dual emission applies to existing Kubernetes instrumentations; it is not a processor-specific compatibility guarantee.
Recommended Free Tools
Why can a schema change break observability?
OpenTelemetry’s Telemetry Schemas specification explains that telemetry sources and consumers can make assumptions about data shape. A backend expecting an old attribute name may stop matching it when the producer changes that name. Different sources in one environment can also evolve at different rates, so a deployment may temporarily contain more than one schema version.
Best Value
In practical terms, the schema is the naming and structure agreement between what a processor emits and what a dashboard, alert, or backend reads. Stable conventions reduce future naming churn; they do not remove the need to migrate consumers that depend on the old keys.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
