Guide des opérations CLI Ceph : Workflows versionnés pour une administration sécurisée

L'administration de Ceph exige de la précision. Une seule commande mal appliquée peut entraîner une cascade d'indisponibilité des données ou une récupération prolongée. Ce guide fournit des workflows conscients des versions, testés en production, pour les versions Reef (18.2.x), Squid (19.2.x) et 20.x. Il remplace les aide-mémoire génériques par des procédures concrètes : inventaires de référence, changements de configuration délimités, diagnostics approfondis et chemins de récupération documentés pour la perte de quorum des moniteurs, le remplacement d'OSD, l'incohérence de PG et la pression de capacité. Chaque commande inclut les signaux de sortie attendus, les étapes de vérification et les actions de restauration.

Prérequis et inventaire de l'environnement

Matrice des versions supportées

Les déploiements basés sur paquets (apt, yum, dnf) utilisent systemctl pour la gestion des démons ; les clusters cephadm exécutent tous les démons dans des conteneurs. Ne mélangez jamais les méthodes d'orchestration sur le même cluster.

Exigences d'accès administrateur

• Trousseau de clés : /etc/ceph/ceph.client.admin.keyring (mode 0600, propriétaire root:root) ou variable d'environnement CEPH_KEYRING.
• Configuration : /etc/ceph/ceph.conf ou CEPH_CONF pointant vers une configuration valide avec les entrées mon_host.
• Privilèges : sudo ou root ; cephadm nécessite un sudo sans mot de passe pour l'utilisateur cephadm.
• Réseau : TCP 6789/3300 (mon), 6800–7300 (OSD/MDS/MGR/RGW) accessibles entre tous les nœuds ; résolution DNS ou /etc/hosts pour les noms d'hôtes des moniteurs.
• Santé du quorum : ceph -s doit afficher mon: <N> daemons, quorum <ids> avant toute opération d'écriture.

Commandes de capture de référence

Exécutez ces commandes avant tout changement et stockez les sorties avec des noms de fichiers horodatés :

ceph -s -f json
ceph versions -f json
cephadm ls -f json
ceph config dump -f json > baseline-config-$(date +%F-%H%M).json
ceph auth ls -f json
ceph osd tree -f json > baseline-topology-$(date +%F-%H%M).json

Conservez ces sorties dans un contrôle de version ou joignez-les à votre ticket de changement pour référence de restauration.

Référence rapide d'architecture

Rôles des démons et commandes clés

Hiérarchie CRUSH et classes de périphériques

Hiérarchie par défaut :

root=default
  datacenter=dc1
    room=room1
      row=row1
        rack=rack1
          chassis=chassis1
            host=storage-01
              osd.0 (class=hdd)
              osd.1 (class=nvme)

Les classes de périphériques (hdd, ssd, nvme) pilotent le placement des PG via les règles crush. Listez les classes avec ceph osd crush class ls.

Aide-mémoire des états PG

Inventaire de version et d'environnement (concret)

Commandes d'inventaire principales

# Rapport de version complet (JSON inclut overall, mon, mgr, osd, mds, rgw)
ceph versions -f json

# Inventaire des démons gérés par cephadm
cephadm ls -f json

# Vue hôte/démon de l'orchestrateur
ceph orch host ls -f json
ceph orch ps -f json --format=json-pretty

# Capacité et utilisation
ceph df -f json
ceph osd df -f json
ceph pg stat -f json

Champs JSON attendus et indicateurs de santé

• ceph versions : "overall": "18.2.4", "mon": ["18.2.4", "18.2.4", "18.2.4"], "mgr": "18.2.4", "osd": ["18.2.4" ...]. Versions mixtes → planifier la mise à niveau.
• cephadm ls : Chaque entrée montre "style": "cephadm:v18.2.4", "name": "osd.0", "container_image_name": "docker.io/ceph/ceph:v18.2.4", "status": "running".
• ceph df : "stats": {"total_bytes": 10995116277760, "total_used_bytes": 3298534883328, "total_avail_bytes": 7696581394432}. total_avail_bytes sous 30 % → rééquilibrage nécessaire.
• ceph pg stat : "pgmap": {"num_pgs": 1024, "num_objects": 50000, "state": ["active+clean": 1020, "active+remapped": 4]}.

Chemin de configuration sécurisé

Audit en lecture seule d'abord

# Configuration effective complète (toutes sections, tous démons)
ceph config dump -f json

# Clé unique pour un démon spécifique ou global
ceph config get global osd_pool_default_size
ceph config get osd.0 osd_memory_target
ceph config get mgr mgr/cephadm/container_image_base

Changements délimités avec rayon d'impact défini

Vérification après changement

# Afficher la différence par rapport à ceph.conf sur disque et à la BD du moniteur
ceph config diff -f json

# Confirmer l'état de l'autoscaler au niveau pool
ceph osd pool ls detail -f json | jq '.[] | {pool_name, pg_autoscale_mode, pg_num, pgp_num}'

# Santé et état PG
ceph -s
ceph pg stat

Procédures de restauration

# Supprimer une clé de configuration (revient à la valeur par défaut compilée ou au scope parent)
ceph config rm global osd_pool_default_pg_autoscale_mode

# Restaurer une valeur explicite précédente
ceph config set global osd_pool_default_size 3

# Redéployer les démons affectés pour prendre en compte la config (cephadm seulement)
cephadm redeploy --limit osd --dry-run
cephadm redeploy --limit osd

⚠️ Rayon d'impact : cephadm redeploy redémarre les démons ; planifiez pendant une période de faible I/O. Vérifiez que ceph -s retourne HEALTH_OK dans les 5 minutes.

Vérification et diagnostics

Analyse approfondie de la santé

# Santé détaillée avec codes et descriptions
ceph health detail -f json

# Muter une vérification spécifique avec TTL (ex: pendant maintenance OSD planifiée)
ceph health mute OSD_DOWN 1h --sticky

# PGs par état (filtrer pour états actionnables)
ceph pg ls bystate degraded,inconsistent,incomplete,stale,undersized -f json

# Arbre OSD avec poids et classes de périphériques
ceph osd tree -f json

# Compteurs de performance OSD (latence, débit)
ceph osd perf -f json

Opérations lentes et internes OSD

# Opérations lentes historiques sur un OSD spécifique (requiert mgr actif)
ceph daemon osd.0 dump_historic_ops -f json

# Statistiques de tas sur tous les OSD (pression mémoire)
ceph tell osd.* heap stats -f json

# Dump de performance depuis le démon OSD (histogrammes de latence, profondeurs de files)
ceph daemon osd.0 perf dump -f json | jq '.osd_op_latency, .commit_latency, .apply_latency'

Diagnostics réseau et horloge

# Vérification du décalage d'horloge des moniteurs (requiert quorum mon)
ceph mon_clock_skew_check -f json

# Version du moniteur et époque de la carte
ceph tell mon.* version -f json

# Connectivité réseau depuis le nœud admin
ceph tell mon.* ping -f json

Collecte de journaux

# Journaux cephadm (dernières 100 lignes)
ceph log last cephadm 100

# Journal systemd pour un démon spécifique (paquet ou cephadm)
journalctl -u ceph-<FSID>@osd.0 -n 200 --no-pager

# Journal du démon Ceph via socket (fonctionne pour les deux déploiements)
ceph daemon osd.0 log flush
ceph daemon osd.0 log reopen

Modes de défaillance et récupération

Perte de quorum des moniteurs

Symptômes : ceph -s affiche mon: 1 daemons, quorum <single>, HEALTH_ERR, erreurs d'I/O client. Prérequis : Au moins un mon en cours d'exécution, accès à sa BD (/var/lib/ceph/mon/ceph-<id>/store.db).

Récupération :

# 1. Extraire le monmap du moniteur survivant
ceph mon dump -f json > monmap-backup.json

# 2. Arrêter tous les mons, injecter le monmap sur chacun
systemctl stop ceph-mon@<id>  # ou cephadm: ceph orch daemon stop mon.<host>
ceph-mon -i <id> --inject-monmap monmap-backup.json

# 3. Démarrer les mons séquentiellement, vérifier le quorum
systemctl start ceph-mon@<id>
ceph -s

Récupération après sinistre : Si tous les mons perdus, reconstruire à partir de ceph-mon --mkfs -i <id> --monmap <file> --keyring <admin-keyring> en utilisant un monmap sauvegardé.

OSD Down / Out / Remplacement

Symptômes : ceph osd tree affiche down, out, ou destroyed ; PGs degraded / recovery.

Workflow :

# 1. Marquer l'OSD out (démarre le rééquilibrage)
ceph osd out 12

# 2. Attendre que les PGs atteignent active+clean (surveiller)
ceph -w  # ou: while ceph pg ls degraded -f json | grep -q degraded; do sleep 10; done

# 3. Détruire l'OSD (retire du crush, supprime l'auth)
ceph osd destroy 12 --yes-i-really-mean-it

# 4. Effacer le périphérique (paquet ou cephadm)
ceph-volume lvm zap /dev/sdX --destroy

# 5. Ajouter le remplacement (cephadm)
ceph orch daemon add osd storage-01:/dev/nvme0n1
# Paquet: ceph-volume lvm create --bluestore --data /dev/nvme0n1

⚠️ Avertissement : Ne jamais ceph osd destroy sans ceph osd out préalable et rééquilibrage propre. Risque de perte de données si PGs pas active+clean.

PG Inconsistent / Bloqué

Symptômes : ceph health detail affiche PG_INCONSISTENT, ceph pg ls inconsistent retourne des IDs de PG. Prérequis : Identifier les PGs affectés, vérifier les sauvegardes, comprendre que ceph pg repair peut supprimer des données.

Récupération :

# 1. Lister les PGs incohérents avec détails
ceph pg ls inconsistent -f json

# 2. Réparer un PG unique (exécuter sur l'OSD primaire si possible)
ceph pg repair 1.5

# 3. Surveiller l'état de réparation
ceph pg ls 1.5 -f json -w  # observer jusqu'à ce que l'état "repair" disparaisse

# 4. Si la réparation échoue, deep-scrub d'abord
ceph pg deep-scrub 1.5
ceph pg repair 1.5

🔄 Restauration : Pas de restauration automatisée ; restaurer depuis la sauvegarde si la réparation cause une perte de données.

Cluster plein / quasi-plein

Symptômes : HEALTH_ERR / HEALTH_WARN FULL / NEARFULL, ceph df affiche > 85% / 95% utilisé.

Récupération :

# 1. Identifier les OSD surutilisés
ceph osd df -f json | jq '.nodes[] | select(.type=="osd") | {id, utilization, kb_avail}'

# 2. Ajuster temporairement les ratios full (gagne du temps)
ceph config set global mon_osd_full_ratio 0.95
ceph config set global mon_osd_nearfull_ratio 0.85

# 3. Réduire le poids des OSD surchargés (progressif)
ceph osd crush reweight osd.0 0.8

# 4. Ajouter de la capacité (préféré)
ceph orch daemon add osd <host>:<device>

# 5. Déclencher le balancer
ceph balancer on
ceph balancer status -f json

Échecs bootstrap / mise à niveau cephadm

Symptômes : cephadm bootstrap bloque, cephadm upgrade rapporte des erreurs upgrade_plan.

Diagnostics :

# Exécution à blanc avant tout changement
cephadm bootstrap --dry-run --config /etc/ceph/ceph.conf
cephadm upgrade --dry-run --image docker.io/ceph/ceph:v19.2.0

# Inspecter le plan de mise à niveau
cephadm upgrade --dry-run --image docker.io/ceph/ceph:v19.2.0 -f json | jq '.upgrade_plan'

# Redéployer un type de démon spécifique après mise à niveau échouée
cephadm redeploy --limit mgr --dry-run
cephadm redeploy --limit mgr

Récupération : Revenir à l'image conteneur précédente via ceph config set mgr mgr/cephadm/container_image_base <old_image> puis cephadm redeploy --limit mgr.

Liste de contrôle des opérations (style runbook)

Validation avant changement

• [ ] ceph -s → HEALTH_OK ou HEALTH_WARN connu (documenté)
• [ ] ceph config dump -f json > pre-change-$(date +%F-%H%M).json
• [ ] ceph df → marge de capacité > 20%
• [ ] Fenêtre de maintenance approuvée, parties prenantes notifiées
• [ ] Commandes de restauration rédigées et testées en mode dry-run

Modèle d'exécution par tâche

Vérification après changement

• [ ] ceph -s → HEALTH_OK
• [ ] ceph pg stat → tous active+clean (zéro degraded, inconsistent, stale)
• [ ] ceph osd perf → commit_latency < 10 ms, apply_latency < 5 ms (ajuster selon charge)
• [ ] Alertes du tableau de bord effacées ; aucun nouvel avertissement ceph health detail
• [ ] ceph config diff correspond au changement prévu seulement

Exigences de documentation

• Référence de ticket, nom de l'opérateur, horodatages début/fin
• Sortie ceph config diff jointe
• Captures ceph -s et ceph pg stat avant/après
• Anomalies observées et mesures d'atténuation prises

Scénario technique réaliste

Scénario : Ajouter trois OSD NVMe sur storage-04 dans un cluster cephadm Reef 18.2.4

Objectif : Étendre la capacité de 3 × 3,84 To NVMe sur storage-04, vérifier que le rééquilibrage se termine sans pic de latence visible par le client.

Prérequis

• Cluster HEALTH_OK, ceph versions montre tous les démons 18.2.4
• storage-04 étiqueté : ceph orch host label add storage-04 nvme
• Périphériques visibles : lsblk -d -o NAME,SIZE,TYPE,MODEL /dev/nvme[0-2]n1
• Trousseau admin et ceph.conf sur le nœud de contrôle

Étapes d'exécution

# 1. Ajouter les OSD (cephadm orchestre ceph-volume lvm en interne)
ceph orch daemon add osd storage-04:/dev/nvme0n1
ceph orch daemon add osd storage-04:/dev/nvme1n1
ceph orch daemon add osd storage-04:/dev/nvme2n1

# 2. Observer le rééquilibrage PG en temps réel
ceph -w  # appuyer sur 'q' pour quitter ; surveiller les mises à jour "pgmap"

# 3. Surveiller les stats PG jusqu'à stabilisation
while true; do
  ceph pg stat -f json | jq '.pgmap | {active_clean: .state_counts[] | select(.name=="active+clean") | .count, recovering: .state_counts[] | select(.name=="recovery") | .count}'
  sleep 30
done

# 4. Vérifier la performance OSD pendant le rééquilibrage
ceph osd perf -f json | jq '.osd_perf_infos[] | select(.id==12 or .id==13 or .id==14) | {id, commit_latency_ms, apply_latency_ms}'

# 5. Vérifier l'état du balancer (auto-activé dans Reef+)
ceph balancer status -f json

# 6. Confirmer l'utilisation équilibrée
ceph osd df -f json | jq '.nodes[] | select(.type=="osd") | {id, utilization, kb_avail}' | sort -k2 -n

Critères de vérification

• Tous les PGs active+clean dans les 2 heures (ajuster selon volume de données)
• ceph osd perf latence sur nouveaux OSDs ≤ médiane OSD existants + 20%
• ceph df montre variance d'utilisation < 15% entre OSDs

Plan de restauration

# Si le rééquilibrage bloque ou latence pique :
ceph orch daemon rm osd.12 osd.13 osd.14
ceph-volume lvm zap /dev/nvme0n1 /dev/nvme1n1 /dev/nvme2n1 --destroy
ceph osd crush rm osd.12 osd.13 osd.14  # si entrées crush persistent

Documenter l'état final avec ceph config dump > post-expansion-$(date +%F).json.

Conclusion

La sécurité opérationnelle dans Ceph exige des commandes adaptées aux versions, des lignes de base observées et des chemins de restauration testés pour chaque changement. Ce guide remplace les aide-mémoire génériques par des workflows concrets : inventorier les versions Reef, Squid et 20.x via ceph versions et cephadm ls ; diagnostiquer avec ceph health detail et ceph daemon perf dump ; exécuter des changements délimités comme l'activation de l'autoscaler PG ou le remplacement d'OSD avec vérification explicite via ceph pg stat et ceph osd perf ; et récupérer après perte de quorum, incohérence PG ou pression de capacité en utilisant des procédures documentées. Capturez toujours ceph config dump et ceph -s avant et après ; mutez les vérifications de santé avec TTL pendant la maintenance planifiée ; distinguez les workflows conteneurs cephadm des opérations systemctl basées sur paquets. L'étape suivante consiste à sélectionner une vérification en lecture seule de ce guide, l'exécuter sur votre cluster, comparer la sortie aux signaux attendus documentés ici, et enregistrer le résultat dans votre runbook.