Dépannage des échecs courants d'allocation de shards Elasticsearch
Apprenez à diagnostiquer et résoudre les échecs courants d'allocation de shards Elasticsearch. Ce guide couvre l'identification des shards non attribués, le diagnostic de problèmes tels que les erreurs d'espace disque, l'indisponibilité des nœuds et le filtrage d'allocation, et fournit des solutions concrètes et des bonnes pratiques pour maintenir un cluster Elasticsearch sain.
Dépannage des échecs courants d'allocation de shards Elasticsearch
Les échecs d'allocation de shards sont le moment où Elasticsearch cesse d'être abstrait. La santé du cluster passe au jaune ou au rouge, les recherches commencent à renvoyer des résultats partiels, l'indexation ralentit, et l'équipe doit déterminer si le problème vient du disque, d'un nœud manquant, d'une mauvaise règle d'allocation ou de données de shard endommagées.
L'erreur que je vois le plus souvent est de traiter tous les shards non attribués de la même manière. Un shard réplica retardé après un redémarrage planifié n'est pas la même urgence qu'un shard primaire non attribué pour l'index principal des commandes. Commencez par trouver quel shard est non attribué, s'il est primaire ou réplica, et ce qu'Elasticsearch dit à propos de la décision d'allocation.
Lire correctement le signal de santé
Commencez par la santé du cluster :
GET /_cluster/health?pretty
Les champs importants sont status, active_primary_shards, active_shards, relocating_shards, initializing_shards, unassigned_shards et delayed_unassigned_shards.
Jaune signifie que tous les shards primaires sont attribués, mais qu'un ou plusieurs réplicas ne le sont pas. Vos données devraient toujours être disponibles, mais la redondance est réduite.
Rouge signifie qu'un ou plusieurs shards primaires ne sont pas attribués. Les données de ces shards sont indisponibles à moins qu'Elasticsearch ne puisse promouvoir un réplica, récupérer le nœud qui avait le shard, ou restaurer à partir d'un snapshot.
Si relocating_shards ou initializing_shards est non nul, le cluster est peut-être déjà en train de guérir. N'interrompez pas une récupération normale simplement parce que la couleur est temporairement jaune.
Lister les shards non attribués
Utilisez _cat/shards pour voir le problème exact :
GET /_cat/shards?v&h=index,shard,prirep,state,node,unassigned.reason&s=state,index
Recherchez UNASSIGNED. La colonne prirep vous indique si le shard est primaire (p) ou réplica (r). La colonne unassigned.reason donne une raison courte comme NODE_LEFT, INDEX_CREATED, CLUSTER_RECOVERED ou ALLOCATION_FAILED.
Pour un grand cluster, affinez :
GET /_cat/shards/logs-*?v&h=index,shard,prirep,state,node,unassigned.reason
Une fois que vous avez l'index, le numéro de shard et le drapeau primaire/réplica, demandez à Elasticsearch l'explication réelle.
Utiliser l'API d'explication d'allocation
Pour tout shard actuellement non attribué :
GET /_cluster/allocation/explain
{}
Pour un shard spécifique :
GET /_cluster/allocation/explain
{
"index": "logs-2026.05.24",
"shard": 0,
"primary": false
}
Lisez can_allocate, allocate_explanation, unassigned_info et node_allocation_decisions. Les décisions de nœud sont particulièrement utiles car elles montrent pourquoi chaque nœud a été rejeté. Les décideurs courants incluent les seuils de disque, les règles de même shard, les filtres d'allocation, les règles de connaissance et les limites de shards par nœud.
Si la sortie indique no_valid_shard_copy pour un primaire, traitez-la sérieusement. Elasticsearch ne voit actuellement aucune copie utilisable de ce shard primaire.
Cause 1 : pas assez de nœuds appropriés
Un cluster simple à un seul nœud avec un réplica sera jaune pour toujours. Elasticsearch ne placera pas un réplica sur le même nœud que son primaire. Un cluster à trois nœuds avec un index configuré pour deux réplicas a besoin de trois nœuds de données appropriés. Si la connaissance d'allocation exige que les copies soient réparties entre les zones, vous avez également besoin d'assez de nœuds dans les zones requises.
Vérifiez les paramètres de réplica :
GET /my-index/_settings?filter_path=*.settings.index.number_of_replicas
S'il s'agit d'un environnement de laboratoire ou temporaire, réduisez les réplicas :
PUT /my-index/_settings
{
"index": {
"number_of_replicas": 0
}
}
Pour la production, la meilleure réponse est généralement d'ajouter des nœuds de données appropriés ou d'ajuster un nombre de réplicas irréaliste. Réduire les réplicas supprime la redondance.
Cause 2 : seuils de disque
La pression sur le disque est l'un des bloqueurs d'allocation les plus courants. Elasticsearch utilise des seuils de disque pour éviter de remplir les nœuds. Lorsque les nœuds dépassent les seuils, Elasticsearch peut cesser de leur attribuer des shards et peut déplacer les shards ailleurs.
Vérifiez l'allocation et l'utilisation du disque :
GET /_cat/allocation?v
GET /_cat/nodes?v&h=name,ip,disk.used_percent,disk.avail,heap.percent,ram.percent,node.role
La sortie d'explication d'allocation peut indiquer qu'un nœud est au-dessus du seuil de disque bas ou haut. Si un index a atteint des conditions de niveau d'inondation, Elasticsearch peut également définir un bloc d'écriture sur les index affectés.
Les bonnes solutions sont des correctifs de capacité : supprimez les anciens index après avoir confirmé les snapshots, ajoutez du disque, ajoutez des nœuds de données, déplacez les données vers un autre niveau, ou raccourcissez la rétention via la gestion du cycle de vie des index.
Modifier les seuils peut être raisonnable dans une urgence contrôlée, mais ce n'est pas un plan de capacité. Si chaque nœud de données est presque plein, augmenter les seuils laisse simplement le cluster fonctionner plus près de la panne.
Après avoir libéré de l'espace suite à un événement de niveau d'inondation, vérifiez la présence d'un bloc en lecture seule :
GET /my-index/_settings?filter_path=*.settings.index.blocks.write,*.settings.index.blocks.read_only_allow_delete
Supprimez le bloc uniquement après avoir résolu la pression sur le disque :
PUT /my-index/_settings
{
"index.blocks.read_only_allow_delete": null
}
Cause 3 : allocation désactivée après maintenance
Les équipes désactivent souvent l'allocation pendant une maintenance roulante, puis oublient de la réactiver.
Vérifiez les paramètres du cluster :
GET /_cluster/settings?include_defaults=true&pretty
Recherchez cluster.routing.allocation.enable. Les valeurs incluent all, primaries, new_primaries et none. Si c'est none, les réplicas et éventuellement d'autres mouvements de shards ne s'alloueront pas normalement.
Réactivez l'allocation :
PUT /_cluster/settings
{
"persistent": {
"cluster.routing.allocation.enable": "all"
}
}
Vérifiez également les paramètres transient. Un paramètre de maintenance transitoire peut encore affecter le cluster même si la section persistante semble correcte.
Cause 4 : filtres d'allocation restrictifs
Les filtres au niveau de l'index peuvent épingler un index à certains nœuds :
GET /my-index/_settings?filter_path=*.settings.index.routing.allocation.*
Les filtres au niveau du cluster peuvent exclure des nœuds de l'allocation :
GET /_cluster/settings?include_defaults=true&filter_path=**.cluster.routing.allocation.*
Les attributs de nœud comptent aussi :
GET /_cat/nodeattrs?v
Un échec typique ressemble à ceci : un index nécessite box_type: hot, mais les nœuds chauds ont été remplacés et les nouveaux nœuds n'ont pas node.attr.box_type: hot. Elasticsearch suit la règle exactement ; la règle est maintenant erronée.
Pour supprimer les filtres d'index trop restrictifs :
PUT /my-index/_settings
{
"index.routing.allocation.require.box_type": null,
"index.routing.allocation.include.box_type": null,
"index.routing.allocation.exclude.box_type": null
}
Utilisez les noms de paramètres exacts présents dans votre index. N'effacez pas aveuglément les règles d'allocation si elles encodent des exigences réelles de zone ou de niveau.
Cause 5 : allocation retardée après le départ d'un nœud
Lorsqu'un nœud part, Elasticsearch peut retarder l'allocation des shards réplica car le nœud pourrait revenir rapidement. Cela évite de copier de gros shards sur le réseau lors d'un redémarrage normal.
Vérifiez les shards retardés :
GET /_cluster/health?pretty
Si delayed_unassigned_shards est supérieur à zéro et que le nœud est attendu de retour, attendre peut être la meilleure action. Vous pouvez également inspecter les paramètres de l'index :
GET /my-index/_settings?filter_path=*.settings.index.unassigned.node_left.delayed_timeout
La valeur par défaut est généralement d'une minute, mais vérifiez toujours votre cluster et votre version. Certaines équipes l'augmentent pour les redémarrages roulants planifiés de gros shards. Ne la rendez pas si longue que de véritables échecs laissent les réplicas manquants pendant un temps inconfortable.
Cause 6 : trop de shards sur un nœud
index.routing.allocation.total_shards_per_node peut limiter le nombre de shards d'un même index pouvant résider sur le même nœud. Les limites de shards au niveau du cluster peuvent également s'appliquer. Ces paramètres sont utiles, mais ils peuvent bloquer l'allocation dans les petits clusters.
Vérifiez les paramètres de l'index :
GET /my-index/_settings?filter_path=*.settings.index.routing.allocation.total_shards_per_node
Si vous avez cinq shards primaires, un réplica, deux nœuds de données et une faible limite par nœud, Elasticsearch peut n'avoir aucun placement légal. Corrigez la limite, ajoutez des nœuds ou reconcevez le nombre de shards.
Cause 7 : pas de copie valide d'un primaire
C'est le cas effrayant. L'explication d'allocation peut signaler qu'il n'y a pas de copie de shard valide pour un primaire. Peut-être que le seul nœud avec le primaire est parti. Peut-être que le disque a échoué. Peut-être que les données du shard sont corrompues.
D'abord, essayez de récupérer le nœud manquant s'il est attendu de retour. Vérifiez les journaux système, les journaux Elasticsearch, la santé du disque et la connectivité réseau. Si un réplica valide existe, Elasticsearch devrait normalement le promouvoir.
Si aucune copie valide n'existe, restaurez à partir d'un snapshot :
POST /_snapshot/my_repository/snapshot_name/_restore
{
"indices": "affected-index"
}
Si les données peuvent être reconstruites à partir d'un système source et que vous acceptez de perdre le contenu du shard, allocate_empty_primary est disponible, mais c'est une opération de perte de données :
POST /_cluster/reroute
{
"commands": [
{
"allocate_empty_primary": {
"index": "affected-index",
"shard": 0,
"node": "target-node",
"accept_data_loss": true
}
}
]
}
N'utilisez pas cela pour "rendre le cluster vert" à moins d'avoir consciemment décidé que les données manquantes sont perdues ou reconstructibles.
Surveiller la récupération
Après avoir effectué une modification, surveillez la progression :
GET /_cat/recovery?v&active_only=true
GET /_cat/shards?v&h=index,shard,prirep,state,node,unassigned.reason
GET /_cluster/health?pretty
Les gros shards prennent du temps. Si les comptes d'octets bougent dans _cat/recovery, le cluster travaille. Si rien ne change, vérifiez à nouveau l'explication d'allocation. La décision d'Elasticsearch peut avoir changé après votre premier correctif, révélant le prochain bloqueur.
Prévention qui aide vraiment
Surveillez le disque avant d'atteindre les seuils. Alertez sur les tendances, pas seulement sur les disques pleins.
Utilisez ILM ou des flux de données pour les journaux et les métriques afin que la rétention soit automatique.
Gardez les snapshots à jour et testez les restaurations. Un snapshot que vous n'avez jamais restauré n'est qu'un espoir.
Gardez les tailles de shards et les nombres de shards raisonnables. Trop de petits shards rendent l'allocation et la récupération plus lentes que le volume de données ne le suggère.
Documentez les filtres d'allocation et les attributs de nœud. Six mois plus tard, quelqu'un remplacera un nœud et oubliera l'attribut qui rendait un index allouable.
Traitez le jaune comme un avertissement et le rouge comme un incident. Le jaune peut être acceptable pendant la maintenance, mais il ne devrait pas devenir un bruit de fond. Le rouge signifie qu'au moins un shard primaire est indisponible, et plus vous attendez, moins vous aurez d'options de récupération faciles.
Une liste de contrôle sur le terrain pour les incidents
Lorsque l'allocation de shards échoue, collectez les mêmes preuves à chaque fois. Cela empêche l'équipe de rebondir entre les théories.
Exécutez :
GET /_cluster/health?pretty
GET /_cat/nodes?v&h=name,ip,roles,master,disk.used_percent,heap.percent,ram.percent
GET /_cat/shards?v&h=index,shard,prirep,state,node,unassigned.reason&s=state,index
GET /_cat/allocation?v
GET /_cat/recovery?v&active_only=true
GET /_cluster/settings?include_defaults=true&pretty
Ensuite, exécutez l'explication d'allocation pour un shard non attribué représentatif. S'il y en a beaucoup, regroupez-les par raison. Dix réplicas non attribués bloqués par des seuils de disque sont un problème. Trois primaires avec no_valid_shard_copy sont un problème différent.
Notez si les données affectées peuvent être reconstruites. Les journaux d'une file d'attente en amont, les métriques des agents et les index de recherche dérivés peuvent être récupérables à partir des systèmes sources. Le contenu créé par l'utilisateur ou les enregistrements de conformité peuvent ne pas l'être. Les commandes de récupération doivent suivre cette réalité commerciale.
Quand attendre et quand agir
Attendez lorsque la récupération progresse activement, que le nœud manquant est attendu de retour bientôt, ou que l'allocation retardée fait exactement ce que vous avez configuré. Vous pouvez vérifier la progression avec _cat/recovery ; des comptes d'octets et de fichiers en mouvement sont de bons signes.
Agissez lorsque l'explication d'allocation montre un bloqueur permanent : pas de nœuds appropriés, seuils de disque sur chaque nœud, allocation désactivée, attributs de nœud manquants, ou pas de copie de shard valide. Attendre ne corrigera pas une règle qui rejette chaque nœud.
Escaladez rapidement lorsque des shards primaires ne sont pas attribués pour des index importants. Les échecs de réplica réduisent la sécurité. Les échecs de primaire réduisent la disponibilité.
Éviter de ralentir la récupération
Les grandes récupérations entrent en concurrence avec la recherche et l'indexation normales. Ajouter trop de nœuds à la fois, redémarrer plus de nœuds ou augmenter la concurrence de récupération sans vérifier la capacité du disque et du réseau peut rendre le cluster moins stable.
Si vous ajustez les paramètres de récupération, faites-le délibérément et enregistrez les valeurs d'origine. Des paramètres tels que les récupérations simultanées peuvent aider dans certains environnements et nuire dans d'autres. Une récupération plus rapide sur le papier peut surcharger les disques et augmenter la latence des requêtes au point que les utilisateurs subissent une panne pire.
Surveillez les nœuds chauds. L'allocation peut techniquement réussir tout en plaçant trop de travail sur un nœud en raison des tailles de shards, des règles de niveau ou de l'utilisation inégale du disque. Utilisez _cat/allocation, les statistiques de nœud et votre système de surveillance pour confirmer que le cluster est équilibré après la résolution de la panne immédiate.
Correctifs après action
La plupart des incidents d'allocation de shards ont une histoire de prévention. Les incidents de seuil de disque pointent vers la rétention, ILM ou la planification de capacité. Les incidents de filtre d'allocation pointent vers une documentation de runbook manquante. Les incidents sans copie valide pointent vers les snapshots et la relecture en amont. La récupération lente pointent vers le dimensionnement des shards et le matériel.
Ne fermez pas l'incident simplement parce que la santé est verte. Supprimez les modifications temporaires de réplica, restaurez les intervalles d'actualisation normaux, réactivez l'allocation si elle a été modifiée, vérifiez les snapshots et ajoutez l'alerte qui aurait détecté le problème plus tôt.
Cas particulier : index fermés et cachés
Parfois, un index ne s'alloue pas parce qu'il est fermé, caché ou fait partie d'une fonctionnalité système dont vous ne réalisiez pas que vous touchiez. Soyez prudent avec les commandes génériques à large spectre lorsque des index système sont présents. Dans les clusters modernes, la sécurité, Kibana, les transformations et d'autres fonctionnalités de la pile peuvent maintenir leurs propres index.
Utilisez des motifs étroits et incluez les index cachés uniquement lorsque vous avez l'intention de les inspecter. Si un index système a des problèmes d'allocation, vérifiez les journaux du composant de pile associé ainsi que ceux d'Elasticsearch. Par exemple, un problème d'index d'objets enregistrés de Kibana peut se manifester comme un problème d'allocation de shards Elasticsearch et comme des échecs de démarrage de Kibana.
La règle est la même qu'avec les données utilisateur : identifiez l'index exact, comprenez à qui il appartient, puis choisissez le correctif. Ne supprimez pas et ne forcez pas l'allocation d'un index système simplement pour effacer un état de santé rouge à moins de comprendre l'impact au niveau du produit.