Dépannage réseau HDFS : guide pratique de terrain

Introduction

Lorsqu'un cluster HDFS cesse de répondre, le problème ne se situe souvent pas dans la couche de stockage, mais dans la plomberie réseau qui relie les clients, les NameNodes et les DataNodes. Un DataNode incapable de joindre le NameNode ne s'enregistrera pas. Un client qui résout une mauvaise adresse échouera avant même d'ouvrir un socket. Une règle de pare-feu qui abandonne silencieusement le trafic sur le port de transfert des DataNodes transformera une lecture normale en connexion bloquée.

Ce guide parcourt un processus structuré de dépannage réseau HDFS. Vous apprendrez à inspecter la résolution DNS, valider les ports en écoute, tester la connectivité entre services, interpréter les signaux de défaillance courants et récupérer sans aggraver la situation. Chaque étape inclut une commande concrète, la sortie attendue et la conduite à tenir lorsque cette sortie diffère.

Le public visé comprend les développeurs, les ingénieurs DevOps et les équipes de startups qui exploitent des clusters HDFS de petite et moyenne taille et doivent diagnostiquer rapidement les problèmes. Vous devez être à l'aise avec un terminal et avoir des connaissances de base de l'architecture HDFS. Tous les exemples supposent un déploiement Apache HDFS standard, mais les mêmes principes s'appliquent aux distributions gérées.

La sécurité opérationnelle est le fondement du processus. Avant de modifier quoi que ce soit, observez l'état actuel. Utilisez d'abord des commandes en lecture seule. Limitez chaque changement à un élément précis et sachez comment l'annuler si le résultat n'est pas celui attendu. Remplacez les identifiants réels, les jetons et les clés privées par des espaces réservés dans toute commande que vous partagez ou documentez.

Établir un inventaire précis de l'environnement

Avant de dépanner, vous devez savoir exactement à quoi vous avez affaire. La version HDFS installée, la topologie de déploiement et la configuration réseau actuelle déterminent les commandes sûres et les options disponibles. Exécuter une commande prévue pour une version sur une autre peut produire une sortie trompeuse ou, pire, modifier le cluster de manière inattendue.

Commencez par deux observations en lecture seule depuis un nœud censé faire partie du cluster. Premièrement, identifiez la version HDFS :

hdfs version

La sortie attendue inclut une ligne telle que :

Hadoop 3.3.6

Si la commande n'est pas trouvée, vérifiez si les binaires HDFS sont dans le PATH actuel ou si vous êtes sur le bon hôte. Ne poursuivez pas le dépannage tant que vous ne connaissez pas la version, car les ports par défaut et les noms des paramètres de configuration peuvent varier.

Deuxièmement, capturez les écouteurs réseau actuels sur le nœud. La commande exacte dépend de la distribution Linux, mais ss est disponible sur la plupart des systèmes modernes :

ss -tulpn | grep -E ':(8020|9870|9866|9864)'

Cela liste les sockets en écoute sur le port RPC classique du NameNode (8020), le port HTTP de l'interface utilisateur du NameNode (9870 dans Hadoop 3.x), le port de transfert de données du DataNode (9866) et le port HTTP du DataNode (9864). Sur Hadoop 2.x, les ports HTTP sont 50070 et 50075, et le port de transfert du DataNode est 50010. Si vous ne voyez rien, soit les services ne sont pas en cours d'exécution, soit ils écoutent sur des ports non par défaut, soit un pare-feu local intercepte le trafic. Vous devrez inspecter les fichiers de configuration pour trouver les ports réels.

Une erreur courante est de supposer que les ports par défaut sont utilisés. Dans un déploiement personnalisé, le port RPC du NameNode peut être défini sur une autre valeur dans hdfs-site.xml. Vérifiez toujours en lisant la configuration effective plutôt qu'en devinant. La commande hdfs getconf peut afficher les valeurs de la configuration :

hdfs getconf -confKey dfs.namenode.rpc-address

La sortie peut être 0.0.0.0:8020 ou un hôte et un port spécifiques. Comparez-la avec les sockets en écoute observés précédemment. Une incohérence indique souvent un service qui n'a pas pris en compte un changement de configuration ou qui s'exécute avec un répertoire de configuration différent.

Enregistrez l'état actuel et un horodatage avant toute intervention. Par exemple, enregistrez une copie du fichier de configuration pertinent :

cp /etc/hadoop/conf/hdfs-site.xml /tmp/hdfs-site.xml.bak.$(date +%Y%m%d)

Cela vous donne un point de restauration si un changement ultérieur aggrave la situation. Ne modifiez jamais un fichier de configuration de production sans d'abord comprendre comment le restaurer.

Diagnostiquer et corriger les problèmes de résolution DNS

De nombreuses pannes de connectivité HDFS commencent par le DNS. HDFS s'appuie fortement sur la résolution de noms d'hôtes pour la découverte de services, l'enregistrement des DataNodes et le routage des clients. Si un NameNode résout son propre nom d'hôte vers une mauvaise adresse IP, les DataNodes seront invités à se connecter à une adresse inaccessible. Si un client résout le nom d'hôte d'un DataNode vers une IP publique mais que le port de transfert de données n'est ouvert que sur un réseau privé, les lectures se bloqueront.

Commencez par vérifier les résolutions DNS directe et inverse depuis le nœud affecté. Supposons que le cluster est censé avoir le nom d'hôte du NameNode namenode.example.com et l'IP 10.0.0.10. Exécutez :

getent hosts namenode.example.com

Sortie attendue :

10.0.0.10      namenode.example.com

Si la sortie affiche une IP différente ou aucun résultat, la résolution DNS est défaillante. Vérifiez également la résolution inverse :

getent hosts 10.0.0.10

La sortie attendue doit inclure namenode.example.com. Certains composants HDFS effectuent des résolutions inverses pour la journalisation et les contrôles de sécurité. Un enregistrement inverse manquant peut provoquer des pannes déroutantes, surtout avec Kerberos activé.

Sur les distributions Linux modernes, getent hosts utilise le Name Service Switch (NSS) et consulte /etc/hosts et le DNS selon /etc/nsswitch.conf. Si vous êtes sur un système plus ancien, la commande équivalente est nslookup ou dig.

Un piège classique est une entrée obsolète dans /etc/hosts. Lors de la configuration initiale du cluster, un administrateur peut avoir ajouté une entrée temporaire pour un nom d'hôte qui a ensuite changé d'adresse IP. Cette entrée remplace le DNS et envoie silencieusement le trafic au mauvais endroit. Pour vérifier si /etc/hosts contient une entrée pour le nom d'hôte :

grep 'namenode.example.com' /etc/hosts

Si vous trouvez une entrée, comparez son IP avec celle prévue. Si elle est obsolète, mettez-la à jour seulement après avoir confirmé que la nouvelle IP est joignable depuis ce nœud et qu'aucune autre configuration ne dépend de l'ancienne IP. Le plus petit changement consiste à éditer /etc/hosts avec un éditeur de texte et à enregistrer une sauvegarde d'abord.

Si le DNS est géré par un serveur externe, utilisez dig pour interroger spécifiquement :

dig +short namenode.example.com A

Cela contourne /etc/hosts et interroge directement le résolveur DNS configuré. Si dig renvoie la bonne IP mais que getent en renvoie une différente, le fichier local interfère.

Après tout changement DNS, vérifiez que la correction s'est propagée et que le service concerné peut désormais résoudre correctement. Exécutez à nouveau getent hosts sur le nœud où vous avez fait le changement, puis répétez sur un autre nœud du cluster. Si vous avez modifié un enregistrement de serveur DNS, rappelez-vous que la mise en cache DNS peut retarder la visibilité. Videz le cache du résolveur local si nécessaire, mais soyez prudent : la commande varie selon le système d'exploitation et le système d'initialisation.

Valider les ports HDFS et les services en écoute

Une fois le DNS correct, la couche suivante est la disponibilité des ports. HDFS utilise plusieurs ports TCP pour le RPC, le HTTP et le transfert de données. Si un port n'est pas en écoute, bloqué ou lié à la mauvaise interface, les connexions échoueront.

D'abord, confirmez que les services attendus écoutent réellement. Sur l'hôte du NameNode, exécutez :

ss -tlnp | grep -E ':(8020|9870)'

La sortie attendue inclut des lignes montrant le nom du processus et l'adresse d'écoute :

LISTEN 0      4096          0.0.0.0:8020      0.0.0.0:*    users:(("java",pid=1234,fd=42))
LISTEN 0      4096          0.0.0.0:9870      0.0.0.0:*    users:(("java",pid=1234,fd=43))

Si le port RPC est absent, le processus NameNode a peut-être échoué à démarrer. Consultez les journaux du NameNode, généralement dans /var/log/hadoop-hdfs/, pour en trouver la cause. Les échecs de démarrage courants incluent des erreurs de configuration, des autorisations de répertoire manquantes ou un répertoire de stockage verrouillé.

Sur un hôte DataNode, exécutez la vérification équivalente :

ss -tlnp | grep -E ':(9866|9864)'

La sortie attendue montre les ports de transfert et HTTP du DataNode. Si le DataNode n'écoute que sur 127.0.0.1 au lieu de 0.0.0.0 ou de l'IP externe du nœud, les clients distants ne peuvent pas se connecter. L'adresse de liaison est contrôlée par des paramètres tels que dfs.datanode.address et dfs.datanode.http.address. Inspectez leurs valeurs effectives :

hdfs getconf -confKey dfs.datanode.address
hdfs getconf -confKey dfs.datanode.http.address

Si une valeur est définie sur 127.0.0.1:9866, le DataNode n'acceptera que les connexions locales. Cela arrive parfois par inadvertance pendant le développement et est ensuite oublié. La correction consiste à modifier la configuration pour utiliser le bon nom d'hôte ou 0.0.0.0 et à redémarrer le DataNode. Cependant, changer l'adresse de liaison affecte la sécurité : lier à 0.0.0.0 expose le port sur toutes les interfaces. Limitez l'exposition avec des pare-feu ou des groupes de sécurité réseau.

Une autre erreur courante est le conflit de port avec un autre service. Par exemple, un NodeManager YARN mal configuré peut tenter d'utiliser le port 9866, ou un processus résiduel d'un démarrage échoué peut encore occuper le port. Pour identifier ce qui utilise un port :

ss -tlnp 'sport = :9866'

Cela montre le nom du processus et le PID. Si le processus n'est pas le DataNode attendu, arrêtez ce processus ou modifiez sa configuration avant de démarrer le DataNode.

Après avoir confirmé que le service écoute, testez la connectivité depuis un nœud distant à l'aide de nc ou telnet. Par exemple, depuis une machine cliente, testez le port RPC du NameNode :

nc -vz namenode.example.com 8020

La sortie réussie attendue se termine par :

Connection to namenode.example.com 8020 port [tcp/*] succeeded!

Si la connexion expire ou est refusée :

• Refusée : le port n'écoute pas sur la cible, ou un pare-feu envoie une réinitialisation.
• Expirée : le paquet est abandonné, souvent par un pare-feu ou un groupe de sécurité réseau.

Vérifiez les pare-feu intermédiaires et les groupes de sécurité cloud. La commande exacte dépend de votre environnement, mais un test rapide consiste à exécuter la même commande nc depuis l'hôte cible vers lui-même en utilisant le même nom d'hôte. Si cela réussit mais que le distant échoue, le problème se situe entre les hôtes.

Tester la connectivité HDFS entre les services

Les vérifications de port prouvent seulement qu'un socket est joignable. Elles ne prouvent pas que le protocole HDFS fonctionne de bout en bout. Un pare-feu peut autoriser la poignée de main TCP mais bloquer la charge utile, ou un service peut écouter mais être dans un mauvais état.

L'étape suivante consiste à tester la connectivité au niveau applicatif. Utilisez les outils natifs HDFS pour effectuer une petite opération. Commencez par une commande en lecture seule inoffensive comme lister le répertoire racine :

hdfs dfs -ls /

La sortie attendue montre le contenu du répertoire racine. Si la commande échoue, le message d'erreur indique généralement la couche :

• Call From client to namenode.example.com:8020 failed on connection exception signifie que le client n'a même pas pu ouvrir un socket vers le NameNode. Revenez aux vérifications DNS et de ports.
• org.apache.hadoop.ipc.RemoteException: Server IPC version mismatch indique une incompatibilité de version entre le client et le serveur.
• Connection refused signifie que le NameNode n'accepte pas les connexions sur cette interface.

Un problème subtil mais courant est que le client utilise une configuration différente de celle du serveur. Le client HDFS lit les fichiers de configuration depuis son classpath local. Si le client a un core-site.xml obsolète pointant vers la mauvaise adresse du NameNode, il échouera même si le cluster est sain. Vérifiez le système de fichiers par défaut effectif :

hdfs getconf -confKey fs.defaultFS

La sortie attendue doit être quelque chose comme hdfs://namenode.example.com:8020. Sur la machine cliente, exécutez la même commande et comparez. S'ils diffèrent, la configuration du client est incorrecte. La plus petite correction consiste à mettre à jour le core-site.xml du client ou à définir la variable d'environnement HADOOP_CONF_DIR pour pointer vers le bon répertoire de configuration.

Pour tester la connectivité des DataNodes, une lecture à partir d'un fichier exerce le chemin complet : du client au NameNode pour les métadonnées, puis du client au DataNode pour les blocs de données. Créez un petit fichier de test s'il n'en existe pas, ou utilisez-en un existant. Par exemple :

hdfs dfs -cat /user/test/hello.txt

La sortie attendue est le contenu du fichier. Si la recherche de métadonnées réussit mais que le transfert de données échoue, le client signalera une BlockMissingException ou un délai d'attente. Cela indique un problème entre le client et les DataNodes. Vérifiez les ports des DataNodes avec nc depuis le client, puis inspectez les journaux des DataNodes pour les tentatives de connexion.

Un outil de dépannage spécialisé est hdfs dfsadmin -report. Il interroge le NameNode pour l'état du cluster et liste tous les DataNodes actuellement considérés comme vivants :

hdfs dfsadmin -report

Recherchez des sections telles que :

Live datanodes (2):

Name: 10.0.0.11:9866 (datanode1.example.com)
Hostname: datanode1.example.com
...

Si un DataNode manque dans cette liste, il a échoué à s'enregistrer auprès du NameNode. Les causes courantes incluent :

• Échec de résolution DNS sur le DataNode pour son propre nom d'hôte.
• Partition réseau entre le DataNode et le NameNode.
• DataNode configuré avec une adresse de NameNode différente.
• Port du DataNode bloqué, de sorte que le NameNode ne peut pas le joindre pour la poignée de main.

Pour enquêter, allez sur l'hôte du DataNode et exécutez également hdfs dfsadmin -report. Si le DataNode ne peut pas se connecter au NameNode, il affichera une erreur. Testez ensuite la connectivité avec nc et consultez les journaux du DataNode.

Interpréter les modes de défaillance courants

Les pannes réseau HDFS tendent à se regrouper en motifs reconnaissables. Reconnaître le motif accélère le diagnostic et suggère la récupération appropriée.

Mode de défaillance 1 : Le client ne peut pas se connecter au NameNode.

Symptôme : hdfs dfs -ls lance immédiatement une exception de connexion après un court délai.

Causes probables :

• Le port RPC du NameNode n'écoute pas.
• Un pare-feu bloque le port.
• Le client a une mauvaise adresse de NameNode dans fs.defaultFS.
• Le DNS résout le nom d'hôte du NameNode vers une mauvaise IP.

Chemin de récupération :

1. Sur le NameNode, exécutez ss -tlnp | grep 8020 pour confirmer qu'il écoute.
2. Sur le client, exécutez nc -vz namenode.example.com 8020 pour tester la joignabilité.
3. Exécutez getent hosts namenode.example.com sur le client pour vérifier l'IP.
4. Exécutez hdfs getconf -confKey fs.defaultFS sur le client et le serveur pour comparer.
5. Corrigez la première incohérence trouvée et retestez avec hdfs dfs -ls /.

Mode de défaillance 2 : Le DataNode ne s'enregistre pas auprès du NameNode.

Symptôme : hdfs dfsadmin -report montre moins de nœuds vivants que prévu, et les journaux du DataNode montrent des erreurs de connexion répétées.

Causes probables :

• Le DataNode ne peut pas résoudre le nom d'hôte du NameNode.
• Un pare-feu réseau bloque le RPC du DataNode vers le NameNode.
• Le nom d'hôte du DataNode se résout vers une adresse que le NameNode ne peut pas joindre en retour (par exemple, un nom DNS privé qui se résout vers 127.0.0.1).
• Les ports utilisés par le DataNode pour le transfert de données ne sont pas joignables depuis le NameNode.

Chemin de récupération :

1. Sur le DataNode, exécutez getent hosts namenode.example.com et confirmez l'IP.
2. Depuis le DataNode, testez le port RPC du NameNode avec nc -vz namenode.example.com 8020.
3. Sur le DataNode, exécutez hostname -f et assurez-vous qu'il renvoie un nom de domaine pleinement qualifié qui se résout vers une IP joignable depuis le NameNode. S'il renvoie localhost ou un nom qui se résout vers 127.0.0.1, le DataNode peut s'enregistrer avec cette adresse, et le NameNode ne pourra pas rappeler.
4. Vérifiez le journal du DataNode pour les lignes contenant Failed to connect to ou Registration failed.
5. Corrigez la résolution du nom d'hôte ou la règle de pare-feu, puis redémarrez le DataNode et vérifiez hdfs dfsadmin -report pour lui.

Mode de défaillance 3 : Les lectures ou écritures se bloquent, mais les opérations de métadonnées réussissent.

Symptôme : hdfs dfs -ls fonctionne rapidement, mais hdfs dfs -cat ou -put reste bloqué pendant longtemps.

Causes probables :

• Port de transfert de données du DataNode bloqué entre le client et les DataNodes.
• DataNode écoutant sur une interface non routable depuis le client.
• Inadéquation de MTU réseau provoquant l'abandon de gros paquets.

Chemin de récupération :

1. Depuis le client, testez le port de transfert du DataNode pour un DataNode censé contenir un bloc du fichier : nc -vz datanode1.example.com 9866. Si cela échoue, corrigez le pare-feu ou la route réseau.
2. Sur le DataNode, vérifiez qu'il écoute sur la bonne adresse : ss -tlnp | grep 9866. S'il n'écoute que sur 127.0.0.1, modifiez dfs.datanode.address et redémarrez.
3. Vérifiez les problèmes de MTU avec ping -M do -s 1472 datanode1.example.com (sur Linux). Si cela échoue mais qu'un paquet plus petit réussit, il y a une inadéquation de MTU. Ajustez les MTU des interfaces ou activez le MSS clamping TCP.

Mode de défaillance 4 : Délais d'attente intermittents ou opérations lentes.

Symptôme : Les opérations réussissent parfois et échouent parfois, ou sont très lentes.

Causes probables :

• Serveur DNS répondant lentement, rendant chaque résolution de nom d'hôte longue de plusieurs secondes.
• Congestion réseau ou perte de paquets.
• Pare-feu limitant le débit des connexions, provoquant des tentatives répétées.

Chemin de récupération :

1. Mesurez la latence de résolution DNS avec time getent hosts namenode.example.com. Si elle est constamment élevée, enquêtez sur le serveur DNS ou ajoutez des entrées statiques à /etc/hosts pour les nœuds du cluster comme solution temporaire.
2. Vérifiez la perte de paquets avec ping -c 20 namenode.example.com et recherchez les paquets perdus.
3. Utilisez traceroute ou mtr pour identifier un saut réseau problématique.

Pièges courants dans le réseau HDFS

Même les opérateurs expérimentés tombent dans les mêmes pièges. Les connaître à l'avance peut faire gagner des heures.

Modifier le mauvais fichier de configuration.

Pourquoi cela arrive : La configuration HDFS peut se trouver dans /etc/hadoop/conf, /usr/local/hadoop/etc/hadoop ou un emplacement spécifique à l'environnement. Lorsque plusieurs copies existent, un administrateur en modifie une pendant que le service en utilise une autre.

Comment éviter : Exécutez hdfs getconf -confKey fs.defaultFS et notez quel répertoire de configuration est réellement lu. Utilisez la variable d'environnement HADOOP_CONF_DIR de manière cohérente. Lorsque vous modifiez un fichier, confirmez que le changement est visible avec hdfs getconf avant de redémarrer.

Oublier que les changements DNS sont mis en cache.

Pourquoi cela arrive : De nombreux systèmes mettent en cache les résolutions DNS au niveau du système d'exploitation ou de la JVM. Après avoir corrigé un enregistrement DNS, l'ancienne IP peut encore être renvoyée.

Comment éviter : Après un changement DNS, videz les caches lorsque c'est possible, ou attendez l'expiration du TTL. Pour la JVM, définissez la propriété networkaddress.cache.ttl de manière appropriée. Une solution temporaire consiste à ajouter l'entrée correcte à /etc/hosts sur le nœud affecté.

Utiliser des adresses IP au lieu de noms d'hôtes dans la configuration.

Pourquoi cela arrive : Cela semble plus direct, évitant complètement le DNS. Mais HDFS utilise les noms d'hôtes à plusieurs endroits, et certaines fonctionnalités comme la prise de conscience de rack attendent une utilisation cohérente des noms d'hôtes.

Comment éviter : Utilisez toujours des noms de domaine pleinement qualifiés dans les fichiers de configuration HDFS, pas des IP brutes, sauf si le déploiement exige absolument des IP pour d'autres raisons.

Redémarrer un service sans vérifier les journaux d'abord.

Pourquoi cela arrive : Lorsque quelque chose est cassé, l'impulsion est de redémarrer. Mais redémarrer peut masquer la cause racine et, dans un cluster de production, provoquer des perturbations supplémentaires.

Comment éviter : Avant de redémarrer un démon HDFS, examinez ses journaux pour les messages d'erreur. Le journal contient souvent la cause exacte, comme une autorisation refusée sur un répertoire ou une erreur d'analyse de configuration. Corrigez la cause, puis redémarrez seulement si nécessaire.

Appliquer un changement à tous les nœuds à la fois.

Pourquoi cela arrive : Lors d'un problème à l'échelle du cluster, il est tentant de pousser la même correction partout. Mais si la correction est erronée, vous avez maintenant cassé chaque nœud.

Comment éviter : Changez un nœud, vérifiez le résultat, puis propagez si réussi. Pour les changements côté client, testez avec un seul client d'abord.

Liste de contrôle des opérations pour un triage rapide

Lorsqu'un problème réseau HDFS est signalé, parcourez cette liste dans l'ordre. Chaque élément inclut le rôle responsable et une action concrète suivante.

L'ingénieur d'astreinte est responsable de la première réponse et de l'exécution de cette liste. Pour les problèmes récurrents, le responsable de l'ingénierie examine le journal des incidents chaque semaine pour identifier les motifs. Pour les changements de règles de pare-feu ou de groupes de sécurité réseau, l'administrateur réseau doit approuver avant l'exécution, et le changement est revu mensuellement selon la politique de gestion des changements.

Conclusion

Le dépannage réseau HDFS est un processus systématique, pas un jeu de devinettes. En établissant un inventaire précis de l'environnement, en vérifiant le DNS, en contrôlant les ports et en testant la connectivité à des couches croissantes, vous pouvez isoler la panne sans perturber le cluster. Chaque étape de ce guide fournit une commande et un résultat attendu, transformant une défaillance ambiguë en condition diagnosable.

La discipline fondamentale est d'observer avant d'intervenir. Utilisez des commandes en lecture seule pour recueillir des preuves. Changez une variable à la fois et vérifiez. Gardez un plan de retour en arrière pour chaque fichier de configuration que vous modifiez. Les exemples ici sont conçus pour Apache HDFS 3.x, mais la méthodologie s'applique à toutes les versions et distributions.

Comme prochaine étape, choisissez une vérification à faible risque de cet article, comme l'exécution de hdfs dfsadmin -report, et effectuez-la sur votre propre cluster. Enregistrez le résultat. Ensuite, simulez une panne de connexion en bloquant temporairement un port sur un nœud de test avec une règle de pare-feu, et pratiquez le chemin de récupération jusqu'à ce qu'il devienne routinier.

Un flux de travail de dépannage fiable rend les pannes visibles, protège les informations sensibles, limite les changements à la ressource prévue et définit la récupération avant qu'un incident ne force la décision. C'est la différence entre une panne frénétique et une correction contrôlée.