OpenTelemetry Operator Kubernetes : Collector et auto-instrumentation pas à pas

OpenTelemetry Operator Kubernetes : installez-le avec Helm, déclarez un Collector vers Dynatrace et instrumentez Java ou Python par simple annotation.
OpenTelemetry Operator Kubernetes : Collector et auto-instrumentation pas à pas

Instrumenter vingt microservices à la main, c’est vingt Dockerfiles à modifier, vingt agents à mettre à jour et autant de configurations d’export qui divergent. L’OpenTelemetry Operator Kubernetes inverse la logique : vous déclarez une fois le Collector et l’instrumentation sous forme de ressources Kubernetes, et l’Operator les applique aux pods par simple annotation.

Objectif de ce tutoriel : installer l’Operator, déployer un Collector passerelle qui exporte vers Dynatrace, activer l’auto-instrumentation Java et Python par annotation, puis vérifier que les traces arrivent. Le contenu vaut pour Dynatrace SaaS et Dynatrace Managed : seule l’URL OTLP change.

Ne confondez pas cet Operator avec Dynatrace Operator, qui gère OneAgent et ActiveGate (voir Dynatrace Operator sur Kubernetes). Les deux peuvent cohabiter, à condition de ne pas instrumenter deux fois les mêmes pods.

Ce que gère l’OpenTelemetry Operator

L’Operator est une implémentation du modèle Operator de Kubernetes. Il gère deux choses : des instances de l’OpenTelemetry Collector et l’auto-instrumentation des workloads avec les bibliothèques OpenTelemetry. Il s’appuie sur quatre ressources personnalisées :

  • OpenTelemetryCollector (opentelemetry.io/v1beta1, nom court otelcol) : un Collector et sa configuration, en mode deployment (par défaut), daemonset, statefulset ou sidecar.
  • Instrumentation (opentelemetry.io/v1alpha1, nom court otelinst) : la configuration du SDK injecté (exporteur, propagateurs, échantillonneur, image par langage).
  • TargetAllocator : répartit les cibles de scraping Prometheus entre plusieurs Collectors (modes statefulset et daemonset).
  • OpAMPBridge : relie les Collectors à un serveur OpAMP.

L’auto-instrumentation couvre Apache HTTPD, .NET, Go, Java, Nginx, Node.js et Python. Go et Nginx sont désactivés par défaut côté Operator (--enable-go-instrumentation, --enable-nginx-instrumentation).

Prérequis

  • Un cluster Kubernetes 1.24 ou plus récent (prérequis du chart Helm) et kubectl.
  • Helm 4.0 ou plus pour la version actuelle du chart, ou kubectl apply avec le manifeste de release.
  • Un certificat pour les webhooks d’admission : cert-manager (méthode par défaut) ou un certificat autosigné généré par le chart.
  • Un token Dynatrace avec openTelemetryTrace.ingest, metrics.ingest et logs.ingest, et l’URL OTLP : https://<env-id>.live.dynatrace.com/api/v2/otlp en SaaS, https://<votre-domaine>/e/<env-id>/api/v2/otlp en Managed.

Installer l’OpenTelemetry Operator Kubernetes

Étape 1 : déployer l’Operator avec Helm

helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts
helm repo update
helm install opentelemetry-operator open-telemetry/opentelemetry-operator \
  --namespace opentelemetry-operator-system --create-namespace \
  --set "manager.collectorImage.repository=ghcr.io/open-telemetry/opentelemetry-collector-releases/opentelemetry-collector-k8s" \
  --set admissionWebhooks.certManager.enabled=false \
  --set admissionWebhooks.autoGenerateCert.enabled=true

Les deux dernières options demandent à Helm de générer un certificat autosigné : pratique sans cert-manager. Si cert-manager est installé, retirez-les. Sans Helm, la commande officielle est kubectl apply -f https://github.com/open-telemetry/opentelemetry-operator/releases/latest/download/opentelemetry-operator.yaml, avec cert-manager obligatoire. Les CRD ne sont pas supprimées à la désinstallation du chart : pensez-y lors d’un nettoyage.

Étape 2 : créer le Collector passerelle

kubectl create namespace observability
kubectl -n observability create secret generic dynatrace-otlp \
  --from-literal=DT_ENDPOINT='https://<env-id>.live.dynatrace.com/api/v2/otlp' \
  --from-literal=DT_API_TOKEN='<token>'
apiVersion: opentelemetry.io/v1beta1
kind: OpenTelemetryCollector
metadata:
  name: gateway
  namespace: observability
spec:
  mode: deployment
  replicas: 2
  envFrom:
    - secretRef:
        name: dynatrace-otlp
  config:
    receivers:
      otlp:
        protocols:
          grpc:
            endpoint: 0.0.0.0:4317
          http:
            endpoint: 0.0.0.0:4318
    processors:
      memory_limiter:
        check_interval: 1s
        limit_percentage: 75
        spike_limit_percentage: 15
      cumulative_to_delta: {}
    exporters:
      otlp_http:
        endpoint: ${env:DT_ENDPOINT}
        headers:
          Authorization: "Api-Token ${env:DT_API_TOKEN}"
    service:
      pipelines:
        traces:
          receivers: [otlp]
          processors: [memory_limiter]
          exporters: [otlp_http]
        metrics:
          receivers: [otlp]
          processors: [memory_limiter, cumulative_to_delta]
          exporters: [otlp_http]
        logs:
          receivers: [otlp]
          processors: [memory_limiter]
          exporters: [otlp_http]

Ce que fait l’Operator : il crée le Deployment et, parce qu’il repère des récepteurs avec ports dans config, une paire de Services (dont un headless) qui exposent 4317 et 4318. Le Service principal s’appelle gateway-collector. Attention : l’Operator ne valide pas toute la configuration ; une configuration invalide peut être acceptée, puis faire planter le Collector au démarrage. otlp_http est le nom récent de l’exporteur otlphttp, toujours accepté comme alias. L’image opentelemetry-collector-k8s fixée à l’étape 1 inclut cumulative_to_delta (il figure dans le manifeste de la distribution Kubernetes) ; pour un autre composant, vérifiez ce manifeste ou changez d’image via spec.image.

Pour un Collector par nœud avec enrichissement k8sattributes, la variante DaemonSet est détaillée dans le Collector OpenTelemetry sur Kubernetes.

Activer l’auto-instrumentation par annotation

Étape 3 : déclarer la ressource Instrumentation

La documentation du dépôt de l’Operator (licence Apache 2.0) montre la forme générale de la ressource :

Extrait du README auto-instrumentation du dépôt opentelemetry-operator : ressource Instrumentation v1alpha1 avec exporter endpoint, propagateurs tracecontext, baggage et b3, sampler parentbased_traceidratio à 0.25 et image Python

Adaptée à notre passerelle :

apiVersion: opentelemetry.io/v1alpha1
kind: Instrumentation
metadata:
  name: dynatrace
  namespace: boutique
spec:
  exporter:
    endpoint: http://gateway-collector.observability:4317
  propagators:
    - tracecontext
    - baggage
  sampler:
    type: parentbased_traceidratio
    argument: "1"
  python:
    env:
      - name: OTEL_EXPORTER_OTLP_ENDPOINT
        value: http://gateway-collector.observability:4318

Les lignes critiques : propagators alimente OTEL_PROPAGATORS (W3C tracecontext pour suivre une requête entre services) ; sampler alimente OTEL_TRACES_SAMPLER et son argument. L’auto-instrumentation Python (comme .NET et Go) exporte en http/protobuf par défaut : elle doit viser le port 4318, d’où la surcharge de l’endpoint.

Étape 4 : annoter les workloads

spec:
  template:
    metadata:
      annotations:
        instrumentation.opentelemetry.io/inject-java: "true"

La valeur "true" prend l’Instrumentation du namespace ; vous pouvez aussi donner un nom ("dynatrace") ou "autre-namespace/dynatrace", et "false" exclut explicitement. L’annotation peut être posée sur le namespace pour couvrir tous ses pods. Les autres langages suivent le même modèle : inject-python, inject-nodejs, inject-dotnet, inject-go (avec otel-go-auto-target-exe et des privilèges élevés), inject-apache-httpd, inject-nginx. Pour un pod à plusieurs conteneurs, instrumentation.opentelemetry.io/container-names désigne les conteneurs ciblés.

L’injection a lieu à la création du pod : relancez le déploiement avec kubectl -n boutique rollout restart deployment/panier.

Comment vérifier que ça fonctionne

  1. Les ressources existent et le Collector tourne :
    kubectl get otelcol -A
    kubectl get otelinst -n boutique
    kubectl -n observability get pods,svc
  2. Le pod applicatif a reçu l’init container et la variable de l’agent :
    kubectl -n boutique get pod -l app=panier \
      -o jsonpath='{.items[0].spec.initContainers[*].name}'
    # attendu : opentelemetry-auto-instrumentation-java
    kubectl -n boutique exec deploy/panier -- env | grep -E "JAVA_TOOL_OPTIONS|OTEL_"
  3. Le Collector exporte sans erreur :
    kubectl -n observability logs deploy/gateway-collector | grep -iE "error|401|403"
  4. En SaaS, dans un Notebook :
    fetch spans, from: now() - 15m
    | filter k8s.namespace.name == "boutique"
    | summarize spans = count(), by: {service.name}

    L’Operator ajoute des attributs de ressource Kubernetes selon les conventions sémantiques ; si le filtre ne renvoie rien, filtrez sur service.name.

  5. En Managed, ouvrez la vue des traces distribuées et cherchez le service panier.

Rien n’arrive ? Suivez le diagnostic des traces OpenTelemetry absentes.

Cohabiter avec Dynatrace Operator

Si Dynatrace Operator injecte déjà OneAgent dans un namespace, n’y ajoutez pas l’auto-instrumentation OpenTelemetry : vous obtiendriez des spans en double (voir OneAgent et OpenTelemetry : éviter les doublons). Séparez les périmètres : namespaceSelector côté DynaKube, annotations inject-* côté OpenTelemetry. Notez aussi que Dynatrace Operator sait configurer automatiquement les exporteurs OTLP des pods (.spec.otlpExporterConfiguration), une alternative si vous voulez garder l’instrumentation dans l’image.

Bonnes pratiques

  • Épinglez les versions de l’Operator, du chart et des images d’instrumentation ; une montée de version change les agents de tous les pods au prochain redémarrage.
  • Une Instrumentation par namespace, versionnée en Git avec les manifestes applicatifs.
  • Échantillonnage au bon endroit : 100 % en tête, et décision fine dans la passerelle (voir le tail sampling OpenTelemetry).
  • Limites de ressources sur le Collector, alignées avec memory_limiter.
  • Déploiement progressif : un namespace pilote, comparaison de la latence avant/après, puis généralisation.

Questions fréquentes

Faut-il cert-manager ?

Non avec Helm : admissionWebhooks.autoGenerateCert.enabled=true génère un certificat autosigné. Le manifeste kubectl apply de la release, lui, suppose cert-manager.

Pourquoi mon pod n’est-il pas instrumenté ?

Le plus souvent, il a été créé avant l’annotation ou l’Instrumentation n’existe pas dans le namespace. Vérifiez aussi que le langage est activé côté Operator (Go et Nginx sont désactivés par défaut).

Sidecar ou passerelle ?

Le mode sidecar s’injecte avec l’annotation sidecar.opentelemetry.io/inject et isole chaque application. La passerelle partagée consomme moins et se gère en un seul point ; commencez par elle.

Conclusion

L’OpenTelemetry Operator Kubernetes transforme l’instrumentation en configuration déclarative : une ressource Collector, une ressource Instrumentation, une annotation par workload. Vous gagnez des traces homogènes sans toucher aux images, et le toil de mise à jour des agents disparaît. Commencez par un namespace, validez les spans dans Dynatrace, puis étendez.

span.observer est un blog indépendant de la communauté, non affilié à Dynatrace LLC. Dynatrace est une marque de Dynatrace LLC. Les CRD, options du chart et versions d’images évoluent : vérifiez-les dans la documentation de l’OpenTelemetry Operator et dans celle de Dynatrace.

Total
0
Shares
Laisser un commentaire

Votre adresse e-mail ne sera pas publiée. Les champs obligatoires sont indiqués avec *

Previous Post
OpenTelemetry vs Prometheus (OTel vs Prometheus) : complémentaires ou concurrents ?

OpenTelemetry vs Prometheus (OTel vs Prometheus) : complémentaires ou concurrents ?

Next Post
Serveur MCP STDIO : contenir le risque d'exécution de commandes

Serveur MCP STDIO : contenir le risque d’exécution de commandes

Related Posts