Risoluzione dei problemi comuni di allocazione degli shard in Elasticsearch

I fallimenti di allocazione degli shard sono il punto in cui Elasticsearch smette di essere astratto. La salute del cluster diventa gialla o rossa, le ricerche iniziano a restituire risultati parziali, l'indicizzazione rallenta e il team deve capire se il problema è il disco, un nodo mancante, una regola di allocazione errata o dati danneggiati dello shard.

L'errore che vedo più spesso è trattare ogni shard non assegnato allo stesso modo. Uno shard replica ritardato dopo un riavvio pianificato non è la stessa emergenza di uno shard primario non assegnato per l'indice principale degli ordini. Inizia trovando quale shard non è assegnato, se è primario o replica, e cosa dice Elasticsearch sulla decisione di allocazione.

Leggere correttamente il segnale di salute

Inizia con la salute del cluster:

GET /_cluster/health?pretty

I campi importanti sono status, active_primary_shards, active_shards, relocating_shards, initializing_shards, unassigned_shards e delayed_unassigned_shards.

Giallo significa che tutti gli shard primari sono assegnati, ma una o più repliche no. I tuoi dati dovrebbero essere ancora disponibili, ma la ridondanza è ridotta.

Rosso significa che uno o più shard primari non sono assegnati. I dati in quegli shard non sono disponibili a meno che Elasticsearch non possa promuovere una replica, recuperare il nodo che aveva lo shard o ripristinare da uno snapshot.

Se relocating_shards o initializing_shards è diverso da zero, il cluster potrebbe già stare guarendo. Non interrompere un recupero normale solo perché il colore è temporaneamente giallo.

Elencare gli shard non assegnati

Usa _cat/shards per vedere il problema esatto:

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

Cerca UNASSIGNED. La colonna prirep ti dice se lo shard è primario (p) o replica (r). La colonna unassigned.reason fornisce una breve ragione come NODE_LEFT, INDEX_CREATED, CLUSTER_RECOVERED o ALLOCATION_FAILED.

Per un cluster grande, restringi:

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

Una volta che hai l'indice, il numero dello shard e il flag primario/replica, chiedi a Elasticsearch la spiegazione reale.

Usare l'API di spiegazione dell'allocazione

Per qualsiasi shard attualmente non assegnato:

GET /_cluster/allocation/explain
{}

Per uno shard specifico:

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

Leggi can_allocate, allocate_explanation, unassigned_info e node_allocation_decisions. Le decisioni sui nodi sono particolarmente utili perché mostrano perché ogni nodo è stato rifiutato. I decisori comuni includono soglie del disco, regole dello stesso shard, filtri di allocazione, regole di consapevolezza e limiti di shard totali per nodo.

Se l'output dice no_valid_shard_copy per un primario, trattalo seriamente. Elasticsearch al momento non vede una copia utilizzabile di quello shard primario.

Causa 1: non abbastanza nodi adatti

Un semplice cluster a nodo singolo con una replica sarà giallo per sempre. Elasticsearch non metterà una replica sullo stesso nodo del suo primario. Un cluster a tre nodi con un indice configurato per due repliche ha bisogno di tre nodi dati adatti. Se la consapevolezza dell'allocazione dice che le copie devono essere distribuite tra le zone, hai anche bisogno di abbastanza nodi nelle zone richieste.

Controlla le impostazioni delle repliche:

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

Se questo è un ambiente di laboratorio o temporaneo, riduci le repliche:

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

Per la produzione, la risposta migliore è di solito aggiungere nodi dati adatti o regolare un numero di repliche irrealistico. Abbassare le repliche rimuove la ridondanza.

Causa 2: soglie del disco

La pressione del disco è uno dei blocchi di allocazione più comuni. Elasticsearch utilizza le soglie del disco per evitare di riempire i nodi. Quando i nodi superano le soglie, Elasticsearch può smettere di assegnare shard a loro e può spostare gli shard via.

Controlla l'allocazione e l'uso del disco:

GET /_cat/allocation?v
GET /_cat/nodes?v&h=name,ip,disk.used_percent,disk.avail,heap.percent,ram.percent,node.role

L'output di spiegazione dell'allocazione può dire che un nodo è sopra la soglia del disco bassa o alta. Se un indice ha raggiunto condizioni di flood-stage, Elasticsearch può anche impostare un blocco di scrittura sugli indici interessati.

Le buone soluzioni sono correzioni di capacità: eliminare vecchi indici dopo aver confermato gli snapshot, aggiungere disco, aggiungere nodi dati, spostare dati in un altro livello o accorciare la conservazione tramite Index Lifecycle Management.

Cambiare le soglie può essere ragionevole in un'emergenza controllata, ma non è un piano di capacità. Se ogni nodo dati è quasi pieno, alzare le soglie fa solo sì che il cluster funzioni più vicino al fallimento.

Dopo aver liberato spazio da un evento flood-stage, controlla la presenza di un blocco di sola lettura:

GET /my-index/_settings?filter_path=*.settings.index.blocks.write,*.settings.index.blocks.read_only_allow_delete

Rimuovi il blocco solo dopo che la pressione del disco è risolta:

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

Causa 3: allocazione disabilitata dopo la manutenzione

I team spesso disabilitano l'allocazione durante la manutenzione rolling, poi dimenticano di riattivarla.

Controlla le impostazioni del cluster:

GET /_cluster/settings?include_defaults=true&pretty

Cerca cluster.routing.allocation.enable. I valori includono all, primaries, new_primaries e none. Se è none, le repliche e possibilmente altri movimenti di shard non si allocheranno normalmente.

Riabilita l'allocazione:

PUT /_cluster/settings
{
  "persistent": {
    "cluster.routing.allocation.enable": "all"
  }
}

Controlla anche le impostazioni transient. Un'impostazione di manutenzione transiente può ancora influenzare il cluster anche se la sezione persistente sembra a posto.

Causa 4: filtri di allocazione restrittivi

I filtri a livello di indice possono fissare un indice a determinati nodi:

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

I filtri a livello di cluster possono escludere nodi dall'allocazione:

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

Anche gli attributi dei nodi contano:

GET /_cat/nodeattrs?v

Un fallimento tipico assomiglia a questo: un indice richiede box_type: hot, ma i nodi hot sono stati sostituiti e i nuovi nodi non hanno node.attr.box_type: hot. Elasticsearch sta seguendo la regola esattamente; la regola ora è sbagliata.

Per rimuovere filtri di indice eccessivamente restrittivi:

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
}

Usa i nomi esatti delle impostazioni presenti nel tuo indice. Non cancellare ciecamente le regole di allocazione se codificano requisiti reali di zona o livello.

Causa 5: allocazione ritardata dopo che un nodo se ne va

Quando un nodo se ne va, Elasticsearch può ritardare l'allocazione degli shard replica perché il nodo potrebbe tornare rapidamente. Questo evita di copiare grandi shard attraverso la rete durante un riavvio normale.

Controlla gli shard ritardati:

GET /_cluster/health?pretty

Se delayed_unassigned_shards è maggiore di zero e si prevede che il nodo torni, aspettare potrebbe essere la migliore azione. Puoi anche ispezionare le impostazioni dell'indice:

GET /my-index/_settings?filter_path=*.settings.index.unassigned.node_left.delayed_timeout

Il valore predefinito è comunemente un minuto, ma controlla sempre il tuo cluster e la versione. Alcuni team lo aumentano per riavvii rolling pianificati di grandi shard. Non renderlo così lungo che i fallimenti reali lascino le repliche mancanti per un tempo scomodo.

Causa 6: troppi shard su un nodo

index.routing.allocation.total_shards_per_node può limitare quanti shard di un indice possono vivere sullo stesso nodo. I limiti di shard a livello di cluster possono anche applicarsi. Queste impostazioni sono utili, ma possono bloccare l'allocazione in cluster piccoli.

Controlla le impostazioni dell'indice:

GET /my-index/_settings?filter_path=*.settings.index.routing.allocation.total_shards_per_node

Se hai cinque shard primari, una replica, due nodi dati e un limite basso per nodo, Elasticsearch potrebbe non avere un posizionamento legale. Correggi il limite, aggiungi nodi o riprogetta il numero di shard.

Causa 7: nessuna copia valida di un primario

Questo è il caso spaventoso. La spiegazione dell'allocazione può riportare che non c'è una copia valida dello shard per un primario. Forse l'unico nodo con il primario è sparito. Forse il disco è fallito. Forse i dati dello shard sono corrotti.

Prima, prova a recuperare il nodo mancante se si prevede che torni. Controlla i log di sistema, i log di Elasticsearch, la salute del disco e la connettività di rete. Se esiste una replica valida, Elasticsearch dovrebbe normalmente promuoverla.

Se non esiste una copia valida, ripristina da uno snapshot:

POST /_snapshot/my_repository/snapshot_name/_restore
{
  "indices": "affected-index"
}

Se i dati possono essere ricostruiti da un sistema sorgente e accetti di perdere il contenuto dello shard, allocate_empty_primary è disponibile, ma è un'operazione di perdita di dati:

POST /_cluster/reroute
{
  "commands": [
    {
      "allocate_empty_primary": {
        "index": "affected-index",
        "shard": 0,
        "node": "target-node",
        "accept_data_loss": true
      }
    }
  ]
}

Non usare questo per "rendere il cluster verde" a meno che tu non abbia deciso consapevolmente che i dati mancanti sono persi o ricostruibili.

Monitorare il recupero

Dopo aver apportato una modifica, monitora i progressi:

GET /_cat/recovery?v&active_only=true
GET /_cat/shards?v&h=index,shard,prirep,state,node,unassigned.reason
GET /_cluster/health?pretty

I grandi shard richiedono tempo. Se i conteggi di byte si muovono in _cat/recovery, il cluster sta funzionando. Se nulla cambia, controlla di nuovo la spiegazione dell'allocazione. La decisione di Elasticsearch potrebbe essere cambiata dopo la tua prima correzione, rivelando il prossimo blocco.

Prevenzione che aiuta davvero

Monitora il disco prima che vengano raggiunte le soglie. Avvisa sulle tendenze, non solo sui dischi pieni.

Usa ILM o data stream per log e metriche in modo che la conservazione sia automatica.

Mantieni gli snapshot aggiornati e testa i ripristini. Uno snapshot che non hai mai ripristinato è solo una speranza.

Mantieni le dimensioni degli shard e i conteggi degli shard ragionevoli. Troppi shard minuscoli rendono l'allocazione e il recupero più lenti di quanto suggerisca il volume di dati.

Documenta i filtri di allocazione e gli attributi dei nodi. Sei mesi dopo, qualcuno sostituirà un nodo e dimenticherà l'attributo che rendeva allocabile un indice.

Tratta il giallo come un avvertimento e il rosso come un incidente. Il giallo può essere accettabile durante la manutenzione, ma non dovrebbe diventare rumore di fondo. Il rosso significa che almeno uno shard primario non è disponibile, e più aspetti, meno opzioni di recupero facili potresti avere.

Una checklist sul campo per gli incidenti

Quando l'allocazione degli shard si rompe, raccogli le stesse prove ogni volta. Mantiene il team dal rimbalzare tra teorie.

Esegui:

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

Poi esegui la spiegazione dell'allocazione per uno shard non assegnato rappresentativo. Se ce ne sono molti, raggruppali per motivo. Dieci repliche non assegnate bloccate dalle soglie del disco sono un problema. Tre primari con no_valid_shard_copy sono un problema diverso.

Scrivi se i dati interessati possono essere ricostruiti. I log da una coda a monte, le metriche dagli agenti e gli indici di ricerca derivati possono essere recuperabili dai sistemi sorgente. I contenuti creati dagli utenti o i record di conformità potrebbero non esserlo. I comandi di recupero dovrebbero seguire quella realtà aziendale.

Quando aspettare e quando agire

Aspetta quando il recupero sta progredendo attivamente, il nodo mancante dovrebbe tornare presto, o l'allocazione ritardata sta facendo esattamente ciò che hai configurato. Puoi verificare i progressi con _cat/recovery; conteggi di byte e file in movimento sono buoni segni.

Agisci quando la spiegazione dell'allocazione mostra un blocco permanente: nessun nodo adatto, soglie del disco su ogni nodo, allocazione disabilitata, attributi del nodo mancanti o nessuna copia valida dello shard. Aspettare non risolverà una regola che rifiuta ogni nodo.

Scala rapidamente quando gli shard primari non sono assegnati per indici importanti. I fallimenti delle repliche riducono la sicurezza. I fallimenti dei primari riducono la disponibilità.

Evitare di rallentare il recupero

I grandi recuperi competono con la ricerca e l'indicizzazione normali. Aggiungere troppi nodi contemporaneamente, riavviare più nodi o aumentare la concorrenza del recupero senza controllare la capacità del disco e della rete può rendere il cluster meno stabile.

Se modifichi le impostazioni di recupero, fallo deliberatamente e registra i valori originali. Impostazioni come le concorrenze di recupero possono aiutare in alcuni ambienti e danneggiare in altri. Un recupero più veloce sulla carta può sovraccaricare i dischi e aumentare la latenza delle query abbastanza da far sì che gli utenti sperimentino un'interruzione peggiore.

Tieni d'occhio i nodi hot. L'allocazione può tecnicamente avere successo mentre pone troppo lavoro su un nodo a causa delle dimensioni degli shard, delle regole di livello o dell'uso irregolare del disco. Usa _cat/allocation, le statistiche dei nodi e il tuo sistema di monitoraggio per confermare che il cluster sia bilanciato dopo che il fallimento immediato è stato risolto.

Correzioni post-incidente

La maggior parte degli incidenti di allocazione degli shard ha una storia di prevenzione. Gli incidenti delle soglie del disco puntano alla conservazione, ILM o pianificazione della capacità. Gli incidenti dei filtri di allocazione puntano a documentazione runbook mancante. Gli incidenti senza copia valida puntano a snapshot e replay a monte. Il recupero lento punta al dimensionamento degli shard e all'hardware.

Non chiudere l'incidente solo perché la salute è verde. Rimuovi le modifiche temporanee alle repliche, ripristina gli intervalli di aggiornamento normali, riabilita l'allocazione se è stata modificata, verifica gli snapshot e aggiungi l'avviso che avrebbe catturato il problema prima.

Caso speciale: indici chiusi e nascosti

A volte un indice non si alloca perché è chiuso, nascosto o parte di una funzionalità di sistema che non sapevi di stare toccando. Fai attenzione con comandi wildcard ampi quando sono presenti indici di sistema. Nei cluster moderni, sicurezza, Kibana, trasformazioni e altre funzionalità dello stack possono mantenere i propri indici.

Usa pattern stretti e includi indici nascosti solo quando intendi ispezionarli. Se un indice di sistema ha problemi di allocazione, controlla i log del componente dello stack correlato oltre a Elasticsearch. Ad esempio, un problema dell'indice degli oggetti salvati di Kibana può manifestarsi come problema di allocazione degli shard di Elasticsearch e come fallimenti di avvio di Kibana.

La regola è la stessa dei dati utente: identifica l'indice esatto, capisci a chi appartiene, poi scegli la correzione. Non eliminare o forzare l'allocazione di un indice di sistema solo per cancellare uno stato di salute rosso a meno che tu non capisca l'impatto a livello di prodotto.