Dépannage HDFS avec exemples pratiques : un runbook pour les opérateurs

Ce guide propose un runbook pratique, copiable‑collable, pour diagnostiquer et corriger les problèmes courants de HDFS (Hadoop Distributed File System) : système de fichiers distribué Hadoop. Il s’adresse aux développeurs, ingénieurs DevOps et équipes de plateforme qui exploitent des lacs de données ou des clusters analytiques basés sur Hadoop. Suivez le flux de travail, exécutez d’abord les commandes sans risque et utilisez le plan de pilote pour répéter les étapes sur un cluster de test avant d’en avoir besoin en production.

Vue d’ensemble du flux de travail

Utilisez ce flux lors des incidents :

1. Triage rapide pour capturer l’état sans le modifier.
2. Identifier le domaine de défaillance : client, NameNode, DataNode, réseau, authentification ou système de fichiers.
3. Lancer les diagnostics ciblés pour ce domaine.
4. Appliquer d’abord la correction à risque minimal et vérifier.
5. Escalader vers des étapes de récupération plus profondes seulement si nécessaire.
6. Enregistrer les commandes et leurs résultats afin de pouvoir les rejouer ou les annuler.

Triage rapide

Commencez par des vérifications non destructives.

• Vérifier les processus :

jps

• Inspecter l’état du cluster :

hdfs dfsadmin -report

• Rechercher les problèmes de blocs :

hdfs fsck / -blocks -locations -racks -openforwrite

• Lister les opérations récentes dans un chemin :

hdfs dfs -ls -R /chemin-interesse | tail -n 50

• Suivre les journaux :

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 de redémarrer quoi que ce soit. Enregistrez la sortie de hdfs dfsadmin -report et de hdfs fsck / -blocks -locations -racks -openforwrite avant tout redémarrage de service.

Problèmes NameNode

Symptômes :

• Les clients se bloquent sur les opérations de liste ou de création.
• L’interface Web est indisponible ou affiche le mode sans échec (Safe Mode).
• Exceptions comme org.apache.hadoop.hdfs.server.namenode.SafeModeException: Cannot create file ... Name node is in safe mode.

Procédure pas à pas :

1. Vérifier le mode sans échec :

hdfs dfsadmin -safemode get

Si ON car moins de dfs.namenode.replication.min blocs sont répliqués, lancez d’abord :

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

pour voir les fichiers concernés, puis corrigez la santé des blocs (voir section réplication) et exécutez :

hdfs dfsadmin -safemode leave

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

jps

netstat -plnt | grep -E '8020|50070|9870'

Port RPC NameNode typique 8020, interface HTTP 9870 (ou 50070 sur versions anciennes). Si un port est occupé, arrêtez le processus conflit ou changez l’adresse de liaison.

1. Contrôler l’espace disque sur les répertoires de métadonnées NameNode (fsimage, edits) :

df -h

Assurez‑vous qu’il reste de la place ; évitez que les disques de métadonnées atteignent 100 %.

Recherchez les erreurs de connectivité JournalNode, les éditions partagées échouées ou java.io.IOException: No space left on device.

1. Examiner les journaux NameNode :

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

1. Si le NameNode ne démarre pas :

Ne lancez jamais hdfs namenode -format sur un répertoire de métadonnées actif ; cela efface l’espace de noms.

1. Ne formatez jamais les métadonnées de production :

Vérifiez chaque processus JournalNode avec :

1. Si vous utilisez des JournalNodes :

jps | grep JournalNode

et confirmez que le port 8485 écoute.

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

hdfs dfsadmin -report

Ouvrez l’interface Web NameNode à http://namenode:9870 et confirmez les DataNodes vivants et le nombre de blocs sains.

DataNode et réplication

Symptômes :

• Lectures/écritures lentes limitées à certains hôtes.
• Blocs UNDER_REPLICATED ou MISSING.
• Journaux DataNode affichant Volume failed ou erreurs d’E/S disque.

Flux de récupération :

1. Vue d’ensemble du cluster :

hdfs dfsadmin -report

Affiche l’état Live/Dead, décommissionnement et capacité.

1. Identifier les blocs défectueux :

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/critique

L’option -w bloque jusqu’à l’atteinte du facteur de réplication cible.

Vérifiez la connectivité avec :

1. Si de nombreux nœuds sont morts :

nc -vz datanode-host 50010

et inspectez les journaux DataNode pour java.io.IOException: No space left on device.

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

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

Mettez à jour le fichier d’exclusion (dfs.hosts.exclude), puis lancez :

1. Décommissionnement bloqué :

hdfs dfsadmin -refreshNodes

Assurez‑vous que le cluster peut encore respecter le facteur de réplication avant le retrait complet du nœud.

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

hdfs balancer -threshold 10

Surveillez avec hdfs balancer -threshold 10 2>&1 | tail -f ; mettez en pause avec hdfs balancer -threshold 10 -pause si la latence des jobs augmente.

1. Confirmer la santé des blocs :

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

Une sortie propre signifie qu’aucun bloc sous‑répliqué ne subsiste.

Disque et permissions

Un disque plein ou des problèmes de permissions provoquent souvent des défaillances en cascade.

Espace disque (niveau OS)

• df -h sur NameNode et DataNodes.
• du -sh /hadoop/dfs/* pour repérer les gros répertoires.
• Rotater ou compresser les gros journaux. Exemple : libérer de l’espace sur un volume DataNode plein :

logrotate -f /etc/logrotate.d/hadoop

gzip /var/log/hadoop/hdfs/audit.log.*

• Les journaux DataNode peuvent indiquer No space left on device ou trop de volumes en échec. Libérez de l’espace, ajoutez de la capacité ou ajustez dfs.datanode.failed.volumes.tolerated avec précaution.

Utilisation HDFS et quotas

• hdfs dfs -du -h -s /projets/equipeX
• hdfs dfs -count -q -h /projets/equipeX
• Définir un quota sur un répertoire de projet :

hdfs dfsadmin -setQuota 1000000 /projets/equipeX

hdfs dfsadmin -setSpaceQuota 500g /projets/equipeX

• Nettoyage de la corbeille quand c’est sûr : hdfs dfs -expunge
• Envisagez fs.trash.interval pour un comportement automatique de la corbeille.

Permissions

• Inspecter et corriger :

hdfs dfs -ls -R /chemin

hdfs dfs -chown -R utilisateur:groupe /chemin

hdfs dfs -chmod -R 755 /chemin

• Pour les répertoires temporaires partagés, utilisez le sticky bit :

hdfs dfs -chmod 1777 /tmp

• Assurez‑vous 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 entraînent délais d’attente, nœuds morts et clients instables.

1. DNS et accessibilité :

getent hosts namenode.example.com

ping -c 3 namenode.example.com

Vérifiez que le DNS inverse résout le même FQDN.

1. Ports requis :

nc -vz namenode 8020

nc -vz datanode 50010

Vérifiez aussi 50070 ou 9870 (HTTP/HTTPS), et 9864 ou 50075 (Web DataNode). Ouvrez les pare‑feu en conséquence.

Recherchez CallTimeoutException dans les journaux client. Si le délai par défaut de 60 secondes est trop court, augmentez le timeout socket dans hdfs-site.xml :

1. Délais client :

<property>
  <name>dfs.client.socket-timeout</name>
  <value>120000</value>
</property>

Pensez aussi à régler ipc.client.connect.max.retries pour les liaisons instables.

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

1. Adresse NameNode correcte :

Confirmez que le script de topologie (/etc/hadoop/conf/topology.sh) est exécutable sur chaque nœud et renvoie le même nom de rack pour un hôte donné.

1. Connaissance des racks :

Authentification Kerberos

Les échecs d’authentification se manifestent par des 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/[email protected]

Vérifier :

klist -e

Exécutez chronyc tracking ou ntpstat sur chaque nœud ; le décalage System time doit être < 5 secondes.

1. Corriger le décalage d’horloge :

Les configs de service utilisent souvent _HOST, ex. hdfs/_HOST@REALM. Assurez‑vous que les keytabs correspondent au FQDN de l’hôte :

1. Valider les principaux et keytabs :

klist -kt /etc/security/keytabs/hdfs.headless.keytab | grep hdfs/

hadoop.security.authentication défini sur kerberos dans core-site.xml. Fichiers JAAS (Java Authentication and Authorization Service) : service d'authentification et d'autorisation Java et keytabs lisibles par l’utilisateur de service.

1. Confirmer les réglages Kerberos :

Si un seul DataNode échoue à l’authentification, régénérez son keytab, redémarrez uniquement le DataNode :

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

systemctl restart hadoop-hdfs-datanode

puis testez à nouveau avec :

hdfs dfs -ls /

Commandes sûres

Commandes en lecture seule ou à faible risque à privilégier au début :

État du cluster

hdfs dfsadmin -report

hdfs fsck / -blocks -locations -racks -openforwrite

Fichiers et quotas

hdfs dfs -ls -R /chemin

hdfs dfs -du -h -s /chemin

hdfs dfs -count -q -h /chemin

Processus et ports

jps

netstat -plnt | grep -E '8020|50010|50070|9870|9864|8485'

ss -lptn

Journaux

tail -F $HADOOP_LOG_DIR/hdfs/*

grep -Ei 'ERROR|FATAL|SASL|Under replicated|SafeMode' $HADOOP_LOG_DIR/hdfs/*.log

Réseau

getent hosts hote

nslookup hote

nc -vz hote port

curl -I http://namenode:9870/

Kerberos

klist

kinit -R

kvno hdfs/hote@REALM

Plan de pilote local

Validez 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 chemins de récupération (sortie du mode sans échec et correction de sous‑réplication).

1. Santé de référence :

hdfs dfsadmin -report

hdfs fsck / -blocks

Dans un environnement de test, provoquez le mode sans échec en arrêtant temporairement un DataNode de test :

1. Exercice mode sans échec :

systemctl stop hadoop-hdfs-datanode

Observez hdfs dfsadmin -safemode get et les journaux NameNode pour SafeModeException. Redémarrez le DataNode et quittez le mode sans échec :

hdfs dfsadmin -safemode leave

Créez un fichier test de 10 Mo :

1. Exercice sous‑réplication :

dd if=/dev/zero of=testfile bs=1M count=10

hdfs dfs -put testfile /tmp/

Définissez le facteur de réplication à 3 et attendez :

hdfs dfs -setrep -w 3 /tmp/testfile

Vérifiez avec :

hdfs fsck /tmp/testfile -blocks -locations

1. Exercice Kerberos (si activé) :

kinit -kt /etc/security/keytabs/hdfs.headless.keytab hdfs/[email protected]

klist

Faites expirer le TGT (kdestroy) ou attendez son expiration ; observez les échecs ; renouvelez et testez à nouveau.

1. Enregistrez les commandes et leurs durées pour que l’équipe puisse rejouer les mêmes étapes de manière cohérente.

Conclusion

Un dépannage HDFS efficace suit un schéma prévisible : triage par lectures sûres, isolation du domaine défaillant, diagnostics ciblés et utilisation de la récupération à risque minimal qui traite la cause racine. Commencez par le plan de pilote pour ancrer les réflexes de l’équipe. Comme prochaines étapes, conservez une check‑liste courte des commandes sûres, suivez les signatures de journaux fréquentes de votre environnement et entraînez‑vous sur un scénario par sprint afin que les incidents deviennent routiniers à résoudre.