OpenTelemetry Helm chart 将 Collector 部署为 DaemonSet、Deployment 或 StatefulSet,并生成合理的默认配置。你完全通过 values.yaml 文件来定制它,这使它天然适合 GitOps。本指南安装它,使用 preset 处理常见需求,并展示如何覆盖 Collector 配置。

安装

helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts
helm repo update

helm install my-opentelemetry-collector open-telemetry/opentelemetry-collector \
  --namespace observability --create-namespace \
  --set image.repository="otel/opentelemetry-collector-k8s" \
  --set mode=daemonset

必须设置两项:

• mode 必须是 daemonset、deployment 或 statefulset。没有默认值。
• image.repository 选择发行版。Kubernetes 发行版(otel/opentelemetry-collector-k8s)包含 preset 所需的组件。如果你需要它之外的组件,请使用 contrib 镜像。

用 --version 固定 chart,用 image.tag 固定镜像,并把一切保存在 values 文件中而不是 --set 参数里,这样它可被审查:

# values.yaml
mode: daemonset
image:
  repository: otel/opentelemetry-collector-k8s
  tag: "0.163.0"   # pin to a version you have tested

helm install otel-agent open-telemetry/opentelemetry-collector \
  -n observability --create-namespace -f values.yaml --version <chart-version>

哪种模式适合哪种工作

• daemonset:每个节点一个 pod。用于日志收集、kubelet 指标和主机指标,因为这些只存在于本地节点上。
• deployment:可扩展的服务。用于应用向其发送数据的 gateway。
• statefulset:当你需要稳定的存储或身份时,例如持久队列或 Target Allocator 模式。
• 对于应当每个集群只收集一次的数据(集群指标、Kubernetes 事件),请使用单副本的 Deployment 或 StatefulSet,否则你会得到重复数据。

Preset

Preset 会开启常见的配置,包括它们所需的 receiver、processor、RBAC 和卷挂载:

# Agent: logs, host and kubelet metrics, and pod metadata on every node
mode: daemonset
presets:
  logsCollection:
    enabled: true
  hostMetrics:
    enabled: true
  kubeletMetrics:
    enabled: true
  kubernetesAttributes:
    enabled: true

# Cluster-wide metrics and events, once
mode: deployment
replicaCount: 1
presets:
  clusterMetrics:
    enabled: true
  kubernetesEvents:
    enabled: true

Preset 需要包含其组件的 Collector 镜像,所以请使用 Kubernetes 或 contrib 镜像。把它们当作起点:对于不寻常的需求,请自己配置组件及其 RBAC 和卷。所有选项都列在 chart 的 values.yaml 中。

覆盖 Collector 配置

config 键会合并到 chart 的默认 Collector 配置之上。添加或更改你需要的内容:

mode: deployment
replicaCount: 2

config:
  processors:
    memory_limiter:
      check_interval: 1s
      limit_percentage: 80
      spike_limit_percentage: 20
  exporters:
    otlp/tempo:
      endpoint: tempo.observability.svc.cluster.local:4317
      tls:
        insecure: true
  service:
    pipelines:
      traces:
        receivers: [otlp]
        processors: [memory_limiter, batch]
        exporters: [otlp/tempo]

容易绊倒人的规则:

• 默认的 exporter 是 debug。 如上所示,在你使用的每条管线中替换它。
• 将默认组件设为 null 会移除它: config.receivers.zipkin: null。
• 列表是替换,而不是合并。 当你更改某条管线时,请列出它的所有组件,包括你想保留的默认组件。
• 禁用未使用的端口,保持 Service 整洁,例如 ports.jaeger-compact.enabled: false。
• 日志与 debug exporter: 如果你启用 logsCollection 并设置 includeCollectorLogs: true,同时在日志管线上保留 debug exporter,Collector 可能会读取它自己的日志并反馈回去,造成日志爆炸。请先切换到真实的 exporter。

一个精简的、仅 OTLP 的 gateway:

config:
  receivers:
    jaeger: null
    prometheus: null
    zipkin: null
  service:
    pipelines:
      traces:
        receivers: [otlp]
        exporters: [otlp/tempo]
      metrics: null
      logs: null
ports:
  jaeger-compact:
    enabled: false
  jaeger-thrift:
    enabled: false
  jaeger-grpc:
    enabled: false
  zipkin:
    enabled: false

Secret 与环境变量

用环境变量注入凭据,并在 Collector 配置中用 ${env:NAME} 引用它们:

extraEnvs:
  - name: BACKEND_TOKEN
    valueFrom:
      secretKeyRef:
        name: otel-backend
        key: token

config:
  exporters:
    otlphttp/backend:
      endpoint: https://otlp.backend.example.com
      headers:
        authorization: Bearer ${env:BACKEND_TOKEN}

不要以明文形式把 Secret 放进 Git:用 SOPS 加密它,或者从 secret 管理器同步它。

使用 Flux 部署

如果你使用 Flux,chart 就是一个 HelmRelease:

apiVersion: source.toolkit.fluxcd.io/v1
kind: HelmRepository
metadata:
  name: open-telemetry
  namespace: flux-system
spec:
  interval: 1h
  url: https://open-telemetry.github.io/opentelemetry-helm-charts
---
apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: otel-agent
  namespace: observability
spec:
  interval: 10m
  chart:
    spec:
      chart: opentelemetry-collector
      version: "<chart-version>"
      sourceRef:
        kind: HelmRepository
        name: open-telemetry
        namespace: flux-system
  values:
    mode: daemonset
    image:
      repository: otel/opentelemetry-collector-k8s
    presets:
      kubernetesAttributes:
        enabled: true

Git 中 values 的变更随后通过 Flux 推出。Flux 系列涵盖了 HelmRelease 的选项,如 remediation 和漂移检测。

验证

kubectl get pods -n observability
kubectl logs -n observability daemonset/otel-agent-opentelemetry-collector | tail -n 20
kubectl port-forward -n observability svc/otel-agent-opentelemetry-collector 13133:13133 &
curl -s http://localhost:13133

Pod 和 Service 的名称遵循你的 release 名称。如果某个 pod 崩溃循环,日志通常会指出未知的组件或无效的键。在这种情况下,镜像中不包含你的配置所引用的某个组件,或者某个值缩进在了错误的键下面。