Dépannage de l'état de santé du cluster Elasticsearch : Un guide étape par étape

Un cluster Elasticsearch jaune ou rouge n'est pas un état mystérieux. Cela signifie généralement qu'Elasticsearch ne peut pas placer un ou plusieurs shards là où il le souhaite. Le travail consiste à trouver quel shard est bloqué, pourquoi l'allocation est bloquée, et si la bonne solution est d'attendre, de libérer des ressources, de ramener un nœud, de restaurer à partir d'un snapshot, ou d'accepter délibérément une perte de données.

Je considère l'état de santé du cluster comme un signal de triage, pas comme le diagnostic lui-même. Vert signifie que chaque shard primaire et réplica est assigné. Jaune signifie que tous les shards primaires sont assignés, donc les recherches et les écritures peuvent généralement continuer, mais au moins un réplica est manquant. Rouge signifie qu'au moins un shard primaire n'est pas assigné, donc une partie d'au moins un index est indisponible. Le rouge est celui qui peut immédiatement casser les lectures ou écritures d'applications.

Commencez par obtenir la vue simple :

GET /_cluster/health?pretty
GET /_cat/health?v

Regardez status, number_of_nodes, active_primary_shards, unassigned_shards, initializing_shards, et relocating_shards. Si vous voyez des shards en initialisation ou en relocalisation après un redémarrage de nœud, le cluster est peut-être déjà en train de récupérer. Ne commencez pas à modifier les paramètres d'allocation avant de savoir si Elasticsearch est simplement en train de travailler.

Ensuite, listez les shards non assignés :

GET /_cat/shards?v&h=index,shard,prirep,state,node,unassigned.reason&s=state,index,shard

La colonne prirep est importante. Un shard p est primaire. Un cluster rouge a toujours au moins un primaire non assigné. Un shard r est un réplica. Un cluster jaune a généralement uniquement des réplicas non assignés.

L'API la plus utile dans cette situation est l'explication d'allocation :

GET /_cluster/allocation/explain?pretty

Pour un shard spécifique, soyez explicite :

GET /_cluster/allocation/explain?pretty
{
  "index": "logs-2026.05.24",
  "shard": 0,
  "primary": false
}

Lisez la réponse can_allocate et les décisions au niveau du nœud. Elasticsearch vous dira généralement exactement quelle règle a bloqué l'allocation : les seuils d'eau du disque, les filtres d'allocation, les règles de même shard, l'allocation différée après le départ d'un nœud, les données primaires manquantes, les versions incompatibles, ou une inadéquation de rôle de nœud.

Quand le cluster est jaune

Le jaune est courant sur les petits clusters. Le cas classique est un cluster de développement à un seul nœud avec number_of_replicas: 1. Elasticsearch ne peut pas placer un réplica sur le même nœud que son primaire, donc le réplica reste non assigné pour toujours. Ce n'est pas une urgence dans un environnement portable. C'est une inadéquation de configuration.

Vérifiez le nombre de réplicas :

GET /my-index/_settings?filter_path=*.settings.index.number_of_replicas

Pour un cluster non-production à un seul nœud, définissez les réplicas à zéro :

PUT /my-index/_settings
{
  "index": {
    "number_of_replicas": 0
  }
}

Pour la production, ne cachez pas le problème en réduisant les réplicas, sauf si vous acceptez intentionnellement moins de redondance. Si l'index est censé avoir un réplica, vous avez besoin d'au moins deux nœuds de données éligibles. S'il a deux réplicas, vous avez besoin d'au moins trois nœuds de données éligibles. Le tiering peut rendre cela moins évident : un réplica d'index chaud ne peut pas s'allouer sur un nœud uniquement chaud si les règles d'allocation exigent des nœuds chauds.

La pression sur le disque est la prochaine cause courante de jaune. Vérifiez l'utilisation du disque des nœuds :

GET /_cat/allocation?v
GET /_cat/nodes?v&h=name,roles,disk.used_percent,disk.avail,heap.percent,cpu,load_1m

Elasticsearch utilise des seuils d'eau du disque pour éviter de remplir les nœuds. Les valeurs par défaut varient selon la version et la configuration, alors inspectez les paramètres réels de votre cluster :

GET /_cluster/settings?include_defaults=true&flat_settings=true&filter_path=**cluster.routing.allocation.disk.watermark**

Si un nœud dépasse le seuil d'eau haut, Elasticsearch évitera d'allouer plus de shards là-bas. S'il atteint le seuil d'eau de crue, Elasticsearch peut placer les index concernés dans un état de blocage en écriture pour protéger le nœud. La solution durable est de supprimer les anciennes données, de déplacer les données vers plus de nœuds, d'augmenter le disque, de réduire le nombre de shards surdimensionnés, ou d'ajuster la rétention ILM. Augmenter temporairement les seuils d'eau peut faire gagner du temps, mais cela ne devrait pas être votre premier geste.

Une séquence de nettoyage pratique ressemble à ceci :

GET /_cat/indices?v&s=store.size:desc
GET /_cat/shards?v&s=store:desc

Trouvez les grands index anciens, vérifiez les attentes de rétention avec l'équipe propriétaire, faites un snapshot si nécessaire, puis supprimez uniquement les données que vous êtes autorisé à retirer :

DELETE /old-logs-2025.12.*

Après avoir libéré de l'espace, l'allocation peut reprendre automatiquement. Si ce n'est pas le cas, relancez l'explication d'allocation. L'ancienne raison peut encore être dans votre tête, mais le cluster peut maintenant être bloqué par une règle différente.

Le filtrage d'allocation est une autre cause fréquente de jaune, surtout après des migrations matérielles. Quelqu'un a peut-être défini un index pour exiger un attribut de nœud qui n'existe plus :

GET /my-index/_settings?flat_settings=true&filter_path=*.settings.index.routing.allocation*
GET /_cluster/settings?flat_settings=true&filter_path=**routing.allocation**

Si la règle est erronée, supprimez-la ou mettez-la à jour :

PUT /my-index/_settings
{
  "index.routing.allocation.require.box_type": null,
  "index.routing.allocation.include._name": null,
  "index.routing.allocation.exclude._name": null
}

Utilisez les clés exactes que vos paramètres montrent. Ne collez pas une réinitialisation large dans la production sans la lire ; les règles d'allocation sont parfois là pour une bonne raison, comme garder certaines données sur un niveau contrôlé par la conformité.

Quand le cluster est rouge

Le rouge mérite des mains plus lentes et de meilleures notes. La première question est de savoir si le shard primaire manquant a une copie récupérable quelque part.

Listez les shards primaires non assignés :

GET /_cat/shards?v&h=index,shard,prirep,state,unassigned.reason | grep ' p UNASSIGNED'

Ensuite, vérifiez quels nœuds sont présents :

GET /_cat/nodes?v&h=name,ip,roles,master,uptime,heap.percent,disk.avail

Si un nœud est manquant, votre meilleur chemin de récupération est souvent de ramener ce nœud. Vérifiez le service, le montage du disque, le réseau de l'hôte, les certificats et les journaux sur le nœud manquant. Un nœud qui a perdu l'accès à son chemin de données peut démarrer comme un nœud vide différent, ce qui n'aide pas à récupérer le shard primaire.

Sur le nœud Elasticsearch, les journaux montrent généralement la vraie défaillance plus tôt que les API. Recherchez des messages concernant des échecs de verrouillage de shard, des fichiers d'index corrompus, la découverte du maître, des erreurs de handshake TLS, des systèmes de fichiers en lecture seule, ou des changements de rôle de nœud. Une défaillance courante dans le monde réel est un redémarrage de nœud après qu'un disque a été remonté sous un chemin différent. Elasticsearch démarre, mais le chemin de données est vide, donc le cluster manque toujours de la copie de shard dont il a besoin.

Exécutez l'explication d'allocation pour le primaire :

GET /_cluster/allocation/explain?pretty
{
  "index": "orders-2026.05.24",
  "shard": 2,
  "primary": true
}

Si l'explication dit qu'aucune copie de shard valide ne peut être trouvée, arrêtez-vous et vérifiez les snapshots avant de faire quoi que ce soit de destructeur :

GET /_snapshot/_all
GET /_snapshot/my-repository/_all?verbose=false

Restaurer un snapshot est généralement plus sûr que d'allouer un primaire vide. Un primaire vide crée un nouveau shard vierge pour cet ID de shard. Ce n'est pas une opération de réparation. Cela dit à Elasticsearch : "J'accepte que les anciennes données pour ce shard soient perdues."

La commande de dernier recours ressemble à ceci :

POST /_cluster/reroute
{
  "commands": [
    {
      "allocate_empty_primary": {
        "index": "orders-2026.05.24",
        "shard": 2,
        "node": "es-data-03",
        "accept_data_loss": true
      }
    }
  ]
}

Utilisez-la seulement après avoir confirmé qu'il n'y a pas de copie de nœud utilisable et aucun snapshot que vous pouvez restaurer. En cas d'incident, notez qui a approuvé ce choix et quel index et shard ont été affectés. Le débogage futur est beaucoup plus facile lorsque la décision de perte de données est explicite.

Cas qui ressemblent à des problèmes d'allocation mais qui sont vraiment des problèmes de cluster

Parfois, les shards ne sont pas assignés parce que le cluster ne peut pas maintenir une appartenance stable. Si les nœuds éligibles au maître ne peuvent pas se parler, le maître élu peut changer à plusieurs reprises, et l'allocation va s'agiter ou s'arrêter. Vérifiez la stabilité du maître :

GET /_cat/master?v
GET /_cat/nodes?v&h=name,roles,master,ip

Si le maître change souvent, inspectez la fiabilité du réseau, le DNS, les certificats des nœuds et les paramètres de découverte. Pour les clusters Elasticsearch modernes, cluster.initial_master_nodes est destiné au bootstrap initial du cluster, pas un paramètre à laisser comme béquille de découverte pour toujours. discovery.seed_hosts doit pointer vers des hôtes seed appropriés, et tous les nœuds doivent utiliser le même nom de cluster et des paramètres de sécurité compatibles.

Une pression JVM élevée peut également provoquer des symptômes d'allocation. Un nœud de données bloqué dans de longues pauses de garbage collection peut quitter et rejoindre le cluster du point de vue du maître. Cela peut créer des shards non assignés même si la machine n'a jamais complètement planté.

Vérifiez le tas et les journaux de garbage collection :

GET /_cat/nodes?v&h=name,heap.percent,ram.percent,cpu,load_1m,node.role
GET /_nodes/stats/jvm?filter_path=nodes.*.jvm.mem,nodes.*.jvm.gc

Si le tas est constamment élevé, n'augmentez pas aveuglément le tas. Elasticsearch fonctionne généralement mieux lorsque le tas laisse suffisamment de mémoire pour le cache du système de fichiers. Recherchez des agrégations surdimensionnées, une utilisation intensive de fielddata, trop de shards, une indexation agressive, ou des requêtes qui nécessitent de meilleures mappings.

Le nombre de shards peut être la cause silencieuse derrière de nombreux problèmes de santé. Un cluster avec de nombreux petits shards passe trop d'efforts à suivre les métadonnées et à déplacer les shards. Utilisez :

GET /_cat/indices?v&h=index,pri,rep,docs.count,store.size,pri.store.size&s=pri:desc
GET /_cluster/stats?filter_path=indices.shards,indices.count,nodes.count

Si chaque index de journal quotidien a de nombreux shards primaires mais peu de données, corrigez le modèle d'index pour les futurs index. Ensuite, envisagez des plans de shrink, rollover ou reindex pour les données existantes.

Un ordre de triage pratique

Quand quelqu'un dit "Elasticsearch est rouge", j'utilise cet ordre :

1. Confirmez la santé avec _cluster/health.
2. Listez les shards non assignés avec _cat/shards.
3. Séparez les échecs primaires des échecs de réplica.
4. Exécutez _cluster/allocation/explain sur un shard représentatif.
5. Vérifiez si tous les nœuds attendus sont présents.
6. Vérifiez les seuils d'eau du disque et les règles d'allocation.
7. Pour les primaires rouges, essayez de récupérer le nœud manquant ou restaurez à partir d'un snapshot avant d'envisager l'allocation de primaire vide.
8. Après que le cluster soit devenu vert, trouvez la cause qui l'a rendu malsain en premier lieu.

Cette dernière étape est importante. Un cluster peut devenir vert après avoir ajouté du disque, redémarré un nœud ou réduit les réplicas, mais le même incident reviendra si la rétention ILM est erronée, le nombre de shards est trop élevé, les nœuds sont sous-dimensionnés, ou un processus de déploiement continue de modifier les attributs des nœuds.

Le dépannage de la santé du cluster consiste moins à mémoriser une commande magique qu'à refuser de deviner. Elasticsearch expose la décision d'allocation. Lisez-la, vérifiez-la par rapport aux paramètres du nœud et de l'index, et choisissez la plus petite correction qui correspond au bloqueur réel.

Après que le cluster soit redevenu vert

Ne fermez pas l'incident simplement parce que la couleur a changé. Vert signifie seulement que les shards sont assignés maintenant. Cela ne prouve pas que le cluster est suffisamment sain pour le prochain pic de trafic, cycle de croissance du disque ou redémarrage de nœud. J'aime capturer une courte note post-action pendant que les détails sont encore frais : quels indices ont été affectés, quels nœuds étaient impliqués, quelle règle d'allocation a bloqué la récupération, et quelle commande ou changement d'infrastructure l'a corrigée.

Vérifiez si la correction a créé un nouveau risque. Si vous avez réduit les réplicas pour transformer le jaune en vert, enregistrez que l'index a maintenant moins de redondance. Si vous avez augmenté les seuils d'eau du disque, ajoutez un rappel pour les abaisser après l'ajout de capacité. Si vous avez restauré un snapshot, vérifiez que l'index restauré a les alias et les paramètres d'écriture attendus avant que les applications ne reprennent les écritures normales.

Quelques vérifications rapides aident à rattraper le travail inachevé :

GET /_cat/recovery?v&active_only=true
GET /_cat/pending_tasks?v
GET /_cat/aliases?v
GET /_cluster/health?wait_for_status=green&timeout=30s

pending_tasks ne devrait pas croître indéfiniment. La récupération devrait finalement se vider. Les alias sont importants car restaurer un index sous un nom différent peut laisser l'application écrire sur l'ancienne cible cassée ou lire seulement une partie des données prévues.

Vérifiez également les blocs d'écriture après les incidents de disque :

GET /*/_settings?filter_path=*.settings.index.blocks*

Si Elasticsearch a défini un bloc de crue, supprimez-le seulement après que la pression sur le disque soit corrigée :

PUT /my-index/_settings
{
  "index.blocks.read_only_allow_delete": null
}

Le travail de prévention le plus utile est généralement ennuyeux : des snapshots fonctionnels, des restaurations testées, une rétention ILM réaliste, suffisamment de marge sur le disque, et des nombres de shards qui correspondent à la taille du cluster. Un cluster avec des snapshots fiables et un dimensionnement de shards sain est beaucoup plus facile à récupérer qu'un cluster avec des commandes d'urgence astucieuses et aucun chemin de restauration.

Ce qu'il ne faut pas faire lors des incidents de santé

Ne redémarrez pas tous les nœuds à la fois. C'est tentant quand le cluster semble malsain, mais une approche progressive et observée est plus sûre. Redémarrer des nœuds sains peut supprimer des copies de shards dont Elasticsearch a besoin pour la récupération. Si vous devez redémarrer, faites-le un nœud à la fois et attendez que le cluster se stabilise entre les étapes.

Ne désactivez pas l'allocation et ne l'oubliez pas. Les changements temporaires d'allocation sont courants pendant la maintenance, mais un paramètre oublié peut laisser des réplicas non assignés longtemps après la fin de la fenêtre de maintenance. Vérifiez toujours les paramètres persistants et transitoires :

GET /_cluster/settings?flat_settings=true&include_defaults=false

Ne supprimez pas les index basés uniquement sur la taille. Les grands index peuvent être critiques pour l'entreprise. Les petits index peuvent être sûrs à supprimer. Liez le nettoyage à la politique de rétention, aux snapshots et à la propriété de l'application. En cas de panne réelle, le nettoyage sûr le plus rapide consiste généralement à supprimer les index de journaux ou de métriques connus comme expirés, plutôt que de deviner à partir d'une liste triée par taille.

Ne supposez pas que Kibana et Elasticsearch utilisent le même langage pour le problème. Kibana peut montrer un statut rouge large tandis que les API Elasticsearch montrent le shard non assigné précis. Utilisez l'interface utilisateur pour la visibilité, mais utilisez les API pour la décision.