Activer APM sur Kubernetes via Single Step Instrumentation

Avant toute chose : Résolvez complètement toutes les variables dans ## Contexte à résoudre avant d'agir. Ne commencez pas l'Étape 0 tant que chaque variable n'a pas une valeur concrète.

Défaillance silencieuse — vérifiez ceci avant toute autre étape :

Si l'application a ddtrace, dd-trace, ou tout SDK OpenTelemetry dans son manifeste de dépendances (requirements.txt, package.json, Gemfile, go.mod, pom.xml) — même sans instruction d'import dans le code — SSI se désactivera silencieusement à l'exécution.

La défaillance est invisible : les conteneurs init s'exécutent et se terminent, le pod démarre en bon état, aucune erreur n'apparaît dans kubectl ou pup, mais aucune trace n'arrive. L'injecteur détecte le traceur installé par l'utilisateur et se termine proprement sans journaliser quoi que ce soit.

Claude exécute

grep -rE "ddtrace|dd-trace|opentelemetry" \
  requirements.txt package.json Gemfile go.mod pom.xml 2>/dev/null \
  || echo "No tracer dependency found"

Si une correspondance — arrêtez. Supprimez complètement le package (pas seulement l'import), reconstruisez l'image, rechargez-la dans le cluster, et redémarrez le pod avant de continuer. Un package présent dans le manifeste suffit pour déclencher ceci, même s'il n'est jamais importé.

Déclencheurs

Invoquez cette compétence quand l'utilisateur exprime l'intention de :

• Activer APM sur un cluster Kubernetes
• Instrumenter les applications Kubernetes avec la traçage Datadog
• Configurer Single Step Instrumentation (SSI)

N'invoquez PAS cette compétence si :

• L'Agent Datadog n'est pas encore installé — exécutez d'abord agent-install
• L'utilisateur souhaite vérifier SSI après la configuration — utilisez verify-ssi
• L'utilisateur souhaite activer Profiler, AppSec, ou Data Streams — utilisez dd-apm-k8s-sdk-features

Prérequis

Ce ne sont pas des lectures — vérifiez activement chacun avant de procéder.

Environnement

• [ ] L'Agent Datadog est installé et en bon état — agent-install terminé
• [ ] Kubernetes v1.20+
• [ ] Pools de nœuds Linux uniquement — les pods Windows nécessitent une exclusion d'espace de noms explicite
• [ ] Le cluster n'est pas ECS Fargate — non supporté
• [ ] Pas d'environnement SELinux renforcé — non supporté
• [ ] Pas une très petite instance VM (ex. t2.micro) — SSI peut dépasser les timeouts d'init
• [ ] Aucune baseline PodSecurity ou politique restreinte appliquée

Langage et runtime

• [ ] Le langage de l'application est l'un de : Java, Python, Ruby, Node.js, .NET, PHP
• [ ] La version du runtime est dans la plage supportée par SSI — vérifiez contre la matrice de compatibilité SSI
• [ ] L'app Node.js n'utilise pas ESM — SSI ne supporte pas ESM
• [ ] L'app Java n'utilise pas déjà un flag JVM -javaagent

Instrumentation existante — confirmée nettoyée par la vérification en haut de cette compétence. Si vous avez sauté cette vérification, revenez et exécutez-la maintenant.

Contexte à résoudre avant d'agir

Découvrez depuis le cluster — ne demandez pas à l'utilisateur des informations que vous pouvez trouver vous-même.

Étape 0 (Uniquement si instrumentation existante détectée) : Supprimer l'instrumentation manuelle

Analysez tous les fichiers source pour : import ddtrace, from ddtrace, require 'ddtrace', require("dd-trace"), opentelemetry, tracer.trace(

Vérifiez aussi les manifestes de dépendances pour les packages ddtrace / dd-trace / OTel SDK.

Si trouvé — supprimez l'import/package, puis reconstruisez et rechargez :

Claude exécute

docker build -f <DOCKERFILE_PATH> -t <IMAGE_NAME> <BUILD_CONTEXT>

[DÉCISION : comment ce cluster obtient-il les images locales ?]

Vérifiez le script de configuration du repo (ex. create.sh, Makefile, justfile) pour voir comment les images sont chargées — ne devinez pas à partir du nom du cluster ou du contexte. Motifs courants :

Si le script de configuration est ambigü, exécutez exactement la commande de chargement qu'il utilise.

• Basé sur registre : sautez — l'image sera tirée au prochain déploiement

Confirmez avec l'utilisateur avant de redémarrer. Dites à l'utilisateur : « Je dois redémarrer <DEPLOYMENT_NAME> dans <APP_NAMESPACE> pour récupérer l'image reconstruite. Prêt à procéder ? » Attendez la confirmation.

Claude exécute

kubectl rollout restart deployment/<DEPLOYMENT_NAME> -n <APP_NAMESPACE>
kubectl wait --for=condition=Ready pod \
  -l app=<APP_LABEL> \
  -n <APP_NAMESPACE> \
  --timeout=120s

Étape 1 : Étendre le manifeste DatadogAgent avec APM

SSI est configuré sur la ressource DatadogAgent existante — ne créez pas de manifeste séparé.

Choisissez le scope de ciblage basé sur ce que l'utilisateur a demandé :

• L'utilisateur a demandé d'instrumenter toutes les applications ou n'a pas spécifié de scope → utilisez Option A (cluster entier)
• L'utilisateur a demandé des espaces de noms spécifiques uniquement → utilisez Option B
• L'utilisateur a demandé d'exclure des espaces de noms du cluster entier → utilisez Option C
• L'utilisateur a demandé des pods/charges de travail spécifiques → utilisez Option D

Par défaut c'est le cluster entier (Option A). Si l'utilisateur a dit « toutes mes applications », « tout mon cluster », ou n'a pas limité le scope, utilisez Option A sans enabledNamespaces ou targets.

Recommended ddTraceVersions : java: "1", python: "2", js: "5", dotnet: "3", ruby: "2", php: "1"

Option A — Cluster entier (par défaut) :

features:
  apm:
    instrumentation:
      enabled: true

Option B — Espaces de noms spécifiques uniquement :

features:
  apm:
    instrumentation:
      enabled: true
      enabledNamespaces:
        - <APP_NAMESPACE>

Option C — Cluster entier avec exclusions :

features:
  apm:
    instrumentation:
      enabled: true
      disabledNamespaces:
        - jenkins
        - kube-system

Option D — Cibler des charges de travail spécifiques :

features:
  apm:
    instrumentation:
      enabled: true
      targets:
        - name: <TARGET_NAME>
          namespaceSelector:
            matchNames:
              - <APP_NAMESPACE>
          ddTraceVersions:
            <LANGUAGE>: "<MAJOR_VERSION>"

Note : ddTraceVersions s'applique uniquement à l'intérieur d'une entrée targets[] (Option D). Ce n'est pas valide aux côtés de enabledNamespaces ou directement au niveau instrumentation.

Claude exécute

kubectl apply -f datadog-agent.yaml

Si datadogagent.datadoghq.com/datadog configured — passez à l'Étape 2.

ERREUR : Erreur de validation — vérifiez YAML. enabledNamespaces et disabledNamespaces ne peuvent pas être tous deux définis.

Étape 2 : Informer l'utilisateur sur les Unified Service Tags

Ne modifiez PAS les Déploiements d'application sans confirmation explicite de l'utilisateur. L'application d'étiquettes aux charges de travail d'application existantes est une modification de ressources gérées par le client.

Informez l'utilisateur que l'ajout d'Unified Service Tags (UST) à ses Déploiements permettra un balisage correct service/env/version dans Datadog. C'est optionnel pour que SSI fonctionne mais recommandé pour une observabilité complète :

# Ajouter à la fois à metadata.labels et spec.template.metadata.labels
tags.datadoghq.com/env: "<ENV>"
tags.datadoghq.com/service: "<SERVICE_NAME>"
tags.datadoghq.com/version: "<VERSION>"

Si l'utilisateur veut que vous appliquez ceux-ci, obtenez d'abord sa confirmation. Les étiquettes UST ne sont pas requises pour que les traces APM circulent — SSI fonctionne sans elles.

Étape 3 : Redémarrer les pods d'application

Confirmez avec l'utilisateur avant de redémarrer. Dites à l'utilisateur : « Je dois redémarrer <DEPLOYMENT_NAME> dans <APP_NAMESPACE> pour que SSI s'injecte dans les pods. Cela causera une brève interruption de service. Prêt à procéder ? » Attendez la confirmation.

Claude exécute

kubectl rollout restart deployment/<DEPLOYMENT_NAME> -n <APP_NAMESPACE>

kubectl wait --for=condition=Ready pod \
  -l app=<APP_LABEL> \
  -n <APP_NAMESPACE> \
  --timeout=120s

Si les pods redémarrent proprement, les conteneurs init nommés datadog-lib-<language>-init seront visibles dans la spec du pod.

ERREUR : Les pods crash-loopent — vérifiez l'instrumentation personnalisée existante. Voir troubleshoot-ssi.

Terminé

Sortez quand TOUS les points suivants sont vrais :

• [ ] features.apm.instrumentation est présent dans le manifeste DatadogAgent appliqué
• [ ] L'utilisateur a été informé qu'il doit redémarrer ses pods d'application
• [ ] L'utilisateur a été informé sur les Unified Service Tags (UST) et comment les appliquer s'il le souhaite
• [ ] Scope confirmé : quelles charges de travail sont instrumentées, lesquelles ont été sautées et pourquoi

Passez automatiquement à verify-ssi maintenant — ne demandez pas la permission à l'utilisateur.

Contraintes de sécurité

• N'écrivez jamais une clé API brute dans aucun fichier ou message de chat
• N'utilisez jamais l'espace de noms default pour les ressources Datadog
• Ne modifiez jamais directement les paramètres admissionController — SSI gère ceci via l'Operator
• N'ajoutez pas de configuration APM aux manifestes d'application — configurez uniquement via DatadogAgent
• Exception : Les étiquettes UST (tags.datadoghq.com/*) sur les Déploiements d'application sont requises et intentionnelles
• N'exécutez jamais kubectl delete sans confirmation de l'utilisateur
• docker push vers un registre nécessite toujours la confirmation de l'utilisateur
• N'utilisez jamais kubectl patch pour appliquer les étiquettes UST ou aucune modification de Deployment. Modifiez toujours le fichier YAML de Deployment et faites kubectl apply -f. Les modifications apportées avec kubectl patch sont temporaires et seront écrasées au prochain rollout.