Ceph Command Cheatsheet¶
Cette fiche rassemble les principales commandes utiles pour administrer, surveiller et dépanner un cluster Ceph.
Elle est destinée principalement aux administrateurs système et stockage intervenant sur les clusters Ceph en production. Elle privilégie les commandes utiles au quotidien : état du cluster, OSD, disques, pools, PG, CRUSH, équilibrage, maintenance, cephadm, RBD et CephFS.
Cette cheatsheet est volontairement orientée opérations et troubleshooting plutôt que description exhaustive de toutes les commandes Ceph.
Références¶
Avant d'utiliser cette fiche, deux références sont particulièrement utiles :
1. Ceph Cheatsheet — TheJJ / GitHub¶
Une cheatsheet très complète consacrée à l'exploitation d'un cluster Ceph. Elle contient notamment des commandes et recommandations concernant les OSD, PG, pools, CRUSH, CephFS, RBD, les performances et le troubleshooting.
Ceph Cheatsheet — TheJJ / GitHub
Cette documentation est une bonne référence pratique, mais certaines commandes ou recommandations peuvent être liées à des versions plus anciennes de Ceph. Il convient donc de vérifier la syntaxe avec la documentation correspondant à la version du cluster.
2. Ceph Commands / Control Commands — documentation officielle¶
La documentation officielle Ceph constitue la référence de référence pour la syntaxe et le comportement des commandes.
Ceph Control Commands — documentation officielle
Pour une commande ayant un impact sur le cluster, notamment les opérations sur les OSD, les PG, les pools, les flags ou la configuration, il est recommandé de vérifier sa documentation officielle avant exécution.
Convention¶
Les commandes sont regroupées par opération :
- État et diagnostic du cluster
- OSD et disques
- Pools et utilisation
- CRUSH et équilibrage
- PG et scrub
- Configuration
- Flags de maintenance
- cephadm / orchestrator
- Remplacement et suppression d'OSD
- Performances RADOS / RBD
- CephFS
- Troubleshooting
⚠️ Attention aux commandes de modification¶
Certaines commandes ne se contentent pas d'afficher des informations : elles modifient directement l'état du cluster.
Avant toute opération de maintenance ou potentiellement destructive, vérifier au minimum :
En particulier, prendre garde aux commandes concernant :
# OSD out / purge / destroy
# reweight
# flags noout / norecover / nobackfill
# noscrub / nodeep-scrub
# ceph orch osd rm
# ceph-volume ... zap
# configuration Ceph
Sur un cluster cephadm, privilégier autant que possible les commandes de l'orchestrateur (ceph orch ...) plutôt que les manipulations manuelles de systemd ou ceph-volume.
Cette fiche est une aide-mémoire. Elle ne remplace pas la documentation officielle Ceph ni les procédures de maintenance validées pour le cluster concerné.
1. État général du cluster¶
Statut¶
Surveiller les événements¶
Messages du Manager :
Informations générales¶
Rapport complet pour diagnostic¶
2. OSD¶
Lister les OSD¶
Lister les OSD down :
Lister les OSD qui ne sont pas up :
Rechercher un OSD¶
Exemple :
Voir les métadonnées :
3. Disques / devices¶
Inventaire des devices¶
Par hôte :
Informations sur un device :
Faire clignoter la LED du disque¶
ou explicitement :
Fonction dépendante du matériel, du firmware, du kernel et de l'HBA/backplane.
Santé / durée de vie¶
4. Utilisation disque¶
Vue globale¶
Utilisation des OSD¶
Par classe :
Utile pour identifier un OSD anormalement rempli :
5. Pools¶
Liste des pools¶
Paramètres d'un pool :
Quelques paramètres intéressants individuellement :
ceph osd pool get <pool> size
ceph osd pool get <pool> min_size
ceph osd pool get <pool> pg_num
ceph osd pool get <pool> pgp_num
ceph osd pool get <pool> pg_autoscale_mode
ceph osd pool get <pool> crush_rule
Statistiques :
6. CRUSH¶
Règles CRUSH¶
Vue de l'arbre :
Poids CRUSH :
À distinguer de
ceph osd reweight: le premier modifie le poids CRUSH réel ; le second applique un override au niveau de l'OSD.
7. Reweight / équilibrage¶
Voir la distribution¶
Tester un reweight automatique¶
Avec paramètres :
Appliquer¶
Exemple prudent :
Empêcher l'augmentation des poids :
Reweight manuel d'un OSD¶
Exemple :
Pour remettre à la valeur normale :
OSD dont le reweight est différent de 1¶
ceph osd tree -f json-pretty |
jq '.nodes[]
| select(.type=="osd")
| select(.reweight != 1)
| {id,name,reweight}'
Préférer le balancer
pg-upmapà des reweights manuels permanents.
8. Balancer¶
Voir les modules :
Activer le balancer si nécessaire :
Activer le mode upmap :
Activer le mode automatique :
Vérifier :
Le balancer est normalement préférable à une succession de
ceph osd reweight.
9. Versions¶
Version locale :
Versions de tous les daemons :
Versions des OSD :
Historique cephadm :
10. Crash Ceph¶
Lister les crashs récents :
Lister tous les crashs :
Statistiques :
Détails :
Archiver un crash après analyse :
Archiver tous les nouveaux :
Supprimer :
Ne pas faire
archive-allavant d'avoir regardé pourquoi les daemons ont crashé.
11. Flags OSD¶
Maintenance d'un hôte¶
Puis, après maintenance :
Préférer un ciblage précis¶
Pour un OSD :
Pour un host / bucket CRUSH :
Flags de récupération¶
Bloquer le backfill¶
Bloquer le recovery¶
Bloquer le rebalancing¶
Bloquer les scrubs¶
Bloquer les deep-scrubs¶
Voir les flags actifs¶
Attention :
nobackfill,norecover,noscrubetnodeep-scrubdoivent rester temporaires. Ils peuvent augmenter fortement le risque opérationnel s'ils sont oubliés.
12. Full / Nearfull¶
Voir les ratios :
Modifier :
Ne modifier ces valeurs que si l'on comprend les conséquences. Un OSD qui atteint
fullpeut provoquer des erreurs d'écriture.
13. Placement Groups (PG)¶
Vue générale¶
Liste des PG¶
Pools :
OSD :
PG d'un pool :
PG d'un OSD :
Mapping d'un PG¶
Exemple :
Informations détaillées¶
14. Scrub / Deep-scrub¶
Forcer un scrub :
Forcer un deep-scrub :
Exemple :
Le deep-scrub est beaucoup plus coûteux qu'un scrub normal.
15. PG inconsistent / réparation¶
Identifier :
Examiner :
Lancer une réparation :
Puis surveiller :
Ne pas lancer
repairaveuglément. Examiner d'abord le PG et les objets concernés.
16. Autoscaler PG¶
État de l'autoscaler :
Voir le mode d'un pool :
Modes :
Modifier :
Indiquer la taille cible d'un pool¶
Par exemple 100 TB :
Ou par ratio :
Puis :
Sur les clusters modernes, laisser l'autoscaler travailler est généralement préférable à calculer manuellement
pg_num.
17. Configuration Ceph¶
Voir la configuration :
Lister les options disponibles :
Voir la valeur effective :
Exemple :
Modifier :
Exemple :
Exemple :
Voir les valeurs par défaut / effectives :
Voir les différences de configuration :
18. OSD Memory Autotuning¶
Vérifier :
ceph config get osd osd_memory_target_autotune
ceph config get mgr mgr/cephadm/autotune_memory_target_ratio
Activer :
Par défaut avec cephadm :
Pour une infrastructure hyperconvergée, une valeur plus faible peut être nécessaire, par exemple :
À adapter à la RAM réellement disponible et aux autres services présents sur les nœuds.
19. cephadm / Orchestrator¶
État de l'orchestrateur¶
Services¶
Daemons¶
Hosts¶
Ajouter un label :
Exemple :
20. Gestion des daemons avec cephadm¶
Redémarrer :
Arrêter :
Démarrer :
Reconfigurer :
Redeployer :
Exemple :
Avec cephadm, préférer
ceph orch daemon ...aux manipulations directes de systemd lorsque le daemon est géré par l'orchestrateur.
21. Upgrade cephadm¶
Vérifier :
Lancer une mise à jour par image :
Ou par version :
Surveiller :
Messages cephadm :
Pause :
Reprise :
22. Remplacement d'un OSD — cephadm¶
Méthode recommandée¶
Identifier le device :
Puis utiliser :
Exemple :
Si le device est partagé par plusieurs OSDs, cephadm demande explicitement une confirmation.
Pour supprimer un remplacement préparé :
Suivre l'opération¶
23. Suppression d'un OSD — cephadm¶
Déclencher la suppression :
Avec nettoyage du disque :
Suivre l'opération :
Arrêter une suppression en cours :
Remplacement en conservant l'ID¶
Forcer :
--forcedoit être exceptionnel : il permet de supprimer un OSD sans attendre l'évacuation normale des PG.
24. Suppression manuelle d'un OSD¶
À réserver aux situations où l'orchestrateur ne peut pas être utilisé.
Vérifier :
Sortir l'OSD :
Attendre :
Puis seulement après validation :
Avec cephadm, préférer
ceph orch osd rm.
25. Outils ceph-volume¶
Inventaire :
Lister les OSD LVM :
Voir un device :
Zapper un disque¶
Avec destruction des structures LVM :
DANGER : vérifier impérativement le device avant
zap.
26. RADOS benchmark¶
Écriture¶
Lecture séquentielle :
Lecture aléatoire :
Nettoyage :
--no-cleanuplaisse volontairement les objets de test dans le pool. Toujours exécuterrados cleanupensuite.
27. RBD performance¶
Depuis le cluster¶
I/O par image :
Vue type iotop :
Exemple :
28. Benchmark depuis un client RBD¶
Écriture¶
fio \
--filename=/mnt/rbd/fio.test \
--size=20G \
--bs=4M \
--numjobs=1 \
--rw=write \
--name=fio \
--direct=1 \
--runtime=30 \
--iodepth=32 \
--ioengine=libaio
Lecture¶
fio \
--filename=/mnt/rbd/fio.test \
--size=20G \
--bs=4M \
--numjobs=1 \
--rw=read \
--name=fio \
--direct=1 \
--runtime=30 \
--iodepth=32 \
--ioengine=libaio
Pour un benchmark représentatif, préciser également le type d'accès (
randread,randwrite,readwrite), la taille de bloc et le niveau de parallélisme correspondant à la charge réelle.
29. CephFS¶
État¶
Daemons MDS¶
Statistiques du daemon¶
Exemple :
Opérations en cours¶
Depuis le nœud MDS :
Exemple :
Sessions¶
En cas de
MDS_SLOW_REQUEST, commencer parceph health detail, puis examinerdump_ops_in_flight.
30. Entrer dans un conteneur cephadm¶
Lister les daemons :
Entrer dans un conteneur :
Ou pour cibler un daemon :
La syntaxe exacte dépend de ce que l'on cherche à exécuter ; pour les opérations Ceph normales, privilégier la CLI
ceph/ceph orch.
31. Tuned¶
Lister les profils disponibles :
Profil actif :
Exemples :
Vérifier que le profil est réellement disponible et adapté à la distribution/kernel utilisés.
32. Diagnostic rapide¶
Cluster en erreur¶
OSD problématique¶
PG problématique¶
Problème de recovery¶
Problème de CephFS¶
ceph fs status
ceph health detail
ceph orch ps --daemon_type mds
ceph daemon mds.<name> dump_ops_in_flight
OSD très rempli¶
33. Avant une maintenance d'un nœud¶
1. Vérifier la santé¶
2. Identifier les OSD du nœud¶
3. Vérifier les opérations en cours¶
4. Poser éventuellement noout ciblé¶
5. Effectuer la maintenance¶
6. Vérifier le retour des OSD¶
7. Retirer le flag¶
8. Vérifier le retour à la normale¶
34. Commandes à manier avec précaution¶
Les commandes suivantes peuvent avoir un impact important :
ceph osd out
ceph osd purge
ceph osd destroy
ceph osd reweight
ceph osd set noout
ceph osd set norecover
ceph osd set nobackfill
ceph osd set noscrub
ceph osd set nodeep-scrub
ceph orch osd rm --force
ceph-volume lvm zap --destroy
Avant toute opération destructive :
Et toujours vérifier explicitement :
- le bon cluster
- le bon host
- le bon OSD
- le bon device
- l'état des PG
- l'espace disponible
- les flags actifs
35. Références¶
Documentation Ceph :
https://docs.ceph.com/en/latest/
Commandes de contrôle :
https://docs.ceph.com/en/latest/rados/operations/control/
Placement Groups :
https://docs.ceph.com/en/latest/rados/operations/placement-groups/
Troubleshooting OSD :
https://docs.ceph.com/en/latest/rados/troubleshooting/troubleshooting-osd/
Cephadm :
https://docs.ceph.com/en/latest/cephadm/
CephFS troubleshooting :
https://docs.ceph.com/en/tentacle/cephfs/troubleshooting/
Device management :
https://docs.ceph.com/en/latest/rados/operations/devices/
RBD :