Das OpenTelemetry-Helm-Chart deployt den Collector als DaemonSet, Deployment oder StatefulSet und erzeugt eine sinnvolle Standardkonfiguration. Du passt sie vollständig über eine values.yaml-Datei an, was sie zu einer natürlichen Wahl für GitOps macht. Diese Anleitung installiert es, nutzt Presets für gängige Anforderungen und zeigt, wie du die Collector-Konfiguration überschreibst.

Installieren

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

Zwei Einstellungen sind erforderlich:

• mode muss daemonset, deployment oder statefulset sein. Es gibt keinen Standard.
• image.repository wählt die Distribution. Die Kubernetes-Distribution (otel/opentelemetry-collector-k8s) enthält die Komponenten, die die Presets brauchen. Nutze das Contrib-Image, wenn du Komponenten außerhalb davon brauchst.

Pinne das Chart mit --version und das Image mit image.tag und halte alles in einer Values-Datei statt in --set-Flags, damit es prüfbar ist:

# values.yaml
mode: daemonset
image:
  repository: otel/opentelemetry-collector-k8s
  tag: "0.163.0"   # pinne auf eine Version, die du getestet hast

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

Welcher Modus für welche Aufgabe

• daemonset: ein Pod pro Knoten. Nutze ihn für Log-Sammlung, kubelet-Metriken und Host-Metriken, da diese nur auf dem lokalen Knoten existieren.
• deployment: ein skalierbarer Service. Nutze ihn für ein Gateway, an das Anwendungen senden.
• statefulset: wenn du stabilen Speicher oder stabile Identität brauchst, zum Beispiel eine persistente Queue oder das Target-Allocator-Muster.
• Für Daten, die einmal pro Cluster gesammelt werden sollen (Cluster-Metriken, Kubernetes-Events), nutze ein Deployment oder StatefulSet mit einem einzelnen Replikat, sonst bekommst du Duplikate.

Presets

Presets schalten gängige Konfigurationen ein, einschließlich der Receiver, Prozessoren, des RBAC und der Volume-Mounts, die sie brauchen:

# Agent: Logs, Host- und kubelet-Metriken sowie Pod-Metadaten auf jedem Knoten
mode: daemonset
presets:
  logsCollection:
    enabled: true
  hostMetrics:
    enabled: true
  kubeletMetrics:
    enabled: true
  kubernetesAttributes:
    enabled: true

# Clusterweite Metriken und Events, einmal
mode: deployment
replicaCount: 1
presets:
  clusterMetrics:
    enabled: true
  kubernetesEvents:
    enabled: true

Presets brauchen ein Collector-Image, das ihre Komponenten enthält, nutze also das Kubernetes- oder Contrib-Image. Behandle sie als Ausgangspunkt: Für ungewöhnliche Anforderungen konfiguriere die Komponenten und ihr RBAC und ihre Volumes selbst. Alle Optionen sind in der values.yaml des Charts aufgelistet.

Die Collector-Konfiguration überschreiben

Der Schlüssel config wird über die Standard-Collector-Konfiguration des Charts gemergt. Füge hinzu oder ändere, was du brauchst:

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]

Regeln, über die man stolpert:

• Der Standard-Exporter ist debug. Ersetze ihn wie oben in jeder Pipeline, die du nutzt.
• Eine Standardkomponente auf null zu setzen entfernt sie: config.receivers.zipkin: null.
• Listen ersetzen, sie werden nicht gemergt. Wenn du eine Pipeline änderst, liste alle ihre Komponenten auf, einschließlich der Standardwerte, die du behalten willst.
• Deaktiviere ungenutzte Ports, um den Service aufgeräumt zu halten, zum Beispiel ports.jaeger-compact.enabled: false.
• Logs und der Debug-Exporter: Aktivierst du logsCollection mit includeCollectorLogs: true und behältst den debug-Exporter in der Logs-Pipeline, kann der Collector seine eigenen Logs lesen und zurückspeisen, was eine Log-Explosion verursacht. Wechsle zuerst auf einen echten Exporter.

Ein auf OTLP reduziertes 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

Secrets und Umgebungsvariablen

Injiziere Zugangsdaten mit Umgebungsvariablen und referenziere sie in der Collector-Konfiguration mit ${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}

Halte das Secret in Klartext aus Git heraus: Verschlüssele es mit SOPS oder synchronisiere es aus einem Secret Manager.

Mit Flux deployen

Wenn du Flux nutzt, ist das Chart ein 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

Eine Änderung der Values in Git rollt dann über Flux aus. Die Flux-Reihe behandelt HelmRelease-Optionen wie Remediation und Drift-Erkennung.

Prüfen

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- und Service-Namen folgen deinem Release-Namen. Gerät ein Pod in eine Absturzschleife, nennt das Log meist die unbekannte Komponente oder den ungültigen Schlüssel. In diesem Fall enthält das Image eine Komponente nicht, die deine Konfiguration referenziert, oder ein Wert wurde unter dem falschen Schlüssel eingerückt.