Commandes HDFS de base avec exemples pratiques : de la découverte à la reprise

Intro

Ce guide transforme les bases d’HDFS en opérations fiables du quotidien. Vous allez inventorier votre environnement, exécuter en sécurité les commandes clés hdfs dfs, vérifier les résultats avec des outils de diagnostic, puis appliquer des procédures de reprise claires pour les pannes courantes. Tous les exemples utilisent des espaces réservés (aucun secret) et mettent l’accent sur une discipline d’observation d’abord, changement ensuite.

Périmètre et versions : commandes valables pour Apache Hadoop HDFS 2.7–3.x. Certains drapeaux varient légèrement selon la version; en cas de doute, consultez hdfs help ou hdfs dfs -help <subcommand> dans votre environnement.

Inventaire de la version et de l’environnement

Avant de modifier quoi que ce soit, confirmez ce que vous exécutez et comment c’est déployé.

Prérequis:

Accès shell à un nœud avec les outils clients Hadoop
Accès réseau au NameNode et aux DataNodes
Un principal utilisateur avec accès en lecture (et écriture/admin uniquement si requis)

Découverte en lecture seule :

# Version HDFS/Hadoop côté client
hdfs version
hadoop version

# Nameservices et topologie NameNode (HA ou NN unique)
hdfs getconf -confKey dfs.nameservices
hdfs getconf -namenodes
# Pour les nameservices en HA, lister les NameNodes HA par nameservice
hdfs getconf -confKey dfs.ha.namenodes.<NAMESERVICE>

# Configuration effective pour une clé donnée
hdfs getconf -confKey dfs.replication

# Rapport de stockage du cluster (aucun changement)
hdfs dfsadmin -report

# Santé rapide de l’espace de noms et des blocs (lecture seule)
hdfs fsck / -files -blocks -locations -racks -move -delete | head -n 50
# Remarque : fsck ci-dessus est en lecture seule sauf si -move ou -delete sont utilisés; omettez-les pour une observation pure

Consignez les horodatages et les sorties. Définissez des signaux attendus avant tout changement. Exemples de signaux :

hdfs dfsadmin -report affiche tous les DataNodes attendus en Alive
L’utilisation de l’espace de noms est sous vos seuils d’alerte
hdfs getconf -confKey dfs.replication renvoie le facteur de réplication par défaut (p. ex., 3)

Exemples essentiels de commandes HDFS

Les commandes suivantes couvrent la majorité des opérations quotidiennes. Remplacez les espaces réservés comme <HDFS_PATH> et <LOCAL_PATH> par vos valeurs.

1) Découverte et listage

# Lister répertoires et fichiers
hdfs dfs -ls /
hdfs dfs -ls -h /data/events

# Liste récursive avec tailles lisibles
hdfs dfs -ls -R -h /projects/<TEAM>

# Métadonnées et résumé d’un fichier
hdfs dfs -stat "%n %b bytes %o owner %r repl %y mtime" /data/logs/app.log

# Utilisation disque (tailles logiques HDFS)
hdfs dfs -du -h /warehouse/tables
hdfs dfs -dus -h /warehouse/tables  # résumé uniquement

Signaux attendus :

-h affiche des tailles conviviales (MB/GB)
-R inclut les chemins imbriqués
-stat imprime le nom, la taille, le propriétaire, la réplication et la date de modification

2) Lecture et écriture de données

# Téléversement (local -> HDFS)
hdfs dfs -mkdir -p /user/<USER>/ingest
hdfs dfs -put -f /local/path/file.csv /user/<USER>/ingest/

# Téléchargement (HDFS -> local)
hdfs dfs -get /user/<USER>/ingest/file.csv /tmp/

# Diffusion du contenu
hdfs dfs -cat /user/<USER>/ingest/file.csv | head -n 5
hdfs dfs -tail -f /logs/app/app.log  # suit le dernier 1 Ko, utile pour le débogage

# Copier et déplacer au sein d’HDFS
hdfs dfs -cp /data/raw/file.parquet /data/stage/file.parquet
hdfs dfs -mv /data/stage/file.parquet /data/prod/file.parquet

# Suppression sûre via la Corbeille (si activée)
hdfs dfs -rm /tmp/old.tmp
hdfs dfs -rm -r /tmp/old_dir
# Suppression définitive (court-circuite la Corbeille; prudence)
hdfs dfs -rm -r -skipTrash /tmp/old_dir

Vérification :

-ls pour confirmer présence et taille
-checksum pour valider l’intégrité si nécessaire : hdfs dfs -checksum <HDFS_PATH>

3) Permissions et ACL

# Propriété et modes (privilèges requis)
hdfs dfs -chown <USER>:<GROUP> /projects/<TEAM>
hdfs dfs -chmod -R 750 /projects/<TEAM>

# Le listage de style POSIX inclut les permissions
hdfs dfs -ls -d /projects/<TEAM>

# ACL (permissions fines)
hdfs dfs -setfacl -m user:<ANALYST>:r-x /projects/<TEAM>/dataset
hdfs dfs -getfacl /projects/<TEAM>/dataset
# Supprimer une entrée ACL
hdfs dfs -setfacl -x user:<ANALYST> /projects/<TEAM>/dataset

Signaux :

-ls affiche les bits de mode; getfacl montre les entrées ACL explicites
Préférez les ACL pour accorder un accès en lecture sans modifier la propriété du répertoire

4) Réplication et quotas

# Ajuster la réplication d’un fichier et attendre la fin
hdfs dfs -setrep -w 3 /data/prod/critical.parquet

# Vérifier la réplication
hdfs fsck /data/prod/critical.parquet -files -blocks -racks | grep -i replication

# Quotas d’espace et d’objets (admin)
hdfs dfsadmin -setSpaceQuota 2t /teams/<TEAM>
hdfs dfsadmin -setQuota 1000000 /teams/<TEAM>   # 1M fichiers+répertoires

# Vérifier les quotas et l’usage
hdfs dfs -count -q -h /teams/<TEAM>
# Supprimer les quotas quand ils ne sont plus nécessaires
hdfs dfsadmin -clrSpaceQuota /teams/<TEAM>
hdfs dfsadmin -clrQuota /teams/<TEAM>

Signaux :

-setrep -w bloque jusqu’à atteindre la cible de réplication ou échouer
-count -q imprime les quotas, l’espace consommé et le nombre d’objets

Voie de configuration sécurisée

Appliquez le plus petit changement justifié, seulement après avoir observé l’état courant et défini un retour arrière.

Versions prises en charge : Hadoop 2.7–3.x (drapeaux communs entre ces versions). Le périmètre d’impact est indiqué pour chaque exemple.

Exemple A : Augmenter la réplication d’un fichier critique

Objectif : accroître la durabilité d’un seul fichier sans impacter les autres.

Prérequis :

Assez de DataNodes et d’espace disque pour héberger les réplicas supplémentaires
Droits d’écriture des métadonnées sur le chemin visé

Observation :

hdfs dfs -stat "%n repl:%r size:%b" /data/prod/critical.parquet
hdfs dfsadmin -report | grep -i "Configured Capacity\|DFS Used\|Under replicated blocks" -A2

Changement (périmètre d’impact : un fichier) :

hdfs dfs -setrep -w 4 /data/prod/critical.parquet

Vérification et retour arrière :

# Vérifier
hdfs fsck /data/prod/critical.parquet -files -blocks -locations | grep -i replication
# Revenir au facteur précédent si nécessaire
hdfs dfs -setrep -w 3 /data/prod/critical.parquet

Signaux d’échec et actions :

Attente bloquée : vérifiez hdfs dfsadmin -report pour espace bas ou DataNodes morts
Toujours sous-répliqué : consultez les journaux du NameNode et confirmez la connectivité réseau

Exemple B : Accorder un accès lecture avec une ACL

Objectif : permettre à un analyste de lire un jeu de données sans changer la propriété ni élargir les permissions du groupe.

Prérequis :

ACL activées (dfs.namenode.acls.enabled=true)

Observation :

hdfs dfs -ls -d /projects/<TEAM>/dataset
hdfs dfs -getfacl /projects/<TEAM>/dataset

Changement (périmètre d’impact : un arbre de répertoires) :

hdfs dfs -setfacl -R -m user:<ANALYST>:r-x /projects/<TEAM>/dataset

Vérification et retour arrière :

hdfs dfs -getfacl /projects/<TEAM>/dataset | grep <ANALYST>
# Tester l’accès (en tant qu’utilisateur analyste)
hdfs dfs -ls /projects/<TEAM>/dataset
# Retour arrière : supprimer l’entrée ACL
hdfs dfs -setfacl -R -x user:<ANALYST> /projects/<TEAM>/dataset

Vérifications et diagnostics

Utilisez des contrôles en lecture seule pour confirmer la santé avant et après chaque changement.

Santé de l’espace de noms et des blocs :

  hdfs fsck / -files -blocks -locations | head -n 100
  hdfs fsck /path/to/object -files -blocks -locations -racks

Signaux : aucun bloc manquant ou corrompu; réplication attendue par fichier.

Capacité du cluster et statut des nœuds :

  hdfs dfsadmin -report

Signaux : tous les DataNodes attendus vivants; utilisation raisonnable; Under replicated blocks proche de zéro.

État du mode sécurisé (Safe mode) :

  hdfs dfsadmin -safemode get

Signaux : doit être OFF pendant les écritures normales.

Répertoires actifs et plus gros consommateurs :

  hdfs dfs -count -q -h / | sort -k3 -hr | head -n 20

Signaux : identifier rapidement les plus gros consommateurs d’espace et les comptes d’inodes élevés.

Vérifications rapides NameNode/JMX (si autorisées) :
Interface Web ou JMX sur http(s)://<NN_HOST>:9870 (Hadoop 3) ou 50070 (Hadoop 2) pour tableaux de bord et métriques.

Modes de panne et reprise

Visez la correction minimale, vérifiez, puis documentez ce qui a changé.

Blocs sous-répliqués ou manquants

Observation :

  hdfs dfsadmin -report | grep -i "Under replicated"
  hdfs fsck / -list-corruptfileblocks

Causes probables : DataNodes morts, espace faible, déséquilibre de racks
Reprise :
Corrigez la santé des nœuds ou ajoutez de la capacité
Rééquilibrez si la distribution est déséquilibrée : hdfs balancer -threshold 10 (admin)
Pour un fichier spécifique, réduisez temporairement la réplication à la capacité disponible, puis restaurez-la quand la capacité revient
Vérifier : hdfs fsck /path -files -blocks | grep -i replication

NameNode en mode sécurisé (écritures en échec)

Observer : hdfs dfsadmin -safemode get
Causes : démarrage, manque de rapports de blocs, capacité insuffisante
Reprise :
Résolvez d’abord les problèmes de DataNode ou de capacité
En dernier recours (admin) : hdfs dfsadmin -safemode leave
Vérifier : téléversez un petit fichier et confirmez sa présence avec -ls

Permission refusée

Observer : message d’erreur exact et ACL actuelles

  hdfs dfs -getfacl /restricted/path

Reprise :
ACL ciblées : hdfs dfs -setfacl -m user:<USER>:r-x /restricted/path
Ou ajustez l’appartenance au groupe/la propriété si approprié
Vérifier : l’utilisateur peut lister (-ls) sans pouvoir écrire sauf si accordé

Disque plein ou presque

Observer : hdfs dfsadmin -report montre une forte utilisation
Reprise :
Archiver ou supprimer les données non critiques : hdfs dfs -rm -r /tmp/old/* (préférez la Corbeille)
Augmenter les quotas seulement après validation du besoin
Ajouter des DataNodes ou étendre les disques quand c’est possible
Vérifier : l’utilisation baisse; la sous-réplication se résorbe

Suppression accidentelle

Observer : vérifier la Corbeille et les instantanés

  hdfs dfs -ls /user/<USER>/.Trash/Current
  hdfs dfs -ls /data/project/.snapshot

Reprise :
Restaurer depuis la Corbeille : déplacez le fichier vers son chemin d’origine
Si les instantanés sont activés (autorisation admin) :

    hdfs dfs -createSnapshot /data/project before_delete
    # Pour restaurer ultérieurement
    hdfs dfs -restoreSnapshot /data/project before_delete

Vérifier : le contenu et les sommes de contrôle du fichier correspondent aux valeurs attendues

Liste de contrôle opérationnelle

Utilisez cette séquence reproductible pour toute modification HDFS.

Identifier la version et la topologie : hdfs version, hdfs getconf -namenodes
Observer la santé et la capacité : hdfs dfsadmin -report, hdfs fsck (lecture seule)
Définir le plus petit changement et son périmètre d’impact; rédiger les étapes de retour arrière
Exécuter avec des espaces réservés explicites et des commandes bornées dans le temps (p. ex., -setrep -w)
Vérifier le succès avec -ls, -stat, fsck et les contrôles de quotas
Consigner horodatages, commandes et sorties observées
En cas d’écart, arrêtez et diagnostiquez avant de poursuivre

Conclusion

Des opérations HDFS efficaces commencent par l’observation, se poursuivent par des changements précisément circonscrits, et s’achèvent par une vérification rigoureuse et un retour arrière clair. Utilisez la découverte pour comprendre votre version et votre topologie, appliquez les commandes hdfs dfs avec intention, validez avec dfsadmin -report et fsck, et gardez prêtes vos options de reprise comme les ACL ciblées, l’ajustement de la réplication, la Corbeille et les instantanés. Une exécution constante de ce flux limite le périmètre d’impact, protège les valeurs sensibles et rend visibles aussi bien les succès que les échecs.