可观测性与稳定性 / 系统课时
补齐 Kubernetes 资源与节点元数据
补齐 Kubernetes 资源与节点元数据
应用把 Trace、Metric、Log 发到 Collector 后,如果只有 service.name,很难回答“来自哪个 Namespace、Pod、Node 或 Workload”。本节用 k8sattributes 把遥测与 Kubernetes Pod 关联,再把同一组资源属性写入三类信号,建立稳定的归属维度。
学习目标
- 理解 Pod 关联与 Kubernetes 元数据补齐是两个连续步骤
- 配置
k8sattributes提取 Namespace、Pod、Node 与 Workload 属性 - 用 RBAC 与 debug exporter 验证三类信号获得一致资源属性
元数据补齐先从 Pod 关联开始
k8sattributes 不会仅凭一条 Span 的内容猜测它来自哪个 Pod。处理器先使用输入资源中的 k8s.pod.uid、k8s.pod.ip,或 OTLP 连接信息定位 Pod,再读取 Kubernetes API 中的元数据,最后把属性写入 Resource。
同一个 Pod 可以归属 Deployment、StatefulSet、DaemonSet、Job 等不同 Workload,因此不要人为制造一个模糊的 workload 字段。保留语义约定中的具体属性,例如 k8s.deployment.name 或 k8s.statefulset.name,后端才能准确筛选和聚合。

给 Collector 配置读取权限
处理器需要通过 Kubernetes API 查询对象。下面示例为运行在 observability Namespace 的 Collector ServiceAccount 提供读取 Pod、Namespace、Node 与常见 Workload 元数据所需的只读权限。
apiVersion: v1
kind: ServiceAccount
metadata:
name: otel-collector
namespace: observability
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: otel-collector-k8s-metadata
rules:
- apiGroups: [""]
resources: ["pods", "namespaces", "nodes"]
verbs: ["get", "list", "watch"]
- apiGroups: ["apps"]
resources: ["replicasets", "deployments", "statefulsets", "daemonsets"]
verbs: ["get", "list", "watch"]
- apiGroups: ["batch"]
resources: ["jobs", "cronjobs"]
verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: otel-collector-k8s-metadata
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: otel-collector-k8s-metadata
subjects:
- kind: ServiceAccount
name: otel-collector
namespace: observability应用这份清单后,可先验证关键权限:
kubectl auth can-i --as=system:serviceaccount:observability:otel-collector list pods --all-namespaces
kubectl auth can-i --as=system:serviceaccount:observability:otel-collector get nodes预期输出:
yes
yes如果这里返回 no,先修复 RBAC;否则 Processor 即使配置正确,也无法稳定补齐集群元数据。
把同一处理器接入三条 Pipeline
下面是一份可直接作为 Collector 配置使用的主示例。extract.metadata 明确选择需要的字段,pod_association 按稳定标识优先、连接信息兜底的顺序尝试关联;同一个 Processor 同时进入 traces、metrics、logs Pipeline,避免跨信号归属不一致。
receivers:
otlp:
protocols:
grpc:
endpoint: 0.0.0.0:4317
http:
endpoint: 0.0.0.0:4318
processors:
k8sattributes:
auth_type: serviceAccount
passthrough: false
pod_association:
- sources:
- from: resource_attribute
name: k8s.pod.uid
- sources:
- from: resource_attribute
name: k8s.pod.ip
- sources:
- from: connection
extract:
metadata:
- k8s.namespace.name
- k8s.pod.name
- k8s.pod.uid
- k8s.pod.start_time
- k8s.node.name
- k8s.replicaset.name
- k8s.deployment.name
- k8s.statefulset.name
- k8s.daemonset.name
- k8s.job.name
- k8s.cronjob.name
batch: {}
exporters:
debug:
verbosity: detailed
service:
pipelines:
traces:
receivers: [otlp]
processors: [k8sattributes, batch]
exporters: [debug]
metrics:
receivers: [otlp]
processors: [k8sattributes, batch]
exporters: [debug]
logs:
receivers: [otlp]
processors: [k8sattributes, batch]
exporters: [debug]这份配置生效后,匹配成功的遥测 Resource 会获得对应 Kubernetes 属性。某个 Pod 不属于 Deployment 时,不应强行出现 k8s.deployment.name;例如 StatefulSet Pod 应以 k8s.statefulset.name 表达所属 Workload。
验证资源属性而不是只看数据有没有到
让应用向该 Collector 发送一批遥测后,检查 debug exporter。下面命令只筛选本节关注的 Kubernetes Resource 属性;实际 Collector Pod 名称会不同。
kubectl -n observability logs deploy/otel-collector --since=2m | grep -E 'k8s\.(namespace|pod|node|deployment|statefulset|daemonset|job|cronjob)'预期输出会包含与实际 Pod 对应的若干属性,例如:
k8s.namespace.name: Str(app)
k8s.pod.name: Str(checkout-<ID>)
k8s.pod.uid: Str(<ID>)
k8s.node.name: Str(<NODE>)
k8s.deployment.name: Str(checkout)<ID> 与 <NODE> 会随集群实际对象变化。若数据已到 Collector 却没有这些字段,按“发送端是否提供可关联标识 → pod_association 是否命中 → RBAC 是否允许查询 → Processor 是否进入对应 Pipeline”的顺序检查,比直接修改后端查询条件更有效。
跨信号关联的关键不是给每条遥测重复塞标签,而是让 Trace、Metric、Log 共享一致的 Resource 身份。这样从某个错误 Span 跳到同 Pod 日志,或从节点指标回查关联 Workload 时,查询条件才能稳定复用。