Dépanner DynaKube : troubleshoot, annotations et support-archive

Dépanner DynaKube : lancer troubleshoot, lire les annotations d’injection et produire un support-archive pour le support Dynatrace, pas à pas.
Dépanner DynaKube : troubleshoot, annotations et support-archive

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 (ou oc sur OpenShift) au namespace dynatrace, le namespace par défaut de l’Operator.
  • Dynatrace Operator 0.9.0 ou plus pour troubleshoot, 0.11.0 ou plus pour support-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.

Sortie de la sous-commande dynatrace-operator troubleshoot dans la documentation : namespace, DynaKube, secret, pull secret et tenant tous marqués comme valides

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.

Annotations d'un pod dont l'injection est ignorée : injected false pour OneAgent, l'enrichissement de métadonnées et l'exporteur OTLP, avec les raisons MissingTenantUUID, OwnerLookupFailed et IngestEndpointUnavailable
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.txt et operator-version.txt ;
  • un dossier logs avec 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 manifests avec les manifestes des composants et des DynaKube ;
  • troubleshoot.txt, la sortie de la commande de l’étape 2, lancée automatiquement ;
  • supportarchive_console.log et, 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.

Commande kubectl run qui lance support-archive dans un pod autonome avec l'image de l'Operator, les arguments --stdout et --delay=10, et redirige la sortie vers operator-support-archive.zip

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 dynatrace montre le DynaKube sans erreur, et troubleshoot n’indique plus d’échec.
  • Les pods du namespace dynatrace sont 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.zip s’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 troubleshoot et 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.

Total
0
Shares
Laisser un commentaire

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

Previous Post
Fidélité RAG : évaluer un RAG et comprendre les limites de la métrique

Fidélité RAG : évaluer un RAG et comprendre les limites de la métrique

Next Post
Alerting rules Prometheus : for, keep_firing_for et tests promtool en CI

Alerting rules Prometheus : for, keep_firing_for et tests promtool en CI

Related Posts