Problèmes d'allocation des shards Elasticsearch : Causes et solutions

Les clusters Elasticsearch sont conçus pour la résilience et la haute disponibilité, reposant fortement sur la distribution et l'allocation correctes des shards entre les nœuds. Lorsqu'un shard ne parvient pas à passer d'un état UNASSIGNED ou INACTIVE à un shard primaire ou réplica actif, l'indicateur de santé du cluster passe souvent au jaune ou au rouge. Comprendre pourquoi les shards ne s'allouent pas est crucial pour maintenir un moteur de recherche sain, performant et disponible.

Ce guide explore en profondeur les causes courantes des échecs d'allocation des shards — des ressources insuffisantes du cluster aux paramètres mal configurés — et fournit des solutions concrètes et pratiques pour résoudre ces problèmes, garantissant que vos données sont correctement indexées et consultables.

Comprendre les états des shards et l'allocation

Avant de dépanner, il est essentiel de savoir ce qu'Elasticsearch essaie de faire. Les shards sont l'unité fondamentale de distribution dans Elasticsearch. Ils peuvent exister dans plusieurs états :

STARTED : Le shard est actif et traite les requêtes (Primaire ou Réplica).
RELOCATING : Le shard est en cours de déplacement d'un nœud à un autre (lors du rééquilibrage ou de l'ajout/suppression de nœuds).
INITIALIZING : Un nouveau shard réplica est créé à partir du shard primaire.
UNASSIGNED : Le shard existe dans les métadonnées de l'état du cluster mais n'est alloué à aucun nœud, souvent parce que le nœud requis est indisponible ou que les critères ne sont pas remplis.

La santé du cluster est déterminée par la présence de shards non alloués :

Vert : Tous les shards primaires et répliques sont alloués.
Jaune : Tous les shards primaires sont alloués, mais un ou plusieurs shards répliques ne sont pas alloués.
Rouge : Un ou plusieurs shards primaires ne sont pas alloués (indiquant un risque de perte de données si le nœud hébergeant le shard primaire tombe en panne).

Causes courantes des échecs d'allocation des shards

L'allocation des shards est gérée par la logique de décision du cluster (allocation decider), qui vérifie de nombreux facteurs avant de placer un shard. Un échec découle généralement d'une violation d'un de ces points de décision.

1. Ressources insuffisantes du cluster

C'est peut-être la cause la plus fréquente des blocages d'allocation, surtout dans les environnements dynamiques.

Seuils d'espace disque

Elasticsearch arrête automatiquement d'allouer de nouveaux shards (primaires et répliques) à un nœud si son utilisation du disque dépasse les seuils prédéfinis. Par défaut, l'allocation s'arrête à 85 % d'utilisation et empêche complètement l'allocation à 90 %.

Seuils par défaut (Vérifier elasticsearch.yml ou les paramètres du cluster) :

Paramètre	Valeur par défaut	Description
`cluster.routing.allocation.disk.watermark.low`	85 %	Seuil où le nœud est considéré comme relativement plein.
`cluster.routing.allocation.disk.watermark.high`	90 %	Seuil où l'allocation vers le nœud est bloquée.
`cluster.routing.allocation.disk.watermark.flood_stage`	95 %	L'allocation s'arrête complètement et les opérations d'indexation/écriture peuvent échouer.

Solution : Vérifiez l'utilisation du disque sur tous les nœuds et libérez de l'espace ou ajoutez plus d'espace disque aux nœuds qui dépassent le seuil élevé.

Pression mémoire et CPU

Bien que moins fréquents que les problèmes de disque, une utilisation mémoire élevée persistante ou une charge CPU élevée sur les nœuds peuvent empêcher l'attribution de nouveaux shards, car les décideurs d'allocation préfèrent les nœuds disposant d'une marge opérationnelle suffisante.

2. Rôles des nœuds et incompatibilité d'attributs

Les déploiements Elasticsearch modernes utilisent souvent des nœuds masters, d'ingestion ou de coordination dédiés. Les shards ne seront pas alloués aux nœuds qui ne répondent pas aux critères requis.

Règles d'allocation incompatibles

Si vous avez configuré des paramètres d'index spécifiques exigeant que les shards soient placés sur des nœuds marqués avec certains attributs (par exemple, SSD rapides), mais qu'aucun nœud disponible ne correspond à ce marquage, les shards resteront non alloués.

Exemple : Un index créé avec index.routing.allocation.require.box_type: high_io ne s'allouera que sur des nœuds configurés explicitement avec ce paramètre.

Solution : Vérifiez les règles d'allocation (allocation.require, allocation.include, allocation.exclude) pour l'index concerné et assurez-vous que les nœuds possèdent les bons paramètres node.attr.

3. Stabilité de l'état du cluster et échecs d'allocation primaire (Santé Rouge)

Si les shards primaires ne sont pas alloués (cluster ROUGE), cela signifie que le nœud qui détenait la dernière copie primaire a échoué ou a quitté le cluster, et qu'aucun shard réplica disponible ne peut être promu au rang de primaire.

Scénarios courants :
* Un nœud détenant la seule copie primaire plante de manière inattendue.
* Le nœud contenant le shard primaire est explicitement retiré du cluster avant que les répliques n'aient été correctement copiées.

Solution : Si le nœud défaillant ne peut pas être récupéré rapidement, vous devrez peut-être forcer manuellement l'allocation en contournant le blocage primaire, mais cela comporte un risque élevé de perte de données pour ces shards spécifiques.

4. Limites et quotas de shards

Elasticsearch impose des limites pour empêcher la création incontrôlée de shards qui pourrait déstabiliser le cluster.

Nombre maximal de shards par nœud

Si un nœud a atteint son nombre maximal de shards configuré (cluster.routing.allocation.total_shards_per_node), aucun shard supplémentaire ne lui sera attribué, même si de l'espace disque est disponible.

Solution : Augmentez la limite total_shards_per_node (utilisez la prudence, car trop de shards par nœud peuvent dégrader les performances) ou ajoutez plus de nœuds au cluster pour répartir la charge.

Diagnostic des échecs d'allocation : L'API Allocation Explain

L'API Allocation Explain est l'outil le plus puissant pour diagnostiquer pourquoi un shard spécifique ne s'alloue pas. Elle simule le processus de prise de décision des décideurs d'allocation.

Pour l'utiliser, vous avez besoin du nom de l'index, du numéro du shard et du nœud sur lequel le shard devrait être (si connu, ou omettez le nœud pour vérifier toutes les possibilités).

Exemple d'utilisation (Vérification du shard 0 de l'index `my_data`) :

GET /_cluster/allocation/explain?pretty
{
  "index": "my_data",
  "shard": 0,
  "primary": true
}

La réponse détaillera chaque décision d'allocation prise pour ce shard, indiquant explicitement quelle règle a été violée (par exemple, "[disk exceeding high watermark on node X]").

Lecture de la sortie

Portez une attention particulière au champ explanation et à la section deciders. Si un décideur renvoie false, le message correspondant explique la contrainte violée (par exemple, utilisation du disque, incompatibilité du nombre de répliques ou exclusion d'attributs de nœud).

Étapes de dépannage et commandes

Face à un état UNASSIGNED, suivez cette séquence de dépannage prioritaire :

Étape 1 : Vérifier la santé du cluster et les shards non alloués

Tout d'abord, ayez une vue d'ensemble.

GET /_cluster/health?pretty
GET /_cat/shards?h=index,shard,prirep,state,unassigned.reason,node

Regardez spécifiquement la colonne unassigned.reason de la sortie de l'API cat. Cela fournit souvent des indices immédiats (par exemple, CLUSTER_RECOVERED, NODE_LEFT, INDEX_CREATED).

Étape 2 : Examiner l'espace disque

Si la raison pointe vers une pression disque, vérifiez l'utilisation réelle sur tous les nœuds.

GET /_cat/allocation?v&h=node,disk.used_percent,disk.avail,disk.total

Action : Si les nœuds approchent 90 % de capacité, commencez immédiatement à nettoyer les journaux, à réduire la rétention des index ou à ajouter de la capacité disque à ces nœuds.

Étape 3 : Utiliser Allocation Explain pour les cas complexes

Si la cause n'est pas une pression de ressources évidente, exécutez l'API Allocation Explain comme détaillé ci-dessus pour identifier les incompatibilités de configuration.

Étape 4 : Forcer manuellement l'allocation (À utiliser avec prudence)

Si un shard primaire est UNASSIGNED (Santé Rouge) parce que le nœud d'origine est définitivement perdu, et que vous acceptez le risque de perdre les données écrites depuis l'existence du dernier shard primaire, vous pouvez forcer le cluster à promouvoir une réplique (si elle existe).

Attention : Cette commande supprime définitivement l'enregistrement du shard primaire non alloué. Utilisez cette commande uniquement si vous ne pouvez pas récupérer le nœud hébergeant le shard primaire.

POST /_cluster/reroute
{
  "commands": [
    {
      "allocate_stale_primary": {
        "index": "nom_index",
        "shard": 0,
        "node": "nom_du_noeud_avec_replique",
        "accept_data_loss": true
      }
    }
  ]
}

Étape 5 : Gérer les répliques bloquées (Santé Jaune)

Si seules les répliques ne sont pas allouées (Santé Jaune) en raison d'un nombre insuffisant de nœuds ou d'espace disque, il suffit de corriger la contrainte de ressource sous-jacente (ajouter des nœuds ou libérer de l'espace disque) pour que les répliques s'allouent automatiquement une fois que les décideurs le permettent.

Si vous devez continuer sans ajouter de ressources, vous pouvez désactiver temporairement l'allocation des répliques pour l'index :

PUT /mon_index/_settings
{
  "index.blocks.write": true, 
  "index.number_of_replicas": 0
}

Après cette modification, la santé du cluster devrait passer à Vert (car zéro réplique est maintenant alloué avec succès). N'oubliez pas de réactiver les répliques plus tard ("index.number_of_replicas": 1).

Bonnes pratiques pour prévenir les problèmes d'allocation

Surveillez rigoureusement les seuils d'espace disque : Mettez en place des alertes basées sur le seuil high (90 %) pour intervenir avant que l'allocation ne soit complètement bloquée.
Maintenez la diversité des nœuds : Assurez-vous d'avoir suffisamment de nœuds physiques ou virtuels pour qu'en cas de défaillance d'un nœud, il reste suffisamment de nœuds disponibles répondant aux exigences d'attributs pour héberger tous les primaires et les répliques requises.
Utilisez la conscience d'allocation (Allocation Awareness) : Pour les déploiements multi-zones ou multi-racks, configurez cluster.routing.allocation.awareness.attributes pour empêcher que toutes les copies d'un shard ne se retrouvent dans la même zone physique, atténuant ainsi les pannes à l'échelle d'une zone.
Définissez des nombres de répliques réalistes : Évitez de définir des nombres de répliques supérieurs au nombre de nœuds physiques que vous pouvez supporter, car cela garantit des répliques non allouées lors des maintenances mineures.

En gérant proactivement les ressources et en utilisant l'API Allocation Explain, les administrateurs peuvent diagnostiquer et résoudre rapidement les facteurs empêchant les shards Elasticsearch d'atteindre une allocation optimale.