Risoluzione dei Problemi di Salute del Cluster Elasticsearch: Una Guida Passo-Passo

Un cluster Elasticsearch giallo o rosso non è uno stato misterioso. Di solito significa che Elasticsearch non può posizionare uno o più shard dove vorrebbe. Il lavoro consiste nel trovare quale shard è bloccato, perché l'allocazione è bloccata e se la soluzione giusta è aspettare, liberare risorse, riportare un nodo, ripristinare da snapshot o accettare deliberatamente la perdita di dati.

Tratto la salute del cluster come un segnale di triage, non come la diagnosi stessa. Verde significa che ogni shard primario e replica è assegnato. Giallo significa che tutti gli shard primari sono assegnati, quindi le ricerche e le scritture di solito possono continuare, ma manca almeno una replica. Rosso significa che almeno uno shard primario non è assegnato, quindi parte di almeno un indice non è disponibile. Il rosso è quello che può rompere immediatamente le letture o scritture delle applicazioni.

Inizia ottenendo una visione semplice:

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

Guarda status, number_of_nodes, active_primary_shards, unassigned_shards, initializing_shards e relocating_shards. Se vedi shard in inizializzazione o in relocation dopo un riavvio del nodo, il cluster potrebbe già essere in fase di recupero. Non inizi a modificare le impostazioni di allocazione prima di sapere se Elasticsearch sta semplicemente lavorando.

Poi elenca gli shard non assegnati:

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

La colonna prirep è importante. Uno shard p è primario. Un cluster rosso ha sempre almeno uno shard primario non assegnato. Uno shard r è una replica. Un cluster giallo di solito ha solo repliche non assegnate.

L'API più utile in questa situazione è allocation explain:

GET /_cluster/allocation/explain?pretty

Per uno shard specifico, sii esplicito:

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

Leggi la risposta can_allocate e le decisioni a livello di nodo. Elasticsearch di solito ti dirà esattamente quale regola ha bloccato l'allocazione: watermarks del disco, filtri di allocazione, regole di stesso shard, allocazione ritardata dopo che un nodo è uscito, dati primari mancanti, versioni incompatibili o una mancata corrispondenza dei ruoli del nodo.

Quando il Cluster è Giallo

Il giallo è comune nei cluster piccoli. Il caso classico è un cluster di sviluppo a un nodo con number_of_replicas: 1. Elasticsearch non può mettere una replica sullo stesso nodo del suo primario, quindi la replica rimane non assegnata per sempre. Non è un'emergenza in un ambiente laptop. È una mancata corrispondenza di configurazione.

Controlla il conteggio delle repliche:

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

Per un cluster non di produzione a nodo singolo, imposta le repliche a zero:

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

Per la produzione, non nascondere il problema riducendo le repliche a meno che tu non stia intenzionalmente accettando meno ridondanza. Se l'indice dovrebbe avere una replica, hai bisogno di almeno due nodi dati idonei. Se ha due repliche, hai bisogno di almeno tre nodi dati idonei. Il tiering può rendere questo meno ovvio: una replica di un indice warm non può allocarsi su un nodo solo hot se le regole di allocazione richiedono nodi warm.

La pressione del disco è la successiva causa comune di giallo. Controlla l'utilizzo del disco dei nodi:

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

Elasticsearch utilizza watermarks del disco per evitare di riempire i nodi. I valori predefiniti variano in base alla versione e alla configurazione, quindi ispeziona le impostazioni effettive del tuo cluster:

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

Se un nodo supera il watermark alto, Elasticsearch eviterà di allocare più shard lì. Se raggiunge il watermark di flood-stage, Elasticsearch potrebbe mettere gli indici interessati in uno stato di blocco scrittura per proteggere il nodo. La soluzione duratura è eliminare dati vecchi, spostare dati su più nodi, aumentare il disco, ridurre il numero di shard sovradimensionati o regolare la retention ILM. Alzare temporaneamente i watermarks può guadagnare tempo, ma non dovrebbe essere la tua prima mossa.

Una sequenza pratica di pulizia è la seguente:

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

Trova grandi indici vecchi, verifica le aspettative di retention con il team proprietario, fai snapshot se necessario, poi elimina solo i dati che sei autorizzato a rimuovere:

DELETE /old-logs-2025.12.*

Dopo aver liberato spazio, l'allocazione potrebbe riprendere automaticamente. Se non lo fa, esegui di nuovo allocation explain. La vecchia ragione potrebbe essere ancora nella tua mente, ma il cluster potrebbe ora essere bloccato da una regola diversa.

Il filtraggio dell'allocazione è un'altra frequente causa di giallo, specialmente dopo migrazioni hardware. Qualcuno potrebbe aver impostato un indice per richiedere un attributo del nodo che non esiste più:

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

Se la regola è sbagliata, rimuovila o aggiornala:

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

Usa le chiavi esatte che mostrano le tue impostazioni. Non incollare un reset generico in produzione senza leggerlo; le regole di allocazione a volte ci sono per una buona ragione, come mantenere certi dati su un tier controllato per conformità.

Quando il Cluster è Rosso

Il rosso merita mani più lente e note migliori. La prima domanda è se lo shard primario mancante ha una copia recuperabile da qualche parte.

Elenca gli shard primari non assegnati:

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

Poi controlla quali nodi sono presenti:

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

Se un nodo manca, il tuo miglior percorso di recupero è spesso riportare indietro quel nodo. Controlla il servizio, il mount del disco, la rete dell'host, i certificati e i log sul nodo mancante. Un nodo che ha perso l'accesso al suo percorso dati potrebbe avviarsi come un nodo vuoto diverso, il che non aiuta a recuperare lo shard primario.

Sul nodo Elasticsearch, i log di solito mostrano il vero fallimento prima delle API. Cerca messaggi su fallimenti di lock dello shard, file di indice corrotti, discovery del master, errori di handshake TLS, filesystem di sola lettura del disco o cambiamenti di ruolo del nodo. Un fallimento comune nel mondo reale è un riavvio del nodo dopo che un disco è stato rimontato sotto un percorso diverso. Elasticsearch si avvia, ma il percorso dati è vuoto, quindi al cluster manca ancora la copia dello shard di cui ha bisogno.

Esegui allocation explain per il primario:

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

Se la spiegazione dice che non è possibile trovare una copia valida dello shard, fermati e controlla gli snapshot prima di fare qualsiasi cosa distruttiva:

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

Ripristinare uno snapshot è di solito più sicuro che allocare un primario vuoto. Un primario vuoto crea un nuovo shard vuoto per quell'ID shard. Non è un'operazione di riparazione. Dice a Elasticsearch: "Accetto che i vecchi dati per questo shard siano persi."

Il comando di ultima risorsa è il seguente:

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

Usalo solo dopo aver confermato che non esiste una copia del nodo utilizzabile e nessuno snapshot che puoi ripristinare. In un incidente, scrivi chi ha approvato quella scelta e quale indice e shard sono stati interessati. Il debugging futuro è molto più facile quando la decisione di perdita di dati è esplicita.

Casi che Sembrano Problemi di Allocazione Ma Sono Realmente Problemi del Cluster

A volte gli shard non sono assegnati perché il cluster non può mantenere una membership stabile. Se i nodi master-eligible non possono parlare tra loro, il master eletto potrebbe cambiare ripetutamente e l'allocazione si agiterà o si fermerà. Controlla la stabilità del master:

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

Se il master cambia spesso, ispeziona l'affidabilità della rete, il DNS, i certificati dei nodi e le impostazioni di discovery. Per i cluster Elasticsearch moderni, cluster.initial_master_nodes è per il bootstrap iniziale del cluster, non un'impostazione da lasciare come stampella di discovery per sempre. discovery.seed_hosts dovrebbe puntare a seed host appropriati e tutti i nodi devono usare lo stesso nome del cluster e impostazioni di sicurezza compatibili.

Un'alta pressione JVM può anche causare sintomi di allocazione. Un nodo dati bloccato in lunghe pause di garbage collection potrebbe lasciare e rientrare nel cluster dal punto di vista del master. Questo può creare shard non assegnati anche se la macchina non è mai completamente crashata.

Controlla heap e log di 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

Se l'heap è costantemente alto, non aumentare l'heap ciecamente. Elasticsearch generalmente funziona meglio quando l'heap lascia abbastanza memoria per la cache del filesystem. Cerca aggregazioni sovradimensionate, uso pesante di fielddata, troppi shard, indicizzazione aggressiva o query che necessitano di mapping migliori.

Il numero di shard può essere la causa silenziosa dietro molti problemi di salute. Un cluster con molti shard minuscoli spende troppo tempo a tracciare metadati e spostare shard. Usa:

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

Se ogni indice di log giornaliero ha molti shard primari ma pochi dati, correggi il template dell'indice per gli indici futuri. Poi considera piani di shrink, rollover o reindex per i dati esistenti.

Un Ordine Pratico di Triage

Quando qualcuno dice "Elasticsearch è rosso", uso questo ordine:

1. Conferma la salute con _cluster/health.
2. Elenca gli shard non assegnati con _cat/shards.
3. Separa i fallimenti primari da quelli delle repliche.
4. Esegui _cluster/allocation/explain su uno shard rappresentativo.
5. Controlla se tutti i nodi previsti sono presenti.
6. Controlla i watermarks del disco e le regole di allocazione.
7. Per i primari rossi, prova a recuperare il nodo mancante o ripristina da snapshot prima di considerare l'allocazione di un primario vuoto.
8. Dopo che il cluster diventa verde, trova la causa che lo ha reso non sano in primo luogo.

Quell'ultimo passo è importante. Un cluster può diventare verde dopo aver aggiunto disco, riavviato un nodo o ridotto le repliche, ma lo stesso incidente tornerà se la retention ILM è sbagliata, il numero di shard è troppo alto, i nodi sono sottodimensionati o un processo di deployment continua a cambiare gli attributi dei nodi.

La risoluzione dei problemi di salute del cluster riguarda meno il memorizzare un comando magico e più il rifiutarsi di indovinare. Elasticsearch espone la decisione di allocazione. Leggila, verificala rispetto alle impostazioni del nodo e dell'indice e scegli la correzione più piccola che corrisponde al blocco effettivo.

Dopo che il Cluster è di Nuovo Verde

Non chiudere l'incidente solo perché il colore è cambiato. Verde significa solo che gli shard sono assegnati ora. Non prova che il cluster sia abbastanza sano per il prossimo picco di traffico, ciclo di crescita del disco o riavvio del nodo. Mi piace catturare una breve nota post-azione mentre i dettagli sono ancora freschi: quali indici sono stati interessati, quali nodi sono stati coinvolti, quale regola di allocazione ha bloccato il recupero e quale comando o modifica dell'infrastruttura lo ha risolto.

Controlla se la correzione ha creato un nuovo rischio. Se hai ridotto le repliche per trasformare il giallo in verde, registra che l'indice ora ha meno ridondanza. Se hai alzato i watermarks del disco, aggiungi un promemoria per abbassarli dopo che la capacità è stata aggiunta. Se hai ripristinato uno snapshot, verifica che l'indice ripristinato abbia gli alias e le impostazioni di scrittura previste prima che le applicazioni riprendano le scritture normali.

Alcuni controlli rapidi aiutano a cogliere il lavoro incompiuto:

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 non dovrebbe crescere per sempre. Il recovery dovrebbe eventualmente svuotarsi. Gli alias sono importanti perché ripristinare un indice con un nome diverso può lasciare l'applicazione che scrive sul vecchio target rotto o che legge solo parte dei dati previsti.

Controlla anche i blocchi di scrittura dopo incidenti del disco:

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

Se Elasticsearch ha impostato un blocco di flood-stage, rimuovilo solo dopo che la pressione del disco è stata risolta:

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

Il lavoro di prevenzione più utile è di solito noioso: snapshot funzionanti, ripristini testati, retention ILM realistica, abbastanza spazio su disco e numero di shard che corrisponde alla dimensione del cluster. Un cluster con snapshot affidabili e dimensionamento sano degli shard è molto più facile da recuperare di un cluster con comandi di emergenza intelligenti e nessun percorso di ripristino.

Cosa Non Fare Durante gli Incidenti di Salute

Non riavviare tutti i nodi contemporaneamente. È tentatore quando il cluster sembra non sano, ma un approccio rolling e osservato è più sicuro. Riavviare nodi sani può rimuovere copie di shard di cui Elasticsearch ha bisogno per il recupero. Se devi riavviare, fallo un nodo alla volta e aspetta che il cluster si stabilizzi tra i passaggi.

Non disabilitare l'allocazione e dimenticartene. I cambiamenti temporanei di allocazione sono comuni durante la manutenzione, ma un'impostazione dimenticata può lasciare le repliche non assegnate molto dopo la finestra di manutenzione. Controlla sempre sia le impostazioni persistenti che quelle transitorie:

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

Non eliminare indici basandoti solo sulla dimensione. Gli indici grandi potrebbero essere critici per il business. Gli indici piccoli potrebbero essere sicuri da rimuovere. Collega la pulizia alla politica di retention, agli snapshot e alla proprietà dell'applicazione. In un vero guasto, la pulizia sicura più veloce è di solito eliminare indici di log o metriche noti come scaduti, non indovinare da una lista ordinata per dimensione.

Non assumere che Kibana ed Elasticsearch usino lo stesso linguaggio per il problema. Kibana potrebbe mostrare uno stato rosso ampio mentre le API di Elasticsearch mostrano lo shard non assegnato preciso. Usa l'interfaccia utente per la visibilità, ma usa le API per la decisione.