Le chart Helm OpenTelemetry déploie le Collector en DaemonSet, en Deployment ou en StatefulSet, et génère une configuration par défaut raisonnable. Vous le personnalisez entièrement via un fichier values.yaml, ce qui en fait un choix naturel pour le GitOps. Ce guide l’installe, utilise les presets pour les besoins courants, et montre comment surcharger la configuration du Collector.

Installer

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

Deux paramètres sont obligatoires :

• mode doit valoir daemonset, deployment ou statefulset. Il n’y a pas de valeur par défaut.
• image.repository choisit la distribution. La distribution Kubernetes (otel/opentelemetry-collector-k8s) inclut les composants dont les presets ont besoin. Utilisez l’image contrib si vous avez besoin de composants qui n’en font pas partie.

Épinglez le chart avec --version et l’image avec image.tag, et conservez tout dans un fichier values plutôt que dans des options --set, afin que ce soit relisible :

# values.yaml
mode: daemonset
image:
  repository: otel/opentelemetry-collector-k8s
  tag: "0.163.0"   # épinglez une version que vous avez testée

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

Quel mode pour quelle tâche

• daemonset : un pod par nœud. Utilisez-le pour la collecte de logs, les métriques du kubelet et les métriques d’hôte, car celles-ci n’existent que sur le nœud local.
• deployment : un service évolutif. Utilisez-le pour une gateway vers laquelle les applications envoient leurs données.
• statefulset : lorsque vous avez besoin d’un stockage ou d’une identité stables, par exemple une file d’attente persistante ou le modèle Target Allocator.
• Pour les données à collecter une seule fois par cluster (métriques du cluster, événements Kubernetes), utilisez un Deployment ou un StatefulSet avec un seul réplica, sinon vous obtiendrez des doublons.

Presets

Les presets activent des configurations courantes, y compris les receivers, processors, RBAC et montages de volumes dont elles ont besoin :

# Agent : logs, métriques d'hôte et de kubelet, et métadonnées de pod sur chaque nœud
mode: daemonset
presets:
  logsCollection:
    enabled: true
  hostMetrics:
    enabled: true
  kubeletMetrics:
    enabled: true
  kubernetesAttributes:
    enabled: true

# Métriques et événements à l'échelle du cluster, une seule fois
mode: deployment
replicaCount: 1
presets:
  clusterMetrics:
    enabled: true
  kubernetesEvents:
    enabled: true

Les presets nécessitent une image de Collector qui contient leurs composants ; utilisez donc l’image Kubernetes ou contrib. Considérez-les comme un point de départ : pour des besoins inhabituels, configurez vous-même les composants ainsi que leur RBAC et leurs volumes. Toutes les options sont listées dans le values.yaml du chart.

Surcharger la configuration du Collector

La clé config est fusionnée par-dessus la configuration par défaut du Collector du chart. Ajoutez ou modifiez ce dont vous avez besoin :

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]

Règles qui piègent les gens :

• L’exporter par défaut est debug. Remplacez-le dans chaque pipeline que vous utilisez, comme ci-dessus.
• Mettre un composant par défaut à null le supprime : config.receivers.zipkin: null.
• Les listes remplacent, elles ne fusionnent pas. Lorsque vous modifiez un pipeline, listez tous ses composants, y compris les composants par défaut que vous voulez conserver.
• Désactivez les ports inutilisés pour garder le Service propre, par exemple ports.jaeger-compact.enabled: false.
• Logs et exporter debug : si vous activez logsCollection avec includeCollectorLogs: true et gardez l’exporter debug sur le pipeline de logs, le Collector peut lire ses propres logs et les réinjecter, provoquant une explosion de logs. Passez d’abord à un vrai exporter.

Une gateway OTLP uniquement, allégée :

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 et variables d’environnement

Injectez les identifiants avec des variables d’environnement et référencez-les dans la configuration du Collector avec ${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}

Ne laissez pas le Secret en clair dans Git : chiffrez-le avec SOPS ou synchronisez-le depuis un gestionnaire de secrets.

Déployer avec Flux

Si vous utilisez Flux, le chart est une 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

Une modification des values dans Git se déploie ensuite via Flux. La série sur Flux couvre les options de HelmRelease comme la remédiation et la détection de dérive.

Vérifier

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

Les noms des pods et des Services suivent le nom de votre release. Si un pod boucle en crash, le log nomme généralement le composant inconnu ou la clé invalide. Dans ce cas, l’image ne contient pas un composant que votre configuration référence, ou une valeur a été indentée sous la mauvaise clé.