可观测性与稳定性 / 系统课时

补齐 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,后端才能准确筛选和聚合。

Kubernetes 元数据从 Pod 关联到三类遥测信号的补齐链路

给 Collector 配置读取权限

处理器需要通过 Kubernetes API 查询对象。下面示例为运行在 observability Namespace 的 Collector ServiceAccount 提供读取 Pod、Namespace、Node 与常见 Workload 元数据所需的只读权限。

yaml
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

应用这份清单后,可先验证关键权限:

bash
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

预期输出:

text
yes
yes

如果这里返回 no,先修复 RBAC;否则 Processor 即使配置正确,也无法稳定补齐集群元数据。

把同一处理器接入三条 Pipeline

下面是一份可直接作为 Collector 配置使用的主示例。extract.metadata 明确选择需要的字段,pod_association 按稳定标识优先、连接信息兜底的顺序尝试关联;同一个 Processor 同时进入 traces、metrics、logs Pipeline,避免跨信号归属不一致。

yaml
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 名称会不同。

bash
kubectl -n observability logs deploy/otel-collector --since=2m | grep -E 'k8s\.(namespace|pod|node|deployment|statefulset|daemonset|job|cronjob)'

预期输出会包含与实际 Pod 对应的若干属性,例如:

text
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 时,查询条件才能稳定复用。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

补齐 Kubernetes 资源与节点元数据

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通