Un déploiement Kubernetes passe, mais les hôtes n’apparaissent pas dans Dynatrace, ou une partie des pods applicatifs reste sans OneAgent. Pour dépanner DynaKube, il faut un ordre de travail précis : sans lui, on relit des logs au hasard pendant que la couverture de supervision reste incomplète et que le MTTR s’allonge.
Ce guide pratique décrit la démarche proposée par la documentation Dynatrace pour Dynatrace Operator : l’état du DynaKube, la sous-commande troubleshoot, les logs, la lecture des annotations d’injection, puis la sous-commande support-archive pour préparer un ticket. Le plan est volontairement différent de l’article sur le raccordement de l’Operator à un cluster Managed : ici on part d’un cluster déjà installé qui se comporte mal.
Périmètre : les pages lues sont celles de la documentation Dynatrace SaaS (docs.dynatrace.com/docs). La page équivalente de la documentation Managed reprend la même section support-archive au moment de la lecture, mais vérifiez-la pour votre version.
Prérequis pour dépanner DynaKube
- Un accès
kubectl(ouocsur OpenShift) au namespacedynatrace, le namespace par défaut de l’Operator. - Dynatrace Operator 0.9.0 ou plus pour
troubleshoot, 0.11.0 ou plus poursupport-archive, d’après la documentation. - Le droit de créer un pod dans ce namespace, si vous voulez la méthode recommandée pour l’archive.
Étape 1 : lire l’état du DynaKube et des pods
La documentation fixe les premiers gestes : vérifier le DynaKube, lancer la sous-commande de diagnostic, regarder les pods, puis leurs logs et leur description.
kubectl get dynakubes -n dynatrace
kubectl -n dynatrace get pods
kubectl logs <nom-du-pod> -n dynatrace
kubectl describe pod <nom-du-pod> -n dynatrace
Le nombre de pods varie selon le mode de déploiement : Operator, OneAgent ou pilote CSI. Un pod en CrashLoopBackOff ou en Pending se lit d’abord avec describe : les événements indiquent souvent la cause (image, ressources, volume).
Étape 2 : lancer la sous-commande troubleshoot
Depuis la version 0.9.0, l’Operator embarque une sous-commande qui contrôle la configuration de base. Selon la documentation, elle vérifie que le namespace existe, que la définition de ressource (CRD) et le DynaKube existent, que l’URL d’API se termine par /api, que le secret porte le même nom que le DynaKube (ou la valeur de .spec.tokens) avec les jetons de l’Operator et de l’ingestion de données, que le customPullSecret est défini, que l’environnement est joignable depuis le pod de l’Operator avec les mêmes paramètres (proxy, certificat) et que les registres d’images OneAgent et ActiveGate sont accessibles.
kubectl exec deploy/dynatrace-operator -n dynatrace -- dynatrace-operator troubleshoot
Si votre DynaKube porte un autre nom que celui par défaut, ajoutez l’argument --dynakube <nom>. La capture ci-dessous reprend l’exemple de sortie sans erreur donné par la documentation.

Lisez la sortie de haut en bas : la première ligne marquée en échec donne la piste. Un jeton absent, une URL d’API mal formée ou un tenant injoignable se corrigent dans le DynaKube ou ses secrets. Si le tenant est injoignable alors que le réseau semble correct, regardez le proxy et le certificat : la commande les prend en compte comme le fait l’Operator.
Étape 3 : lire les logs de l’Operator et de OneAgent
Pour suivre l’Operator en direct :
kubectl -n dynatrace logs -f deployment/dynatrace-operator
Sur OpenShift, la documentation donne la même commande avec oc. Les pods OneAgent déployés par l’Operator se lisent avec kubectl logs <pod-oneagent> -n dynatrace. Sur les hôtes, les logs OneAgent sont par défaut dans /var/log/dynatrace/oneagent.
Un conseil de méthode, sans lien avec une exigence de l’éditeur : notez l’heure du premier symptôme et filtrez les logs à partir de ce moment. Dans une démarche SRE sans recherche de coupable, cette chronologie sert aussi de base au compte rendu d’incident.
Étape 4 : comprendre pourquoi une injection est ignorée
Quand un pod applicatif n’est pas instrumenté, ne cherchez pas d’abord dans les logs de l’Operator : lisez les annotations du pod. La documentation indique qu’une annotation injected: "false" existe pour OneAgent, pour l’enrichissement de métadonnées et pour la configuration de l’exporteur OTLP, chacune accompagnée d’une annotation reason.

Valeur de reason |
Sens selon la documentation |
|---|---|
NoBootstrapperConfig |
Le webhook ne trouve pas ou ne crée pas le Secret de configuration du bootstrapper dans le namespace du pod ; souvent, la réconciliation du DynaKube n’est pas terminée. |
NoMutationNeeded |
L’injection est désactivée, souvent par des annotations. |
OwnerLookupFailed |
Le propriétaire du pod n’a pas pu être déterminé, souvent parce que l’API Kubernetes était lente ou injoignable. |
MissingTenantUUID |
L’identifiant d’environnement n’est pas vérifié, en général pendant l’installation initiale ou à cause d’un problème de réconciliation. |
DynaKubeStatusNotReady |
Le statut des CodeModules n’est pas prêt, le webhook ne peut pas en choisir un. |
NoOTLPExporterConfigSecret, NoOTLPExporterActiveGateCertSecret |
Secret de configuration de l’exporteur OTLP absent, ou certificat ActiveGate absent (utile seulement si l’export OTLP passe en TLS vers ActiveGate). |
IngestEndpointUnavailable |
Aucune URL d’ingestion valide n’a pu être construite. |
Ces valeurs relient directement un symptôme à une cause : plusieurs d’entre elles disparaissent d’elles-mêmes quand la réconciliation s’achève, il est donc utile de relire le statut du DynaKube avant de redémarrer quoi que ce soit.
Cas particulier : ImagePullBackOff sur un registre privé
Les pods injectés exécutent un init container Dynatrace que le nœud doit télécharger. Le customPullSecret du DynaKube ne couvre que les composants de l’Operator dans le namespace dynatrace : il n’est pas transmis aux pods applicatifs. Selon la documentation, ce problème apparaît souvent après le passage à Kubernetes 1.35, où la fonctionnalité KubeletEnsureSecretPulledImages est activée par défaut ; la solution est de distribuer un secret de pull à vos namespaces, nœuds ou pods applicatifs.
Étape 5 : produire un support-archive pour le support
Quand le diagnostic local ne suffit pas, support-archive (Operator 0.11.0 ou plus) regroupe en un fichier ZIP ce dont le support a besoin. Selon la documentation, l’archive contient :
kubernetes-version.txtetoperator-version.txt;- un dossier
logsavec les logs de tous les conteneurs de l’Operator et des composants déployés dans son namespace, y compris les conteneurs précédents si disponibles (ActiveGate, OneAgent, webhook, pilote CSI, selon ce qui est déployé) ; - un dossier
manifestsavec les manifestes des composants et des DynaKube ; troubleshoot.txt, la sortie de la commande de l’étape 2, lancée automatiquement ;supportarchive_console.loget, si les extensions sont actives, les fichiers de diagnostic de l’Extension Controller.
La méthode recommandée lance un pod autonome qui réutilise l’image de l’Operator. Le paramètre --delay=10 compte : sans lui, kubectl run manque les premières lignes de sortie et peut corrompre l’archive. Le serviceAccountName doit être dynatrace-operator pour accéder aux logs et aux manifestes. Le contenu du ZIP part sur la sortie standard, le reste sur stderr.

La capture est un extrait : la commande complète, avec son bloc securityContext, figure dans la documentation, et c’est elle qu’il faut copier. Cette méthode suppose que les ressources de l’Operator soient encore installées sur le cluster.
Si les règles du cluster interdisent ce pod, la documentation admet, en dernier recours, de lancer la commande dans le pod de l’Operator :
kubectl exec -n dynatrace deployment/dynatrace-operator -- dynatrace-operator support-archive --stdout > operator-support-archive.zip
Sur un grand cluster, le volume de données collectées peut faire dépasser sa limite de mémoire à l’Operator et provoquer un arrêt par manque de mémoire (OOM kill), surtout s’il est sous-dimensionné. Sous Windows, utilisez l’invite de commandes cmd.exe : PowerShell n’est pas pris en charge.
Comment vérifier que ça fonctionne
kubectl get dynakubes -n dynatracemontre le DynaKube sans erreur, ettroubleshootn’indique plus d’échec.- Les pods du namespace
dynatracesont prêts. - Après un redémarrage des charges concernées, les nouveaux pods n’ont plus d’annotation
injected: "false". - Le fichier
operator-support-archive.zips’ouvre : un ZIP illisible signale presque toujours une sortie mélangée ou tronquée, d’où l’intérêt de--delay.
Bonnes pratiques
- Procédez toujours dans le même ordre : DynaKube,
troubleshoot, pods, logs, annotations, puis archive. Une checklist partagée réduit le MTTR et le toil. - Joignez
troubleshootet l’archive aux tickets plutôt que des extraits de logs isolés. - Avant de lancer l’archive, relisez les manifestes pour ne pas transmettre de secrets : l’archive contient des manifestes (vérifiez ce qu’elle contient dans votre cas, la documentation ne détaille pas le masquage).
- Tenez l’Operator à jour : voir la mise à jour de Dynatrace Operator.
- Pour la suite, l’enrichissement de métadonnées Kubernetes et le déploiement de OneAgent par l’Operator expliquent les composants dont on lit ici les annotations.
Questions fréquentes
Quelle commande lancer en premier pour dépanner DynaKube ?
kubectl get dynakubes -n dynatrace, puis dynatrace-operator troubleshoot dans le pod de l’Operator. Ce sont les deux premiers gestes de la documentation.
Faut-il exécuter support-archive dans le pod de l’Operator ?
Non, la documentation recommande un pod autonome. L’exécution dans le pod de l’Operator est un dernier recours, avec un risque d’arrêt par manque de mémoire sur un grand cluster.
Mon pod applicatif n’est pas instrumenté, où regarder ?
Dans ses annotations : oneagent.dynatrace.com/injected et oneagent.dynatrace.com/reason. La valeur de reason oriente vers la cause, par exemple une réconciliation du DynaKube non terminée.
Conclusion
Pour dépanner DynaKube, retenez une chaîne courte : statut, troubleshoot, logs, annotations, support-archive. Le diagnostic reste côté Kubernetes ; il ne dit rien de la qualité des données une fois collectées. Sources : documentation Kubernetes troubleshooting et General troubleshooting, consultées en octobre 2026.
span.observer est un blog indépendant de la communauté, non affilié à Dynatrace LLC. Dynatrace est une marque de Dynatrace LLC. Les commandes et versions évoluent : vérifiez-les dans la documentation officielle correspondant à votre version.