Risoluzione dei problemi: Controllo e interpretazione dello stato di salute del cluster Elasticsearch

Elasticsearch è un motore di ricerca e analisi robusto e distribuito, ma la sua natura distribuita richiede un monitoraggio costante per garantire l'integrità dei dati e l'alta disponibilità. Il primo, e più cruciale, passo nell'amministrazione è il controllo dello stato di salute del cluster. Uno stato di salute ottimale garantisce che tutti i segmenti di dati primari e replica (shard) siano correttamente assegnati ai nodi e operativi.

Questa guida fornisce un approccio pratico al controllo dello stato di salute del cluster utilizzando l'essenziale API _cat/health. Descriveremo in dettaglio come interpretare gli stati codificati a colori (Verde, Giallo, Rosso) e forniremo passaggi attuabili per diagnosticare e risolvere problemi comuni di instabilità, aiutando gli amministratori a ripristinare rapidamente le prestazioni ottimali del cluster.

Comprendere lo stato di salute di Elasticsearch

Elasticsearch utilizza un semplice sistema a semaforo codificato a colori per comunicare lo stato operativo degli indici e degli shard del cluster. Questo stato riflette lo stato di assegnazione sia degli shard primari che di quelli replica.

I tre stati di salute principali

Stato	Significato	Disponibilità dei dati	Ridondanza	Azione richiesta
Verde	Tutti gli shard primari e replica sono assegnati e operativi.	100% disponibile	Completa	Solo monitoraggio
Giallo	Tutti gli shard primari sono assegnati, ma uno o più shard replica non sono assegnati.	100% disponibile	Compromessa	Indagare/Risolvere l'assegnazione della replica
Rosso	Uno o più shard primari non sono assegnati.	Perdita/Indisponibilità parziale o totale dei dati	Gravemente compromessa	Intervento immediato

Controllo dello stato di salute del cluster con `_cat/health`

Le API _cat sono progettate per diagnostiche rapide e leggibili dall'uomo. L'endpoint _cat/health è il modo più rapido per ottenere una panoramica dello stato attuale del cluster.

Comando di base

È possibile eseguire questo comando usando cURL, la console Kibana Dev Tools o qualsiasi client HTTP.

# Utilizzo di cURL (formato leggibile dall'uomo)
curl -X GET "localhost:9200/_cat/health?v&pretty"

Interpretazione dell'output di `_cat/health`

Una query riuscita restituisce una tabella con metriche chiave:

Colonna	Descrizione
`epoch`	L'ora (timestamp Unix) in cui la richiesta è stata eseguita.
`timestamp`	L'ora nel formato HH:MM:SS.
`cluster`	Il nome del cluster.
`status`	L'indicatore di colore cruciale (Verde, Giallo o Rosso).
`node.total`	Numero totale di nodi attualmente uniti al cluster.
`node.data`	Numero di nodi dati nel cluster.
`shards`	Numero totale di shard (primari + replica) che dovrebbero essere attivi.
`pri`	Numero totale di shard primari.
`relo`	Numero di shard attualmente in fase di rilocazione tra i nodi.
`init`	Numero di shard attualmente in fase di inizializzazione.
`unassign`	Numero di shard attualmente non assegnati.

Esempio di un cluster sano (Verde):

echo      timestamp cluster       status node.total node.data shards pri relo init unassign
1678886400 10:30:00  my-cluster-dev green         3         3     30  15    0    0        0

Diagnosi dello stato: Giallo

Quando un cluster riporta uno stato Giallo, significa che, sebbene tutti i tuoi dati siano tecnicamente disponibili (tutti gli shard primari sono assegnati), il livello di ridondanza definito non è soddisfatto. Uno o più shard replica non sono stati allocati.

Cause comuni dello stato Giallo

Perdita di nodi (temporanea): Un nodo dati che ospitava shard replica è andato offline. Elasticsearch sta aspettando che quel nodo torni online o che un nuovo nodo si unisca prima di tentare la riallocazione.
Nodi insufficienti: Se richiedi 2 repliche (3 copie totali dei dati) ma hai solo 2 nodi dati, la terza copia non può essere posizionata, portando a uno stato Giallo permanente fino all'aggiunta di un altro nodo.
Allocazione ritardata: Il cluster è configurato per ritardare l'allocazione della replica dopo un guasto del nodo per prevenire un ribilanciamento immediato e costoso se il nodo torna rapidamente.
Vincoli di spazio su disco: I nodi potrebbero non avere spazio su disco sufficiente per ospitare gli shard replica.

Passaggi attuabili per lo stato Giallo

Controlla gli shard non assegnati: Usa l'API _cat/shards per identificare esattamente quali shard non sono assegnati (u) e perché sono in attesa.

bash curl -X GET "localhost:9200/_cat/shards?v"
Usa l'API di spiegazione dell'allocazione (Allocation Explain API): Per diagnostiche dettagliate sul motivo per cui uno shard specifico non è assegnato, usa l'API Allocation Explain. Sostituisci index_name e shard_id di seguito con i valori effettivi trovati tramite _cat/shards.

bash curl -X GET "localhost:9200/_cluster/allocation/explain?pretty" -H 'Content-Type: application/json' -d' { "index": "index_name", "shard": 0, "primary": false } '

Cerca specificamente i campi unassigned_info e decisions per ragioni come CLUSTER_REBALANCE_ALLOCATION_DELAY o NO_VALID_TARGET_NODE.
Verifica il conteggio e la configurazione dei nodi: Assicurati che il numero di nodi dati soddisfi o superi il numero richiesto di repliche più uno (N repliche + 1 primario).

Suggerimento: Se il cluster è Giallo a causa di una manutenzione nota e a breve termine su un nodo, puoi spesso ignorarlo temporaneamente, ma sii consapevole che stai operando senza ridondanza.

Diagnosi dello stato: Rosso

Uno stato Rosso è critico e significa che uno o più shard primari non sono assegnati. Ciò significa che i dati memorizzati in quello shard sono completamente non disponibili per l'indicizzazione o la ricerca.

Cause comuni dello stato Rosso

Guasto massiccio del nodo: Un nodo primario è fallito e nessun altro nodo è riuscito a subentrare nel ruolo primario perché i dati erano corrotti o interamente non disponibili nel resto del cluster.
Corruzione/Guasto del disco: Il dispositivo di archiviazione contenente lo shard primario è fallito e non esiste alcuna replica da promuovere.
Problemi con le impostazioni dell'indice: Errata configurazione o eliminazione errata dei file di indice a livello di filesystem.

Intervento immediato per lo stato Rosso

Esegui sempre il backup del tuo cluster (tramite snapshot) prima di tentare azioni di recupero manuali quando il cluster è Rosso.

Controlla immediatamente i log: Rivedi i log del nodo master e del/i nodo/i che ospita/no lo shard primario fallito per identificare l'esatta eccezione o la causa del crash (spesso correlata a guasti del disco o errori di memoria insufficiente).
Identifica l'indice fallito: Usa _cat/shards per trovare l'indice associato al primario non assegnato (p).

```bash

Cerca le righe in cui lo stato è 'UNASSIGNED' e il primario è 'p'

curl -X GET "localhost:9200/_cat/shards?h=index,shard,prirep,state,unassigned.reason"
```
Tenta il reroute forzato (Pericoloso - Da usare come ultima risorsa): Se sei certo che i dati esistano su uno dei nodi (ad esempio, un nodo è tornato online ma il routing non si è corretto), potresti provare un reroute manuale. Questo viene spesso utilizzato quando uno shard primario è definitivamente perso e decidi di scartare i dati persi e forzare un nuovo primario vuoto su un nodo sano.

```bash

ATTENZIONE: Questo comando può portare alla perdita di dati se usato in modo errato.

Assegna uno shard primario vuoto a un nodo, contrassegnando l'indice come sano.

curl -X POST "localhost:9200/_cluster/reroute?pretty" -H 'Content-Type: application/json' -d'
{
"commands" : [
{
"allocate_empty_primary" : {
"index" : "failed_index_name",
"shard" : 0,
"node" : "target_node_name",
"accept_data_loss" : true
}
}
]
}
'
```
Ripristina da snapshot: Se lo shard primario fallito non può essere recuperato, l'unico modo sicuro per ripristinare l'integrità dei dati è ripristinare l'indice interessato dall'ultimo snapshot riuscito.

Diagnostica avanzata: Impostazioni del cluster

A volte, lo stato del cluster è Rosso o Giallo a causa di azioni amministrative o salvaguardie operative preconfigurate.

Controllo dell'allocazione del routing del cluster

L'API _cluster/settings ti consente di verificare se l'allocazione automatica degli shard è stata esplicitamente disabilitata, il che impedirebbe al cluster di auto-ripararsi.

# Recupera le impostazioni correnti del cluster
curl -X GET "localhost:9200/_cluster/settings?include_defaults=true&pretty"

Cerca specificamente la seguente impostazione:

{
  "persistent": {
    "cluster": {
      "routing": {
        "allocation": {
          "enable": "none" 
        }
      }
    }
  }
}

Se cluster.routing.allocation.enable è impostato su none (o primaries), Elasticsearch non allocherà shard, bloccando il cluster nel suo stato attuale (probabilmente Giallo o Rosso).

Riabilitazione dell'allocazione

Per ripristinare la normale allocazione degli shard, aggiorna l'impostazione a all:

curl -X PUT "localhost:9200/_cluster/settings?pretty" -H 'Content-Type: application/json' -d'
{
  "persistent": {
    "cluster.routing.allocation.enable": "all"
  }
}
'

Conclusione

Interpretare lo stato di salute del cluster Elasticsearch è la competenza fondamentale per qualsiasi amministratore. L'API _cat/health fornisce una visione immediata dell'integrità operativa dei tuoi dati. Mentre uno stato Verde è l'obiettivo, comprendere che Giallo significa ridondanza ridotta e Rosso significa dati non disponibili consente una risoluzione dei problemi precisa e immediata utilizzando strumenti secondari come _cat/shards e l'API Allocation Explain. Il monitoraggio regolare e gli snapshot proattivi rimangono le migliori difese contro un fallimento critico del cluster.