## Introduction Le système de fichiers distribués Hadoop (HDFS) est au cœur de nombreuses plateformes de données à grande échelle, mais sa configuration reste une source fréquente d'incidents. Un seul paramètre erroné peut dégrader silencieusement les performances, causer une perte de données ou mettre hors service un cluster complet. Ce guide s'adresse aux développeurs, consultants DevOps et équipes techniques de startups qui doivent passer d'un problème à une correction vérifiée sans conjectures. Nous nous concentrons sur des opérations pratiques et liées à la version. Chaque section associe une erreur à son symptôme observable, à une modification minimale et à une commande de vérification. L'objectif est la sécurité opérationnelle : observer avant de modifier, limiter le rayon d'impact, utiliser des espaces réservés plutôt que des secrets, vérifier les résultats et documenter la récupération. Vous ne devez jamais appliquer une modification sans savoir détecter un échec et revenir en arrière. Cet article suppose un cluster HDFS en état de marche. Nous utilisons la syntaxe des commandes de Hadoop 3.3.x, mais signalons les différences lorsque cela est pertinent. Confirmez toujours votre version installée avec hdfs version avant de continuer. ## Inventaire de la version et de l'environnement Avant de toucher à la moindre configuration, établissez un inventaire précis de votre environnement. Le comportement de HDFS diffère selon les versions, et un paramètre qui fonctionne sous Hadoop 2.x peut être déprécié ou renommé sous Hadoop 3.x. Commencez par des commandes en lecture seule pour capturer l'état actuel. ### Identifier la version de HDFS et la topologie de déploiement Exécutez la commande suivante sur un hôte NameNode : hdfs version La sortie attendue inclut : Hadoop 3.3.4 Source code repository https://github.com/apache/hadoop -r a585a73c3e02ac62350c136643a5e7f6095a3dbb Compiled by ubuntu on 2023-06-14T17:48Z Compiled with protoc 3.7.1 From source with checksum 5a1a9c42a5f5f5f5f5f5f5f5f5f5f5f5 Notez la version de Hadoop et la version de Java utilisée par le cluster : java -version La compatibilité Java est critique : Hadoop 3.3.x nécessite Java 8 ou 11 (selon la compilation). L'exécution sous Java 17 peut provoquer des erreurs inattendues. Consultez la documentation du fournisseur de votre distribution (par exemple, Cloudera, Hortonworks, Apache vanilla) pour leur matrice de support. Listez les rôles et leurs hôtes à l'aide de votre gestionnaire de cluster ou de la commande hdfs dfsadmin -report : hdfs dfsadmin -report Cela affiche les DataNodes actifs et inactifs, la capacité et les informations sur les blocs. Notez la topologie, comme la configuration de la sensibilisation aux racks, et si la haute disponibilité (HA) avec plusieurs NameNodes est activée. ### Capturer l'état actuel de la configuration Ne supposez pas que les fichiers de configuration sur disque correspondent aux démons en cours d'exécution. Un démon peut avoir été démarré avec des options de ligne de commande ou des variables d'environnement. Pour voir ce qu'un démon actif a réellement utilisé au démarrage, consultez l'environnement de son processus ou ses journaux. Pour un NameNode, vous pouvez lister la configuration effective pour une clé spécifique à l'aide de hdfs getconf : hdfs getconf -confKey dfs.replication Cela renvoie la valeur issue de la configuration chargée. Comparez-la avec la valeur dans hdfs-site.xml . Toute divergence indique une option de démarrage ou un classpath mal configuré. Pour une vue complète, videz toutes les propriétés de configuration et leurs sources : hdfs getconf -confKey Mais cela inclut les valeurs par défaut. Concentrez-vous plutôt sur les propriétés que vous comptez modifier et leurs valeurs actuelles avant l'édition. ### Prérequis pour une observation sûre - Accès SSH aux hôtes NameNode et DataNode avec les autorisations appropriées. - Accès en lecture au répertoire de configuration Hadoop, souvent /etc/hadoop/conf . - L'utilisateur hdfs doit pouvoir exécuter des commandes en lecture seule sans demander d'informations d'identification (ticket Kerberos ou authentification simple). - Synchronisation horaire entre les nœuds (NTP) pour corréler les horodatages des journaux. ### Exemple : Vérification du facteur de réplication Supposons que vous vouliez vérifier le facteur de réplication par défaut actuel. Exécutez : hdfs getconf -confKey dfs.replication Si la sortie est 3 , mais que vos SLA exigent 2 pour réduire les coûts, notez que sa modification n'affecte que les nouveaux fichiers. Les fichiers existants conservent leur ancien facteur de réplication à moins que vous ne le définissiez explicitement avec hdfs dfs -setrep . Définissez maintenant le résultat attendu et le signal d'échec avant toute modification. Pour un changement planifié, écrivez : - Modification : Définir dfs.replication sur 2 dans hdfs-site.xml . - Résultat attendu : Les nouveaux fichiers créés auront une réplication de 2. - Signal d'échec : hdfs dfs -ls /newfile affiche une réplication de 3, ou hdfs fsck / -files -blocks -locations montre des blocs sous-répliqués. - Récupération : Annulez la modification et redémarrez les démons affectés, ou utilisez hdfs dfs -setrep 3 /path pour les fichiers existants. Utilisez toujours des espaces réservés pour les chemins et les informations d'identification ; n'incluez jamais de vrais identifiants de production dans la documentation. ## Chemin de configuration sûr Une fois l'inventaire établi, appliquez les modifications via un chemin contrôlé. Les erreurs de configuration HDFS surviennent souvent parce que quelqu'un modifie un fichier sur un nœud mais pas sur les autres, ou applique un changement sans vérifier d'abord la santé du cluster. ### Le principe du plus petit changement justifié Chaque modification doit avoir une raison liée à des observables. Si vous ne pouvez pas mesurer l'amélioration ou la correction, ne faites pas le changement. Par exemple, augmenter dfs.namenode.handler.count de la valeur par défaut 10 à 20 peut aider si vous constatez des temps de file d'attente RPC élevés, mais consomme plus de mémoire. Le changement n'est justifié que si vous observez le symptôme et pouvez en vérifier l'effet. Utilisez un outil de gestion de configuration (Ansible, Puppet, Chef) pour pousser les modifications de manière cohérente sur tous les nœuds. Si vous modifiez manuellement, utilisez un script pour comparer les fichiers : diff /etc/hadoop/conf/hdfs-site.xml /path/to/backup/hdfs-site.xml ### Procédure de modification documentée - Sauvegardez les fichiers de configuration actuels. cp /etc/hadoop/conf/hdfs-site.xml /etc/hadoop/conf/hdfs-site.xml.$(date +%Y%m%d%H%M%S) - Modifiez la configuration sur tous les nœuds concernés (NameNode et DataNodes). Par exemple, pour changer dfs.blocksize de 128 Mo à 256 Mo : dfs.blocksize 268435456 Taille de bloc en octets (256 Mo). - Validez la syntaxe XML avant le redémarrage : xmllint --noout /etc/hadoop/conf/hdfs-site.xml - Redémarrez les démons affectés dans le bon ordre. Pour les clusters non-HA, redémarrez d'abord les DataNodes (redémarrage progressif) ou tous en même temps si la fenêtre de maintenance le permet. Pour la haute disponibilité, utilisez un redémarrage progressif pour éviter les temps d'arrêt : hdfs haadmin -failover nn1 nn2 # redémarrer nn1 hdfs haadmin -failover nn2 nn1 # redémarrer nn2 - Vérifiez que la nouvelle configuration a pris effet : hdfs getconf -confKey dfs.blocksize Sortie attendue : 268435456 ou 256m selon le formatage. - Vérifiez la santé du cluster après le redémarrage : hdfs dfsadmin -report Tous les DataNodes doivent apparaître comme actifs sans blocs manquants. ### Considérations sur le rayon d'impact Une modification du NameNode affecte l'ensemble de l'espace de noms et les opérations de métadonnées. Une modification d'un DataNode n'affecte que le stockage et le service de blocs de ce nœud. Une modification d'une configuration côté client (par exemple, dfs.client.read.shortcircuit ) n'affecte que les performances de ce client, pas la stabilité du cluster. Par exemple, l'activation des lectures en court-circuit avec dfs.client.read.shortcircuit et dfs.domain.socket.path nécessite que le DataNode dispose d'un socket de domaine Unix. Si le socket ne peut pas être créé, les lectures échouent. Testez sur un seul client avant de déployer sur tous. ### Chemin de retour en arrière Avant tout changement, notez les commandes exactes pour revenir en arrière. Pour les modifications de configuration, cela signifie généralement restaurer le fichier de sauvegarde et redémarrer les démons. Mais parfois, un changement a des effets secondaires persistants (par exemple, changer dfs.namenode.name.dir vers un nouveau répertoire initie une opération similaire à un formatage si ce n'est pas fait avec soin). Dans ce cas, vous devrez peut-être restaurer à partir d'un instantané du système de fichiers ou utiliser la fonction de retour en arrière du NameNode. HDFS prend en charge le retour en arrière d'une mise à niveau du NameNode, mais pas les modifications arbitraires de configuration. Le retour en arrière le plus sûr est donc une restauration complète de la configuration suivie d'un redémarrage propre. ### Exemple : Modification de la taille de bloc Problème : De nombreux petits fichiers de moins de 128 Mo entraînent une surcharge de métadonnées élevée. Vous décidez d'augmenter la taille de bloc à 256 Mo pour réduire l'utilisation de la mémoire du NameNode. Prérequis : Confirmez que la version du cluster prend en charge les blocs de 256 Mo (toutes les versions le font). Vérifiez l'utilisation actuelle de la mémoire du NameNode avec jstat -gcutil 1000 . Modification : Mettez à jour dfs.blocksize comme ci-dessus. Rayon d'impact : N'affecte que les nouveaux fichiers. Les fichiers existants conservent leur taille de bloc. Pas de temps d'arrêt si un redémarrage progressif est utilisé. Vérification : hdfs dfs -mkdir /testblocksize hdfs dfs -Ddfs.blocksize=268435456 -put localfile /testblocksize/ hdfs fsck /testblocksize/localfile -files -blocks La sortie attendue montre une taille de bloc de 268435456. Récupération : Annulez la configuration et redémarrez. Supprimez le fichier de test. ## Vérification et diagnostic Après avoir appliqué une modification de configuration, vous devez vérifier non seulement que la valeur est définie, mais aussi que le comportement prévu se produit et qu'aucun effet secondaire indésirable n'apparaît. C'est là que de nombreuses équipes d'exploitation échouent : elles vérifient le fichier de configuration mais pas le comportement réel. ### Commandes de diagnostic en lecture seule Ces commandes ne modifient pas l'état et peuvent être exécutées à tout moment en toute sécurité : - hdfs dfsadmin -report – état du cluster, vivacité des nœuds, capacité. - hdfs fsck / -files -blocks -locations – vérification du système de fichiers (lecture seule). - hdfs dfs -ls / – liste de base. - hdfs dfs -cat /path – lire un petit fichier pour tester le chemin de lecture. - hdfs dfs -du /path – utilisation du disque. - hdfs dfs -stat %r /path – facteur de réplication d'un fichier. - hdfs getconf -confKey – valeur effective d'une propriété. - hdfs dfsadmin -printTopology – topologie des racks. ### Vérification ciblée par sous-système Si vous avez modifié un paramètre du NameNode comme dfs.namenode.handler.count , vous devez surveiller la file d'attente RPC et les temps de traitement. Utilisez le point de terminaison des métriques du NameNode ou hdfs dfsadmin -safemode get pour vérifier s'il est entré inopinément en mode sans échec. Si vous avez modifié un paramètre du DataNode comme dfs.datanode.max.transfer.threads , observez les journaux du DataNode et l'utilisation du réseau. Si vous avez modifié un paramètre client comme dfs.client.read.shortcircuit , exécutez un benchmark sur un client représentatif pour confirmer l'amélioration des performances et l'absence d'erreurs. ### Exemple : Vérification d'une modification de dfs.replication Scénario : Vous avez changé la réplication par défaut de 3 à 2 pour économiser de l'espace. Pour vérifier, procédez comme suit : - Créez un fichier de test : hdfs dfs -put /etc/hosts /testrep - Vérifiez son facteur de réplication : hdfs dfs -stat %r /testrep Sortie attendue : 2 . Si elle affiche 3 , la modification n'a pas pris effet ou le fichier a été créé avant le changement. - Vérifiez les emplacements des blocs pour vous assurer qu'il y a deux copies sur des racks différents (si la sensibilisation aux racks est configurée) : hdfs fsck /testrep -files -blocks -locations Recherchez deux emplacements de blocs avec des identifiants de rack différents. - Supprimez le fichier de test : hdfs dfs -rm /testrep Si la vérification échoue, annulez immédiatement la modification de configuration et redémarrez les services affectés. Diagnostiquez ensuite pourquoi le changement ne s'est pas appliqué (par exemple, nom de propriété incorrect, redémarrage du NameNode incomplet ou problème de synchronisation de la configuration). ## Modes de défaillance et récupération Même avec une gestion prudente des modifications, des défaillances surviennent. Voici les erreurs de configuration HDFS courantes, leurs symptômes observables et les étapes de récupération. ### Erreur 1 : Ne pas définir dfs.namenode.name.dir sur plusieurs répertoires Pourquoi cela arrive : Les administrateurs configurent parfois un seul répertoire pour les métadonnées du NameNode afin d'économiser de l'espace disque, ignorant la recommandation d'avoir au moins deux répertoires sur des disques physiques séparés pour la redondance. Symptôme : Si le disque unique tombe en panne, tout l'espace de noms est perdu. Aucun basculement automatique sans HA. Comment éviter : Configurez toujours au moins deux répertoires locaux sur des disques différents, et configurez également un point de montage NFS distant pour plus de sécurité (avec des réserves sur les performances). Récupération : Si vous avez un NameNode secondaire, vous pouvez récupérer les métadonnées à partir de son point de contrôle si dfs.namenode.secondary.http-address est configuré. Sinon, vous devez restaurer à partir de la sauvegarde. Pour prévenir, mettez en place une sauvegarde régulière du répertoire de métadonnées du NameNode. ### Erreur 2 : Mauvaise configuration de dfs.datanode.data.dir avec des chemins séparés par des virgules sans vérifier les montages disque Pourquoi cela arrive : Les opérateurs listent plusieurs répertoires mais ne vérifient pas que chaque chemin correspond à un système de fichiers monté. Si un chemin se trouve sur le système de fichiers racine au lieu du disque de données prévu, le DataNode peut remplir la partition racine. Symptôme : Le DataNode échoue avec « Espace disque plein » même si les disques de données ont de l'espace ; la partition racine se remplit, pouvant faire planter le système d'exploitation. Comment éviter : Avant d'ajouter des répertoires, vérifiez les points de montage : df -h /path/to/dir Assurez-vous que chaque répertoire se trouve sur un volume physique distinct et a une capacité suffisante. Récupération : Arrêtez le DataNode, supprimez le répertoire mal configuré de dfs.datanode.data.dir , nettoyez les données écrites au mauvais endroit, puis redémarrez. Surveillez également l'espace de la partition racine. ### Erreur 3 : Modifier dfs.blocksize sans tenir compte de la distribution des tailles de fichiers Pourquoi cela arrive : Une équipe veut réduire la mémoire du NameNode en utilisant des blocs plus grands, espérant que moins de blocs signifient moins de métadonnées. Mais si la charge de travail consiste en de nombreux petits fichiers, les blocs sont toujours alloués par fichier, et la surcharge de réplication peut augmenter. Symptôme : Aucune réduction de la mémoire du NameNode ; possible augmentation de l'utilisation du stockage en raison de l'allocation partielle de blocs pour les petits fichiers. Comment éviter : Analysez la distribution des tailles de fichiers avant de modifier la taille de bloc. Utilisez : hdfs fsck / -files -blocks | awk '{print $1}' | sort | uniq -c | head Si la plupart des fichiers sont plus petits que la nouvelle taille de bloc, le changement n'aidera pas et peut gaspiller de l'espace. Envisagez plutôt la compaction ou l'utilisation d'un format de stockage différent (par exemple, ORC, Parquet) qui regroupe les petits fichiers dans des fichiers plus grands. Récupération : Si déjà modifié, vous pouvez revenir sur le paramètre, mais les fichiers existants restent à la nouvelle taille de bloc. Pour les rétablir, vous devrez les réécrire (par exemple, les copier vers un emplacement temporaire avec l'ancienne taille de bloc puis les remplacer). ### Erreur 4 : Définir incorrectement dfs.namenode.safemode.threshold-pct Pourquoi cela arrive : Un administrateur veut accélérer le démarrage en abaissant le seuil (par défaut 0.999f signifie que le NameNode sort du mode sans échec lorsque 99,9 % des blocs sont signalés). Le définir trop bas, par exemple 0,5, fait sortir le NameNode du mode sans échec avant que tous les blocs ne soient signalés, entraînant une sous-réplication et une perte de données potentielle. Symptôme : Après le redémarrage, le cluster semble sain mais de nombreux fichiers sont sous-répliqués. hdfs dfsadmin -report montre des blocs manquants ; hdfs fsck / signale des blocs sous-répliqués. Comment éviter : Gardez la valeur par défaut ou augmentez-la pour plus de sécurité. Si vous devez la baisser, faites-le temporairement et surveillez les rapports de blocs. Récupération : Remettez le seuil à la valeur par défaut et redémarrez le NameNode. Exécutez ensuite hdfs fsck / -files -blocks -locations pour identifier les blocs sous-répliqués et laissez le système les répliquer automatiquement. Vous pouvez également déclencher manuellement la réplication avec hdfs dfs -setrep -R 3 /path . ### Erreur 5 : Mauvaise configuration du script de sensibilisation aux racks Pourquoi cela arrive : Le script spécifié dans net.topology.script.file.name n'est pas exécutable ou renvoie une erreur. Par conséquent, tous les nœuds se voient attribuer le rack par défaut /default-rack , ce qui signifie que HDFS ne peut pas répartir les répliques entre les racks, perdant la tolérance aux pannes. Symptôme : hdfs dfsadmin -printTopology montre tous les nœuds sous /default-rack . Si un rack tombe en panne, des données peuvent être perdues car toutes les répliques sont dans le même rack. Comment éviter : Testez le script manuellement avec des adresses IP d'exemple et assurez-vous qu'il renvoie un chemin de rack valide. Définissez des autorisations appropriées ( chmod 755 ). Récupération : Corrigez le script et redémarrez le NameNode. La topologie sera mise à jour. Pour rééquilibrer les répliques entre les racks, utilisez le Balancer avec l'option -policy ou attendez la réplication naturelle basée sur la nouvelle topologie. ### Erreur 6 : Ne pas activer dfs.namenode.acls.enabled lors de l'utilisation des ACL Pourquoi cela arrive : Un développeur essaie d'utiliser les ACL avec hdfs dfs -setfacl mais le paramètre est faux, donc la commande échoue silencieusement ou les ACL sont ignorées. Symptôme : Les utilisateurs ne peuvent pas accéder aux fichiers auxquels ils devraient avoir droit ; hdfs dfs -getfacl ne montre aucune ACL étendue. Comment éviter : Avant d'activer les ACL, vérifiez qu'elles sont prises en charge et définissez dfs.namenode.acls.enabled sur true dans hdfs-site.xml , puis redémarrez le NameNode. Testez avec une ACL simple. Récupération : Si la modification a été faite sans redémarrage, redémarrez le NameNode pour prendre en compte le paramètre. Les ACL existantes peuvent devoir être réappliquées si la fonctionnalité a été désactivée à un moment donné. ### Erreur 7 : Négliger dfs.namenode.handler.count sous forte charge Pourquoi cela arrive : Le nombre de gestionnaires par défaut (10) est souvent trop faible pour les clusters avec de nombreux clients simultanés, provoquant une accumulation dans la file d'attente RPC et des opérations de métadonnées lentes. Symptôme : Les journaux du NameNode affichent « RPC queue full » ou des avertissements « Slow RPC » ; les clients expirent. Comment éviter : Surveillez la longueur de la file d'attente RPC et les temps de traitement du NameNode à l'aide du point de terminaison JSON des métriques ou JMX. Augmentez dfs.namenode.handler.count à une valeur basée sur le nombre de cœurs et la concurrence attendue, généralement 20 à 50 pour les clusters moyens. Testez progressivement. Récupération : Si vous l'augmentez trop, l'utilisation de la mémoire peut augmenter. Surveillez l'utilisation du tas et ajustez. ## Liste de contrôle des opérations Utilisez cette liste de contrôle avant, pendant et après toute modification de configuration HDFS. Attribuez un responsable unique pour chaque élément afin d'éviter la dilution des responsabilités. Revenez sur cette liste à chaque changement (par exemple, revue hebdomadaire des modifications ou par incident).
ÉtapeTâcheResponsableFréquenceFait ?
1Vérifier la version et la topologie de HDFSPriya Shah, responsable plateformeÀ chaque changement
2Capturer les valeurs de configuration actuelles pour les propriétés ciblesAlex Chen, ingénieur DevOpsÀ chaque changement
3Définir le résultat attendu et le signal d'échec pour le changement planifiéPriya ShahÀ chaque changement
4Sauvegarder les fichiers de configurationAlex ChenÀ chaque changement
5Valider la syntaxe XML avec xmllintAlex ChenÀ chaque changement
6Appliquer le changement via la gestion de configuration ou l'édition manuelle sur tous les nœudsAlex ChenÀ chaque changement
7Redémarrer les démons dans le bon ordre (progressif si possible)Priya ShahÀ chaque changement
8Vérifier la santé du cluster avec hdfs dfsadmin -reportMaria Garcia, administratrice plateforme de donnéesImmédiatement après le redémarrage
9Exécuter une vérification ciblée pour le changement spécifiqueMaria GarciaDans l'heure suivant le changement
10Vérifier les effets secondaires indésirables (par exemple, augmentation de la mémoire, clients lents)Maria GarciaDans les 24 heures
11Documenter le changement, le résultat et les problèmes éventuels dans le runbookAlex ChenLe jour même
12Revoir le plan de retour en arrière si la vérification a échoué et l'exécuter si nécessairePriya ShahEn cas d'échec
Ce tableau est un modèle ; remplacez les responsables par les membres de votre équipe. L'essentiel est que chaque tâche ait une personne responsable, pas un groupe, pour éviter les suppositions selon lesquelles quelqu'un d'autre l'a fait. De plus, assurez-vous de : - Utiliser d'abord des commandes en lecture seule. Ne faites jamais une modification sans observer l'état actuel. - Ne jamais mettre de vrais secrets dans les fichiers de configuration ou la documentation. Utilisez des variables d'environnement ou des coffres de clés sécurisés. - Tenir un journal de toutes les modifications avec horodatage pour l'audit et le dépannage. - Planifier des revues de configuration au moins mensuellement, pas seulement lorsque des problèmes surviennent. ## Conclusion Les erreurs de configuration HDFS proviennent souvent d'un manque de conscience des versions, d'une vérification insuffisante et d'une propriété floue des tâches de modification. En suivant un chemin structuré – inventaire, plus petit changement justifié, vérification et récupération documentée – vous pouvez prévenir la plupart des incidents et résoudre rapidement ceux qui surviennent. Les techniques de ce guide s'appliquent largement : observer avant d'intervenir, définir les résultats attendus, utiliser des commandes concrètes avec des espaces réservés et attribuer des responsabilités. Comme prochaine étape, choisissez une vérification à faible risque de la liste de contrôle (par exemple, vérifier votre valeur actuelle de dfs.replication ), enregistrez l'état actuel, exécutez la commande et comparez-la à votre valeur attendue. Passez ensuite en revue les dépendances telles que Apache Spark, NiFi et Kafka qui reposent sur les performances et la disponibilité de HDFS. N'oubliez pas qu'un flux de travail technique fiable rend les défaillances visibles, protège les valeurs sensibles, limite les modifications aux ressources prévues et définit la vérification de la récupération avant qu'un incident ne force la décision.