Erreurs courantes HDFS et correctifs : guide pratique de dépannage

Introduction

Lorsque le système de fichiers distribué Hadoop (HDFS) échoue, le message d'erreur n'est souvent qu'un point de départ. Les opérateurs ont besoin d'une méthode systématique pour passer d'un symptôme à une correction vérifiée sans aggraver la situation. Ce guide fournit un dépannage pratique et adapté à la version pour les erreurs HDFS courantes, en mettant l'accent sur l'observation sécuritaire, l'intervention minimale et la vérification.

Que vous soyez un développeur déboguant un job, un ingénieur DevOps gérant un cluster ou une équipe de start-up exécutant Hadoop pour la première fois, vous apprendrez à :

• Identifier la version et la topologie HDFS installées avant de modifier quoi que ce soit.
• Utiliser des commandes en lecture seule pour capturer l'état actuel et éviter les modifications accidentelles.
• Appliquer le correctif le plus minimal possible et vérifier le résultat avec une commande concrète.
• Récupérer après des modifications échouées en suivant des étapes de restauration testées.

Chaque section comprend des exemples de commandes avec des espaces réservés, des sorties attendues et des signaux d'échec. N'utilisez jamais de véritables identifiants ou identifiants de production dans un environnement de formation ou de documentation.

Inventaire de la version et de l'environnement

Avant de toucher à toute configuration, sachez exactement avec quoi vous travaillez. Le comportement de HDFS change selon les versions, et une commande qui fonctionne dans Hadoop 3.3 peut ne pas exister dans 2.7. La première étape consiste à collecter des informations sur la version et la topologie.

Commandes d'observation en lecture seule :

# Vérifier la version de Hadoop
hadoop version
# Sortie attendue : lignes incluant :
# Hadoop 3.3.4
# Source code repository ... -r 5854879e8a1ba80db1e8f1e630ba7d2f79fa1fd8

# Vérifier la version de HDFS spécifiquement
hdfs version

# Lister les DataNodes et leur statut (lecture seule)
hdfs dfsadmin -report
# Attendu : un rapport montrant les nœuds vivants et morts, la capacité et l'utilisation du pool de blocs.
# Signal d'échec : « No route to host » ou « Connection refused » si HDFS est arrêté.

Vérifier le répertoire de configuration :

# Localiser les fichiers de configuration Hadoop
ls $HADOOP_CONF_DIR
# Attendu : core-site.xml, hdfs-site.xml, yarn-site.xml, etc.

Prérequis :

• Accès SSH au NameNode et à au moins un DataNode.
• Variables d'environnement correctes (HADOOP_HOME, JAVA_HOME).
• Permission de lecture sur les fichiers de configuration.

Rayon d'impact : Toutes les commandes de cette section sont en lecture seule. Elles ne modifient pas l'état du système.

Vérification : Après avoir exécuté chaque commande, confirmez que vous avez reçu une sortie et aucune erreur. Enregistrez la version et la topologie dans votre runbook.

Récupération : Si les commandes échouent en raison de binaires manquants, vérifiez que $HADOOP_HOME/bin est dans votre PATH. Si la configuration est manquante, consultez vos scripts de provisionnement de cluster.

Chemin de configuration sécuritaire

Les modifications de configuration sont une cause fréquente d'erreurs HDFS. Une seule faute de frappe dans hdfs-site.xml peut empêcher le NameNode de démarrer. Suivez un chemin sécuritaire : sauvegarde, modification, validation, application, vérification.

Étape 1 : Sauvegarder la configuration actuelle

cp $HADOOP_CONF_DIR/hdfs-site.xml $HADOOP_CONF_DIR/hdfs-site.xml.bak.$(date +%Y%m%d)
# Attendu : aucune sortie en cas de succès.
# Vérifier : ls $HADOOP_CONF_DIR/hdfs-site.xml.bak.*

Étape 2 : Effectuer une modification minimale

Par exemple, pour augmenter le facteur de réplication de 3 à 4 (en supposant suffisamment de DataNodes) :

Modifiez hdfs-site.xml :

<property>
  <name>dfs.replication</name>
  <value>4</value>
</property>

Rayon d'impact : Cette modification n'affecte que les nouveaux fichiers. Les fichiers existants conservent leur ancienne réplication jusqu'à l'exécution d'une commande setrep.

Étape 3 : Valider la syntaxe XML

xmllint --noout $HADOOP_CONF_DIR/hdfs-site.xml
# Attendu : aucune sortie si valide.
# Échec : messages d'erreur indiquant un XML mal formé.

Étape 4 : Appliquer la modification

Les modifications de configuration nécessitent un redémarrage progressif pour les DataNodes et éventuellement un redémarrage du NameNode. Ne redémarrez jamais les deux simultanément dans un cluster de production.

Pour les DataNodes (redémarrage progressif) :

# Sur chaque hôte DataNode, un à la fois :
hdfs --daemon stop datanode
hdfs --daemon start datanode
# Vérifier que le nœud rejoint le cluster :
hdfs dfsadmin -report
# Recherchez le nœud dans la liste « Live datanodes ».

Pour le NameNode (si nécessaire) :

# Sur le NameNode actif :
hdfs --daemon stop namenode
hdfs --daemon start namenode
# Vérifier que le NameNode quitte le mode sans échec et devient actif :
hdfs dfsadmin -safemode get
# Attendu : « Safe mode is OFF »

Vérification :

# Vérifier le facteur de réplication effectif pour un nouveau fichier de test
hdfs dfs -mkdir /tmp/test-repl
hdfs dfs -put localfile /tmp/test-repl/
hdfs fsck /tmp/test-repl/localfile -files -blocks -locations
# Attendu : les blocs affichent un facteur de réplication de 4.

Récupération : Si le NameNode ne démarre pas, restaurez la sauvegarde :

cp $HADOOP_CONF_DIR/hdfs-site.xml.bak.$(date +%Y%m%d) $HADOOP_CONF_DIR/hdfs-site.xml

Puis redémarrez le NameNode.

Vérification et diagnostics

Une fois qu'une modification est effectuée, vous devez vérifier qu'elle a fonctionné. HDFS fournit plusieurs commandes de diagnostic.

Vérifier la santé du système de fichiers

hdfs fsck / -files -blocks -locations
# Sortie attendue : un rapport de tous les fichiers et blocs, se terminant par :
# « The filesystem under path '/' is HEALTHY »
# Échec : rapports de blocs corrompus ou manquants.

Vérifier la réplication des blocs

hdfs fsck /path/to/file -files -blocks -locations
# Attendu : pour chaque bloc, une liste des emplacements DataNode et le nombre de réplicas.
# Échec : « Under-replicated blocks » ou « Mis-replicated blocks ».

Vérifier le statut du NameNode

hdfs haadmin -getServiceState nn0
# Attendu : « active » ou « standby » (si la haute disponibilité est configurée).
# Échec : « Connection refused » si le NameNode est arrêté.

Vérifier les journaux

Les journaux sont la source la plus riche de diagnostics. Les emplacements varient, mais généralement :

# Journaux du NameNode
ls $HADOOP_LOG_DIR
# Recherchez namenode*.log ou hadoop-hdfs-namenode-*.log

# Suivre le dernier journal du NameNode
tail -f $HADOOP_LOG_DIR/hadoop-hdfs-namenode-$(hostname).log
# Signaux d'échec : lignes avec « FATAL », « ERROR » ou traces de pile.

Exemple de diagnostic : Vous observez que des fichiers sont sous-répliqués. Exécutez hdfs fsck / -files -blocks et recherchez des entrées comme :

/tmp/test/file.txt 1 blocks, 2 replicas (expected 3)

Cela indique que le facteur de réplication est défini sur 3, mais que seuls 2 réplicas existent. Causes possibles : un DataNode est arrêté, ou le cluster a été récemment étendu et un rééquilibrage est nécessaire.

Vérification : Après correction (par exemple, en ramenant le DataNode), exécutez à nouveau hdfs fsck / -files -blocks -locations et confirmez que le nombre de blocs sous-répliqués diminue.

Modes d'échec et récupération

Modes d'échec HDFS courants et comment s'en remettre.

1. Le NameNode ne démarre pas

Symptôme : hdfs --daemon start namenode se termine rapidement et les journaux affichent des erreurs.

Causes possibles :

• Journaux d'édition ou fsimage corrompus.
• Erreurs de configuration (mauvais port, XML invalide).
• Espace disque insuffisant pour les métadonnées.

Étapes de diagnostic :

# Vérifier le journal pour une exception spécifique
grep -i 'error\|exception' $HADOOP_LOG_DIR/hadoop-hdfs-namenode-*.log | tail -20
# Vérifier l'espace disque sur les répertoires de métadonnées du NameNode
df -h /path/to/namenode/dir

Options de récupération :

• Si erreur de configuration : corrigez le XML et redémarrez.
• Si corruption des métadonnées : envisagez d'utiliser le point de contrôle du SecondaryNameNode ou une sauvegarde récente de fsimage. Les détails dépendent de votre stratégie de sauvegarde.
• Si disque plein : libérez de l'espace et redémarrez.

2. Le DataNode ne parvient pas à s'enregistrer auprès du NameNode

Symptôme : Le processus DataNode s'exécute mais n'apparaît pas dans les nœuds vivants de hdfs dfsadmin -report.

Causes possibles :

• Partition réseau ou pare-feu bloquant le port du DataNode (par défaut 9866).
• Le DataNode a un identifiant de cluster différent de celui du NameNode.
• Le répertoire dfs.datanode.data.dir configuré pour le DataNode est inaccessible.

Diagnostic :

# Sur le DataNode, vérifier le journal pour les erreurs d'enregistrement
grep -i 'register\|error' $HADOOP_LOG_DIR/hadoop-hdfs-datanode-*.log | tail -20
# Vérifier la connectivité du DataNode au NameNode sur le port IPC (par défaut 8020)
telnet namenode-host 8020

Récupération :

• Corrigez le réseau/pare-feu.
• En cas de discordance d'identifiant de cluster : localisez le fichier VERSION dans le répertoire de données et mettez à jour l'identifiant de cluster pour qu'il corresponde à celui du NameNode, ou désaffectez le nœud et effacez ses données.
• Assurez-vous que les permissions du répertoire de données sont correctes.

3. Blocs sous-répliqués

Symptôme : hdfs fsck / signale des blocs sous-répliqués.

Causes possibles :

• DataNode(s) arrêté(s).
• Facteur de réplication augmenté mais pas encore appliqué.
• Défaillances de disque sur les DataNodes.

Diagnostic :

hdfs fsck / -files -blocks -locations | grep -i 'under-replicated'
# Attendu : liste des fichiers et blocs affectés.

Récupération :

• Ramenez le DataNode en ligne. HDFS répliquera automatiquement si possible.
• Si le DataNode ne peut pas être récupéré, désaffectez-le correctement :

# Ajoutez le nœud à dfs.hosts.exclude, puis actualisez les nœuds
hdfs dfsadmin -refreshNodes
# Surveillez le statut de désaffectation
hdfs dfsadmin -report

• En cas de défaillance de disque, remplacez le disque et redémarrez le DataNode ; les données seront répliquées à partir d'autres réplicas.

4. Mode sans échec bloqué sur ON

Symptôme : Le NameNode reste en mode sans échec plus longtemps que prévu, bloquant les écritures.

Diagnostic :

hdfs dfsadmin -safemode get
# Si « ON », vérifiez la raison
hdfs dfsadmin -safemode enter
# En fait, vérifiez simplement le statut et le journal. Les journaux peuvent montrer pourquoi le mode sans échec est prolongé.

Récupération :

• Si suffisamment de DataNodes ont signalé, vous pouvez quitter manuellement le mode sans échec :

hdfs dfsadmin -safemode leave

• Mais vérifiez d'abord les blocs manquants ou les nœuds morts ; le mode sans échec peut protéger les données.

Liste de contrôle des opérations

Utilisez cette liste de contrôle pour tout processus de dépannage ou de modification HDFS. Attribuez un responsable pour chaque élément et une fréquence de révision.

Propriété des décisions : Pour les modifications majeures de configuration HDFS, le propriétaire désigné est le responsable d'ingénierie (par exemple, Priya Shah). Pour les modifications opérationnelles de routine, l'ingénieur DevOps de garde peut procéder avec une revue par les pairs. Le plan de gestion de la configuration est révisé trimestriellement pour intégrer les nouvelles versions de HDFS et les apprentissages opérationnels.

Pièges courants et comment les éviter

1. Modifier la configuration sans sauvegarde

Pourquoi cela arrive : Sous la pression du temps, les opérateurs modifient directement hdfs-site.xml. Comment éviter : Utilisez toujours un système de contrôle de version pour les configurations ou au moins créez une sauvegarde horodatée avant de modifier. Récupération : Si une modification casse quelque chose, restaurez la sauvegarde et redémarrez le service affecté.

2. Redémarrer plusieurs nœuds simultanément

Pourquoi cela arrive : Mécompréhension des exigences de redémarrage progressif ou précipitation pendant une fenêtre de maintenance. Comment éviter : Utilisez des procédures de redémarrage progressif, un DataNode à la fois. Pour le NameNode, assurez-vous que la haute disponibilité est configurée avant de redémarrer le nœud actif. Récupération : Si trop de DataNodes sont arrêtés, HDFS peut entrer en mode sans échec. Attendez que les nœuds se rejoignent ou ajustez manuellement la réplication.

3. Ignorer le mode sans échec comme symptôme

Pourquoi cela arrive : Traiter le mode sans échec comme une nuisance et forcer la sortie sans vérifier l'état des blocs. Comment éviter : Enquêtez sur la raison du mode sans échec : exécutez hdfs fsck / et vérifiez les rapports des DataNodes avant de quitter le mode sans échec. Récupération : Si le mode sans échec est quitté prématurément et que des données sont perdues, restaurez à partir d'une sauvegarde ou augmentez temporairement le facteur de réplication.

4. Ne pas vérifier après les modifications

Pourquoi cela arrive : Supposer que la commande a réussi car elle n'a renvoyé aucune erreur. Comment éviter : Exécutez toujours une commande de vérification, comme vérifier l'accessibilité d'un fichier ou hdfs dfsadmin -report, après toute modification. Récupération : Si la vérification échoue, annulez la modification en utilisant votre sauvegarde ou votre procédure de retour en arrière.

5. Utiliser de mauvais noms ou numéros de port

Pourquoi cela arrive : Les ports HDFS ont changé selon les versions (par exemple, le port IPC du DataNode est passé de 50020 à 9866). Comment éviter : Consultez la documentation officielle pour votre version spécifique de Hadoop. Récupération : Mettez à jour les règles de pare-feu ou la configuration pour correspondre aux ports corrects.

Conclusion

Un dépannage HDFS efficace est une discipline : observer, modifier de manière minimale, vérifier et documenter. Les commandes et procédures de ce guide vous donnent une base, mais adaptez-les toujours à la version et à la configuration spécifiques de votre cluster.

Commencez par un diagnostic à faible risque, comme hdfs fsck / ou hdfs dfsadmin -report, pour comprendre la santé de votre cluster. Enregistrez l'état actuel avant d'apporter toute modification et ayez toujours un chemin de récupération testé prêt. En suivant ces pratiques, vous pouvez réduire les temps d'arrêt et empêcher que de petits problèmes ne deviennent des pannes à l'échelle du cluster.