Kubernetes attributes processor v1：它对 EDOT Collector 意味着什么

Elasticsearch2026-09-30 10:24

作者：来自 Elastic Christos Markou

高效存储高基数指标，使用 time series data streams，并继续使用你的 Prometheus 和 PromQL 工作流。

深入了解基础设施和指标监控。立即开始免费云试用，或者现在就在你的本地机器上试用 Elastic。

Kubernetes Semantic Conventions 已经稳定，OpenTelemetry Kubernetes attributes processor 也随之达到 v1.0.0（上游公告）。有 7 个 attributes 更改了名称。Labels 和 annotations 少了一个字母，container.image.tag 多了一个字母，而其他所有内容，包括 k8s.pod.name、k8s.namespace.name 和 k8s.deployment.name，都保持不变。

默认的 EDOT Collector Helm values 没有问题。我们在 kind 和 GKE 上使用仅支持 v1 的 collectors 运行了 telemetry，然后审查了 kubernetes_otel package 中的全部 36 个 assets：12 个 dashboards、18 个 alerting rule templates、2 个 ML modules 、4 个 SLO templates。其中没有任何一个引用了重命名后的 field。

自定义 assets 则是另一回事。任何查询 k8s.pod.labels.<key> 或 container.image.tag 的内容，在 EDOT 9.6 之后都会悄悄停止返回数据，不会报错，也不会显示空状态警告。

Kubernetes attributes processor 如何达到 v1.0.0

Collector component 达到 v1.0.0 并不只是版本号的提升。稳定性标准要求完整的文档、社区支持覆盖、内部可观测性、性能基准测试，以及由维护者和最终用户认可的正式毕业流程。

对于 Kubernetes attributes processor 来说，让 component 稳定下来也意味着让它输出的内容稳定下来。K8s Semantic Conventions 必须首先达到稳定状态。这发生在 2026 年 6 月，当时Semantic Conventions v1.42.0 发布。

Elastic 工程师参与了多项毕业要求：

毕业流程（opentelemetry-collector-contrib#49274）经历了数周的审查、在生产环境中运行该 component 的最终用户的认可，以及 vendor distributors 的认可。EDOT Collector 就是这些 distributors 之一。

v1.0.0 中发生了什么变化

v1 晋级使 processor 的输出与稳定的 Semantic Conventions 保持一致。重命名的 attributes 仅限于 label、annotation 和 container image tag 这些 namespace。

v0 attribute name v1 attribute name
container.image.tag container.image.tags
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>

没有发生变化的 Attributes

每个核心 resource attribute 都保留其 v0 名称。如果你的 dashboards、alerts 或 ES|QL 查询使用了以下任何 attribute，那么在 EDOT 9.6 之后它们仍然可以正常工作。

Category Attributes
Pod identity k8s.pod.name、k8s.pod.uid、k8s.pod.ip、k8s.pod.start_time
Workload k8s.deployment.name、k8s.replicaset.name、k8s.statefulset.name、k8s.daemonset.name、k8s.job.name、k8s.cronjob.name
Cluster placement k8s.namespace.name、k8s.node.name
Container container.id
Service service.name、service.version、service.instance.id

控制 v0 和 v1 attribute 发出的 Feature gates

该 processor 提供两个 feature gates，在整个 v1 发布系列中都保持为 beta：

Feature gate EDOT 9.6 之前 从 EDOT 9.6 开始 启用后的效果
processor.k8sattributes.EmitV1K8sConventions disabled enabled 发出 v1 attribute 名称
processor.k8sattributes.DontEmitV0K8sConventions disabled enabled 停止发出 v0 attribute 名称

在 EDOT 9.6 之前，两个 gates 都处于关闭状态：collectors 只发出旧的 v0 名称，因此行为尚未发生变化。

从 EDOT 9.6 开始，两个 gates 默认都处于开启状态：collectors 只发出新的 v1 名称。这就是 breaking change。

你可以使用 EDOT kube-stack Helm values 中的 feature-gates key 覆盖默认设置。该 key 针对每个 collector 单独生效；你可以分别为 cluster 和 daemon 设置不同的值。

yaml 复制代码 
`

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

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

`AI写代码![](https://csdnimg.cn/release/blogv2/dist/pc/img/runCode/icon-arrowwhite.png)

为什么默认的 EDOT Collector 设置不受影响

每个 EDOT kube-stack Helm chart 配置都包含一个 k8s_attributes processor block，它只提取核心 resource attributes。以下是deploy/helm/edot-collector/kube-stack/values.yaml中的 cluster collector 配置：

csharp 复制代码 
`

1.  k8s_attributes:
2.    passthrough: false
3.    pod_association:
4.      - sources:
5.          - from: resource_attribute
6.            name: k8s.pod.ip
7.      - sources:
8.          - from: resource_attribute
9.            name: k8s.pod.uid
10.      - sources:
11.          - from: resource_attribute
12.            name: k8s.pod.name
13.          - from: resource_attribute
14.            name: k8s.namespace.name
15.      - sources:
16.          - from: connection
17.    extract:
18.      metadata:
19.        - "k8s.namespace.name"
20.        - "k8s.deployment.name"
21.        - "k8s.replicaset.name"
22.        - "k8s.statefulset.name"
23.        - "k8s.daemonset.name"
24.        - "k8s.cronjob.name"
25.        - "k8s.job.name"
26.        - "k8s.node.name"
27.        - "k8s.pod.name"
28.        - "k8s.pod.ip"
29.        - "k8s.pod.uid"
30.        - "k8s.pod.start_time"
31.        # Service attributes per https://opentelemetry.io/docs/specs/semconv/non-normative/k8s-attributes/
32.        - "service.name"
33.        - "service.version"
34.        - "service.instance.id"

`AI写代码![](https://csdnimg.cn/release/blogv2/dist/pc/img/runCode/icon-arrowwhite.png)

DaemonSet collector 会额外添加 container.id，以及 filter.node_from_env_var: OTEL_K8S_NODE_NAME，将 metadata 查找范围限定在本地节点。两个 block 都不会提取 labels、annotations 或 container.image.tag。因此没有任何内容需要重命名。

同样的模式也适用于 managed_otlp 和 managed_otlp/logs 变体。

我们如何测试 v1 Kubernetes semantic conventions

在采用 v1 之前，我们使用 feature gates 强制只输出 v1，然后针对实际的 v1 attribute schema 进行了端到端验证。

测试设置：

  • 一个连接到 Elastic Cloud 的 kind 集群，使用 Kubernetes OTel onboarding 流程安装。我们编辑了 EDOT kube-stack Helm values，以：

    • 启用两个 feature gates（processor.k8sattributes.EmitV1K8sConventions 和 processor.k8sattributes.DontEmitV0K8sConventions）。

    • 提取 container.image.tags、一个 pod label（app）和一个 pod annotation，以明确验证这些重命名后的 attributes。

  • Kubernetes 上的 Elastic OTel Demo（./demo.sh k8s --k8sattrs_v1_overrides），通过 processor 同时路由 APM 和基础设施 telemetry。

  • 在 GKE 集群上重复了相同的设置。

验证和结果：

  • 默认的 Kubernetes dashboards 使用 v1 attributes 正常渲染。

  • 一个示例 nginx deployment 在索引后的 documents 中显示 container.image.tags、k8s.pod.label.app 和 k8s.pod.annotation.<key>。

  • Demo 应用服务都使用 v1 attributes 进行了 enrichment，包括 traces。

与此同时，我们对 kubernetes_otel integration package 进行了完整的内容审计：12 个 dashboards、18 个 alerting rule templates、2 个 ML modules 和 4 个 SLO templates。没有任何一个引用 label 或 annotation fields。因此不需要更新 package。

在 EDOT 9.6 之前，你需要进行任何更改吗？

如果你的 EDOT Collector 配置只使用默认的 EDOT Helm values，那么你不受影响。Elastic 内置的 dashboards、alerting rule templates、ML modules 和 SLO templates 都已经针对 v1 schema 完成验证，无需进行任何更改。

如果你有引用重命名字段的自定义 assets （dashboards、alerts、SLOs、ES|QL queries、transforms、ingest pipelines 或 runtime fields，其中使用了 k8s.pod.labels.<key>、k8s.pod.annotations.<key>、k8s.node.labels.<key>、k8s.namespace.labels.<key> 或 container.image.tag），那么你需要在升级到 EDOT 9.6 之前或升级过程中采取行动。

如果你不采取行动，升级后会发生两件事：

  • 引用 v0 名称的 assets 会悄悄停止返回新数据。UI 不会显示警告。

  • Elasticsearch 不会重命名已经建立索引的 fields。旧数据继续使用 v0 名称；新数据使用 v1 名称。单独查询其中任意一个名称，只会返回部分时间线的数据。

将自定义 assets 迁移到 v1 attribute 名称

步骤 1：评估对重命名字段的影响

在升级到 EDOT 9.6 之前，在 Kibana saved objects 和 alerting rules 中搜索旧的 field names：

markdown 复制代码 
`

1.  k8s.pod.labels.    k8s.pod.annotations.
2.  k8s.node.labels.   k8s.node.annotations.
3.  k8s.namespace.labels.  k8s.namespace.annotations.
4.  container.image.tag

`AI写代码

步骤 2：在升级时启用双重发出

如果你有受影响的自定义 assets，请将以下内容添加到 collector 配置中，以便在迁移期间同时写入旧名称和新名称：

markdown 复制代码 
`

1.  collectors:
2.    daemon:
3.      args:
4.        feature-gates: -processor.k8sattributes.DontEmitV0K8sConventions,processor.k8sattributes.EmitV1K8sConventions
5.    cluster:
6.      args:
7.        feature-gates: -processor.k8sattributes.DontEmitV0K8sConventions,processor.k8sattributes.EmitV1K8sConventions

`AI写代码

双重发出意味着会写入新的 v1 名称（因此 Elastic 内置 assets 可以正常工作），同时也会写入旧的 v0 名称（因此现有自定义 assets 在你更新它们的过程中仍然可以返回结果）。将其视为迁移过渡方案，而不是永久配置。

步骤 3：将自定义 assets 更新为 v1 attribute 名称

将所有对旧 field names 的引用替换为上表中对应的 v1 名称。逐一检查 dashboards、alert conditions、transforms，以及任何引用受影响 namespaces 的 saved searches。

步骤 4：移除双重发出标志

所有自定义 assets 更新完成后，移除 -processor.k8sattributes.DontEmitV0K8sConventions override，恢复为仅发出 v1。这样可以减少 indexing 开销，也是稳定的最终状态。

完整的迁移参考位于 processor 的Semantic Conventions Compatibility 部分。

v1 Kubernetes attributes processor 何时随 EDOT 发布

v1.0.0 晋级已合并到 OpenTelemetry Collector Contrib main，并随 v0.161.0 发布。EDOT Collector 会在 9.6 版本 中引入它，届时两个 feature gates 都会默认启用。有关特定版本的详细信息，请查看 EDOT Collector reference documentation。

Kubernetes attributes processor 是 OpenTelemetry Collector 项目中正在进行的更广泛稳定化工作的多个 components 之一。还会有更多 components 加入。如果你正在使用仍处于 alpha 或 beta 稳定级别的 components，并希望看到它们更快达到 v1.0.0，最有效的方式是为这些 components 的毕业流程提供反馈、使用报告或直接贡献。

原文：Kubernetes attributes processor v1: What it means for EDOT Collector | Elastic Observability Labs

相关推荐
Elasticsearch2 小时前
Elasticsearch Serverless 如何通过 hollow shards 将索引节点关闭次数降低 30%
elasticsearch
SelectDB技术团队3 小时前
Agent Trace 数据底座建设：宽表建模、全文检索与成本聚合的配置与验证步骤
大数据·python·clickhouse·elk·elasticsearch·全文检索·复杂查询
Zhu7583 小时前
快速测试-ZLMediaKit
大数据·elasticsearch·搜索引擎
Elastic 中国社区官方博客3 小时前
使用 NVIDIA cuVS 在 Elasticsearch 中实现 GPU 加速的向量索引：在 10 分钟内处理 1.38 亿个向量
大数据·数据库·elasticsearch·搜索引擎·全文检索·安全威胁分析
liuhl091016 小时前
【无标题】
大数据·elasticsearch·搜索引擎
xbgRS17 小时前
Elasticsearch的查询
elasticsearch
Elasticsearch21 小时前
使用 Lucene 搜索你的 Bean —— Highlighting
elasticsearch
Elasticsearch21 小时前
使用 Lucene 搜索你的 Bean —— Elasticsearch
elasticsearch
Elasticsearch1 天前
最好的 LLM 只有 59% 的时间能写出正确的 Elasticsearch ES|QL。以下是另外 41% 出错的原因
elasticsearch
热门推荐
01国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）02历年考研数学一、数学二、数学三真题试卷及答案PDF03Telegram APK 下载安装完整指南 — 2026年最新04GitHub 镜像站点05蜘蛛磁力 搜索引擎大全，如何使用蜘蛛磁力查找磁力链接062026 爱知・名古屋亚运会怎么看？直播平台+赛程安排分享07微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新08jev-ultrafast 深度解析：7 秒订机票的浏览器 Agent 是如何炼成的09给AI一张“业务概念地图“：本体如何从哲学走向企业智能102026 年 9 月国内外主流大模型横向硬核评测：价格、算力、业务场景全维度对比，GPT‑6 Astra横空出世