Dépannage HDFS avec exemples pratiques

Intro

Cette version française explique HDFS troubleshooting with practical examples avec le même objectif pratique que l article source : aider le lecteur à comprendre le contexte, les décisions à prendre et les points à vérifier avant de passer à l action.

Ce guide montre comment effectuer du HDFS troubleshooting avec des étapes pratiques et « copy-paste ». Vous apprendrez à lire les bons HDFS logs, à exécuter des HDFS commands sûres, à isoler les causes et à dérouler des workflows de HDFS recovery étape par étape pour les pannes courantes. Conservez ce document comme runbook pour les développeurs, consultants DevOps et équipes de startups opérant des data lakes ou des services Hadoop. Les environnements mêlant Apache Spark, NiFi, Kafka et Linux y trouveront aussi des repères utiles.

Vue d'ensemble du workflow

Utilisez ce flux pendant un incident :

1. Triage rapide pour capturer l'état sans le modifier.
2. Identifier le domaine en échec : client, NameNode, DataNode, réseau, authentification, ou système de fichiers.
3. Lancer des diagnostics ciblés pour ce domaine.
4. Appliquer d'abord le correctif le moins risqué et vérifier.
5. N'escalader vers des opérations de récupération plus profondes qu'en dernier recours.
6. Noter les commandes et résultats pour pouvoir répéter ou revenir en arrière.

Triage rapide

Commencez par des vérifications non destructives.

• Vérifier les processus :
• Sur NameNode et DataNodes : jps
• Inspecter l'état du cluster :
• hdfs dfsadmin -report
• Rechercher des problèmes de blocs :
• hdfs fsck / -blocks -locations -racks -openforwrite
• Lister les opérations récentes sur un chemin :
• hdfs dfs -ls -R /path-of-interest | tail -n 50
• Suivre les logs :
• tail -F $HADOOP_LOG_DIR/hdfs/NameNode.log
• tail -F $HADOOP_LOG_DIR/hdfs/DataNode.log
• grep -Ei 'ERROR|FATAL|Exception' $HADOOP_LOG_DIR/hdfs/*.log

Capturez les symptômes avant tout redémarrage.

Problèmes NameNode

Symptômes typiques :

• Les clients se figent sur les opérations de listage ou de création.
• L'UI Web est indisponible ou indique le Safe Mode.
• Exceptions telles que :
• org.apache.hadoop.hdfs.server.namenode.SafeModeException: Cannot create file ... Name node is in safe mode

Procédure pas à pas :

1. Vérifier le Safe Mode :

• hdfs dfsadmin -safemode get
• S'il est activé pour cause de faible réplication, corriger la santé des blocs (voir section réplication), puis : hdfs dfsadmin -safemode leave.

1. Vérifier le processus NameNode et les ports :

• jps doit montrer NameNode.
• netstat -plnt | grep -E '8020|50070|9870'
• Si un port est occupé, arrêter le processus en conflit ou changer l'adresse d'écoute.

1. Contrôler l'espace disque des répertoires de métadonnées (fsimage, edits) :

• df -h
• Assurez-vous d'avoir de la marge ; ne laissez pas les disques de métadonnées atteindre 100%.

1. Parcourir les logs NameNode :

• Chercher des erreurs de connectivité JournalNode, des échecs d'« shared edits », ou java.io.IOException: No space left on device.

1. Si le NameNode ne démarre pas :

• Confirmer core-site.xml et hdfs-site.xml (ex. fs.defaultFS, dfs.namenode.name.dir, dfs.namenode.edits.dir).

1. Ne pas formater la métadonnée de production :

• Ne jamais lancer hdfs namenode -format sur un répertoire de métadonnées actif.

1. Si vous utilisez des JournalNodes :

• Assurez-vous que tous les JournalNodes sont opérationnels ; vérifier le port 8485 et leurs logs.

1. Valider après récupération :

• hdfs dfsadmin -report
• Ouvrir l'UI du NameNode et confirmer les DataNodes vivants et la santé des blocs.

DataNode et réplication

Symptômes :

• Lectures/écritures lentes limitées à certains hôtes.
• Blocs UNDER_REPLICATED ou MISSING.
• Logs DataNode indiquant Volume failed ou des erreurs d'I/O disque.

Workflow de récupération :

1. Vue cluster :

• hdfs dfsadmin -report pour voir le statut Live/Dead, la décommission et la capacité.

1. Identifier les mauvais blocs :

• hdfs fsck / -blocks -locations -racks | grep -i 'Under replicated\|Missing'

1. Déclencher la réplication pour un chemin :

• hdfs dfs -setrep -w 3 /data/critical
• L'option -w attend que la cible de réplication soit atteinte.

1. Si de nombreux nœuds sont morts :

• Vérifier les règles réseau/firewall et les logs DataNode pour des pannes disque.

1. Vérifier les répertoires de données des DataNodes :

• dfs.datanode.data.dir doit exister, être accessible en écriture par l'utilisateur DataNode et disposer d'espace libre.

1. Décommission bloquée :

• Mettre à jour le fichier d'exclusion, puis hdfs dfsadmin -refreshNodes.
• S'assurer que la réplication cible peut être satisfaite avant le retrait final.

1. Rééquilibrer après ajout de capacité :

• hdfs balancer -threshold 10
• Surveiller et mettre en pause si cela impacte les jobs.

1. Confirmer la santé des blocs :

• hdfs fsck / -blocks | grep -v 'Under replicated'

Disque et permissions

Un disque plein ou des erreurs de permissions provoquent souvent des effets en cascade.

Espace disque (niveau OS) :

• df -h sur NameNode et DataNodes.
• du -sh /hadoop/dfs/* pour trouver les gros répertoires.
• Faire tourner ou compresser (gzip) les gros logs.
• Les logs DataNode peuvent montrer No space left on device ou de nombreux volumes en échec. Libérez de l'espace, ajoutez de la capacité, ou ajustez dfs.datanode.failed.volumes.tolerated avec précaution.

Usage HDFS et quotas :

• hdfs dfs -du -h -s /projects/teamX
• hdfs dfs -count -q -h /projects/teamX
• Nettoyage de la corbeille quand c'est sûr : hdfs dfs -expunge
• Envisager fs.trash.interval pour une gestion automatique de la corbeille.

Permissions :

• Inspecter et corriger :
• hdfs dfs -ls -R /path
• hdfs dfs -chown -R user: group /path
• hdfs dfs -chmod -R 755 /path
• Pour les répertoires temporaires partagés, utiliser le sticky bit 1777 si approprié.
• S'assurer que les utilisateurs de service possèdent et peuvent écrire dans leurs répertoires de travail.

Réseau et RPC

Les problèmes réseau mènent à des timeouts, nœuds morts et clients instables.

1. DNS et accessibilité :

• getent hosts namenode.example.com
• ping -c 3 namenode.example.com
• S'assurer que la résolution inverse pointe vers le même FQDN.

1. Ports requis :

• nc -vz namenode 8020
• nc -vz datanode 50010
• Vérifier aussi 50070 ou 9870 (HTTP/HTTPS), et 9864 ou 50075 (Web DataNode).
• Ouvrir les firewalls en conséquence.

1. Timeouts côté client :

• Rechercher CallTimeoutException dans les logs client.
• Envisager d'ajuster dfs.client.socket-timeout et ipc.client.connect.max.retries pour des liaisons instables.

1. Adresse du NameNode correcte :

• fs.defaultFS dans core-site.xml doit correspondre à hdfs://cluster et pointer vers le NameNode actif.

1. Awareness rack :

• S'assurer que les scripts de topologie sont présents et exécutables sur tous les nœuds, si utilisés.

Authentification Kerberos

Les échecs d'authentification apparaissent sous forme d'erreurs SASL ou GSS.

Erreurs courantes :

• GSS initiate failed
• Failed to find any Kerberos tgt
• Client cannot authenticate via SASL

Étapes de récupération :

1. Obtenir un ticket valide :

• kinit -kt /etc/security/keytabs/hdfs.headless.keytab hdfs/host@REALM
• Vérifier : klist

1. Corriger la dérive d'horloge :

• chronyc tracking ou ntpstat ; garder la dérive faible (idéalement sous 5 minutes).

1. Valider les principals et keytabs :

• Les configurations de service utilisent souvent _HOST, p.ex. hdfs/_HOST@REALM.
• S'assurer que les keytabs correspondent au FQDN de l'hôte.

1. Confirmer les réglages Kerberos :

• hadoop.security.authentication défini à kerberos dans core-site.xml.
• Fichiers JAAS et keytabs lisibles par l'utilisateur du service.

1. Problèmes spécifiques à un hôte :

• Régénérer le keytab de l'hôte, redémarrer uniquement le service concerné, puis re-tester avec hdfs dfs -ls /.

Commandes sûres

Commandes en lecture seule ou à faible risque à privilégier tôt :

• État du cluster :
• hdfs dfsadmin -report
• hdfs fsck / -blocks -locations -racks -openforwrite
• Fichiers et quotas :
• hdfs dfs -ls -R /path
• hdfs dfs -du -h -s /path
• hdfs dfs -count -q -h /path
• Processus et ports :
• jps
• netstat -plnt | grep -E '8020|50010|50070|9870|9864|8485'
• ss -lptn
• Logs :
• tail -F $HADOOP_LOG_DIR/hdfs/*
• grep -Ei 'ERROR|FATAL|SASL|Under replicated|SafeMode' $HADOOP_LOG_DIR/hdfs/*.log
• Réseau :
• getent hosts host
• nslookup host
• nc -vz host port
• curl -I http://namenode:9870/
• Kerberos :
• klist
• kinit -R
• kvno hdfs/host@REALM

Plan pilote local

Déployez ce workflow en toute sécurité sur un hôte unique ou un petit cluster de test.

Périmètre : valider le triage et deux parcours de récupération (sortie de Safe Mode et correction d'under-replication).

1. Santé de base :

• hdfs dfsadmin -report
• hdfs fsck / -blocks

1. Exercice Safe Mode :

• En environnement de test, provoquer le Safe Mode en réduisant temporairement la tolérance de réplication ou en arrêtant un DataNode de test.
• Observer hdfs dfsadmin -safemode get et les logs NameNode.
• Rétablir la capacité et sortir : hdfs dfsadmin -safemode leave.

1. Exercice under-replication :

• Créer un petit fichier : hdfs dfs -put README /tmp/
• hdfs dfs -setrep -w 3 /tmp/README sur un cluster avec 3 DNs ; surveiller la fin de réplication.
• Vérifier avec hdfs fsck /tmp/README -blocks -locations.

1. Exercice Kerberos (si activé) :

• kinit -kt ... puis klist.
• Laisser expirer le TGT ou attendre ; observer les échecs ; renouveler et re-tester.

1. Noter les commandes et timings pour que l'équipe reproduise les mêmes étapes de manière fiable.

Conclusion

Un dépannage HDFS efficace suit un motif prévisible : triage par lectures sûres, isolement du domaine fautif, diagnostics ciblés, puis correction au moindre risque pour traiter la cause racine. Démarrez par le plan pilote pour développer les bons réflexes d'équipe. Ensuite, gardez une courte checklist de commandes sûres, suivez les signatures de logs fréquentes dans votre environnement, et entraînez un scénario par sprint afin que les incidents deviennent routiniers à résoudre. Ce guide de HDFS troubleshooting vous aide à adresser rapidement HDFS errors, à interpréter les HDFS logs, à lancer les HDFS commands adéquates et à mener une HDFS recovery maîtrisée.