Kubernetes attributes processor v1: What it means for EDOT Collector

Elastic speaks OpenTelemetry natively. Send traces, logs, and metrics over OTLP straight into Elasticsearch, no proprietary agents required. See how it fits together, try it for free in the cloud, or run it locally.

The Kubernetes Semantic Conventions are stable, and the OpenTelemetry Kubernetes attributes processor reached v1.0.0 with them (upstream announcement). Seven attributes change name. Labels and annotations lose a letter, container.image.tag gains one, and everything else, including k8s.pod.name, k8s.namespace.name and k8s.deployment.name stays as it is.

Default EDOT Collector Helm values are fine. We ran telemetry through v1-only collectors on kind and GKE, then audited all 36 assets in the kubernetes_otel package: 12 dashboards, 18 alerting rule templates, 2 ML modules, 4 SLO templates. None of them reference a renamed field.

Custom assets are another matter. Anything querying k8s.pod.labels.<key> or container.image.tag quietly stops returning data after EDOT 9.6, with no error and no empty-state warning.

How the Kubernetes attributes processor reached v1.0.0

Reaching v1.0.0 for a collector component is not just a version bump. The stability criteria require complete documentation, community support coverage, internal observability, performance benchmarks, and a formal graduation process endorsed by maintainers and end users.

For the Kubernetes attributes processor, stabilizing the component also meant stabilizing what it emits. The K8s Semantic Conventions had to reach stable status first. That happened in June 2026 when Semantic Conventions v1.42.0 shipped.

Elastic engineers contributed to several of the graduation requirements:

• Driving the stabilization process (opentelemetry-collector-contrib#44483).
• The feature-gate mechanism for the semconv transition (opentelemetry-collector-contrib#44589).
• Kubernetes-specific benchmarks and load tests (opentelemetry-collector-contrib#46665, opentelemetry-collector-contrib#47798).
• The graduation proposal (opentelemetry-collector-contrib#49274) and the final promotion PR (opentelemetry-collector-contrib#49152).

The graduation process (opentelemetry-collector-contrib#49274) went through several weeks of review, endorsements from end users running it in production, and endorsements from vendor distributors. EDOT Collector was among those distributors.

What changed in v1.0.0

The v1 promotion aligns the processor's output with stable Semantic Conventions. The renamed attributes are limited to the label, annotation, and container image tag namespaces.

Attributes that did not change

Every core resource attribute keeps its v0 name. If your dashboards, alerts or ES|QL queries use any of these, they keep working after EDOT 9.6.

Feature gates that control v0 and v1 attribute emission

The processor ships two feature gates that remain in beta for the entire v1 release line:

Before EDOT 9.6, both gates are off: collectors emit only the old v0 names, and there is no change in behavior yet.

From EDOT 9.6, both gates are on by default: collectors emit only the new v1 names. This is the breaking change.

You can override the defaults using the feature-gates key in the EDOT kube-stack Helm values. The key applies per collector; you can set different values for cluster and daemon independently.

# Dual emission: emit both v0 and v1 names simultaneously (migration aid).
# Use this when upgrading to EDOT 9.6 if you have custom assets referencing v0 names.
collectors:
  daemon:
    args:
      feature-gates: -processor.k8sattributes.DontEmitV0K8sConventions,processor.k8sattributes.EmitV1K8sConventions

# Stay on v0 schema only (short-term, while planning migration).
collectors:
  daemon:
    args:
      feature-gates: -processor.k8sattributes.EmitV1K8sConventions,-processor.k8sattributes.DontEmitV0K8sConventions

Why the default EDOT Collector setup is unaffected

Every EDOT kube-stack Helm chart configuration ships a k8s_attributes processor block that extracts only core resource attributes. Here is the cluster collector configuration from deploy/helm/edot-collector/kube-stack/values.yaml:

k8s_attributes:
  passthrough: false
  pod_association:
    - sources:
        - from: resource_attribute
          name: k8s.pod.ip
    - sources:
        - from: resource_attribute
          name: k8s.pod.uid
    - sources:
        - from: resource_attribute
          name: k8s.pod.name
        - from: resource_attribute
          name: k8s.namespace.name
    - sources:
        - from: connection
  extract:
    metadata:
      - "k8s.namespace.name"
      - "k8s.deployment.name"
      - "k8s.replicaset.name"
      - "k8s.statefulset.name"
      - "k8s.daemonset.name"
      - "k8s.cronjob.name"
      - "k8s.job.name"
      - "k8s.node.name"
      - "k8s.pod.name"
      - "k8s.pod.ip"
      - "k8s.pod.uid"
      - "k8s.pod.start_time"
      # Service attributes per https://opentelemetry.io/docs/specs/semconv/non-normative/k8s-attributes/
      - "service.name"
      - "service.version"
      - "service.instance.id"

The DaemonSet collector adds container.id and a filter.node_from_env_var: OTEL_K8S_NODE_NAME to scope metadata lookups to the local node. Neither block extracts labels, annotations, or container.image.tag. There is nothing to rename.

The same pattern applies across the managed_otlp and managed_otlp/logs variants.

How we tested the v1 Kubernetes semantic conventions

Before adopting v1, we ran end-to-end verification against the actual v1 attribute schema using the feature gates to enforce v1-only output.

The test setup:

• A kind cluster connected to Elastic Cloud, installed using the Kubernetes OTel onboarding flow. The EDOT kube-stack Helm values were edited to:
  • Enable both feature gates (processor.k8sattributes.EmitV1K8sConventions and processor.k8sattributes.DontEmitV0K8sConventions).
  • Extract container.image.tags, a pod label (app), and a pod annotation, so the renamed attributes were explicitly exercised.
• The Elastic OTel Demo on Kubernetes (./demo.sh k8s --k8sattrs_v1_overrides), which routes both APM and infrastructure telemetry through the processor.
• The same setup repeated on a GKE cluster.

Validations and results:

• Default Kubernetes dashboards render correctly with v1 attributes.
• A sample nginx deployment shows container.image.tags, k8s.pod.label.app, and k8s.pod.annotation.<key> on indexed documents.
• Demo application services are enriched with v1 attributes, including traces.

In parallel, a full content audit covered the kubernetes_otel integration package: 12 dashboards, 18 alerting rule templates, 2 ML modules, and 4 SLO templates. None reference label or annotation fields. No package updates were needed.

Do you need to change anything before EDOT 9.6?

If your EDOT Collector configuration only uses the default EDOT Helm values, you are not affected. Elastic's built-in dashboards, alerting rule templates, ML modules, and SLO templates were verified against the v1 schema and require no changes.

If you have custom assets referencing the renamed fields (dashboards, alerts, SLOs, ES|QL queries, transforms, ingest pipelines, or runtime fields that use k8s.pod.labels.<key>, k8s.pod.annotations.<key>, k8s.node.labels.<key>, k8s.namespace.labels.<key>, or container.image.tag), you need to act before or alongside upgrading to EDOT 9.6.

Two things happen after the upgrade if you do not act:

• Assets referencing v0 names silently stop returning new data. There is no UI warning.
• Elasticsearch does not rename fields already indexed. Old data keeps v0 names; new data uses v1 names. A query on either name alone returns only part of the timeline.

Migrating custom assets to the v1 attribute names

Step 1: Assess exposure to the renamed fields

Before upgrading to EDOT 9.6, search your Kibana saved objects and alerting rules for the old field names:

k8s.pod.labels.    k8s.pod.annotations.
k8s.node.labels.   k8s.node.annotations.
k8s.namespace.labels.  k8s.namespace.annotations.
container.image.tag

Step 2: Enable dual emission at upgrade time

If you have affected custom assets, add the following to your collector configuration so both old and new names are written simultaneously while you migrate:

collectors:
  daemon:
    args:
      feature-gates: -processor.k8sattributes.DontEmitV0K8sConventions,processor.k8sattributes.EmitV1K8sConventions
  cluster:
    args:
      feature-gates: -processor.k8sattributes.DontEmitV0K8sConventions,processor.k8sattributes.EmitV1K8sConventions

Dual emission means new v1 names are written (so built-in Elastic assets work), and old v0 names are also written (so existing custom assets keep returning results while you update them). Treat this as a migration runway, not a permanent configuration.

Step 3: Update custom assets to v1 attribute names

Replace every reference to the old field names with the corresponding v1 names from the table above. Work through dashboards, alert conditions, transforms, and any saved searches that reference the affected namespaces.

Step 4: Remove the dual-emission flag

Once all custom assets are updated, remove the -processor.k8sattributes.DontEmitV0K8sConventions override to return to v1-only emission. This reduces indexing overhead and is the stable end state.

The full migration reference is in the processor's Semantic Conventions Compatibility section.

When the v1 Kubernetes attributes processor ships in EDOT

The v1.0.0 promotion merged into OpenTelemetry Collector Contrib main and ships with v0.161.0. EDOT Collector picks it up in the 9.6 release, where both feature gates flip to enabled by default. Check the EDOT Collector reference documentation for version-specific details.

The Kubernetes attributes processor is one of several components moving through the broader stabilization effort in the OpenTelemetry Collector project. More components will follow. If you are using components still at alpha or beta stability and want to see them reach v1.0.0 sooner, the best path is to provide feedback, usage reports, or direct contributions to the graduation process for those components.