Risoluzione dei problemi relativi allo stato del cluster Elasticsearch: una guida passo passo

Risoluzione dei problemi di salute del cluster Elasticsearch: Una guida passo-passo

Elasticsearch è un sistema distribuito robusto, ma come qualsiasi architettura distribuita, richiede un monitoraggio attivo e occasionali interventi per mantenere una salute ottimale. Lo stato di salute del cluster è la metrica più critica per determinare la prontezza operativa e la sicurezza dei dati della vostra implementazione. Quando il cluster passa da Green a Yellow o, in modo critico, a Red, l'integrità o la disponibilità dei dati è minacciata.

Questa guida completa fornisce passaggi esperti per diagnosticare e risolvere i problemi comuni di salute del cluster Elasticsearch, concentrandosi specificamente sul recupero dagli stati Yellow e Red. Utilizzeremo pratiche Cat API e controlli passo-passo per identificare rapidamente la causa principale e implementare azioni correttive.

1. Comprendere lo stato di salute del cluster Elasticsearch

Prima di procedere alla risoluzione dei problemi, è essenziale comprendere cosa significhi ogni colore di salute del cluster. Lo stato di salute è determinato dallo stato di allocazione delle vostre shard primarie e di replica tra i nodi del cluster.

Stato	Significato	Implicazioni
Green	Tutte le shard primarie e di replica sono state allocate con successo.	Il cluster è pienamente operativo e resiliente.
Yellow	Tutte le shard primarie sono allocate, ma una o più shard di replica non sono assegnate.	I dati sono disponibili, ma il cluster manca della piena resilienza ai guasti dei nodi.
Red	Almeno una shard primaria non è assegnata (e quindi non disponibile).	Perdita di dati o inaccessibilità per l'indice contenente le shard fallite. Azione critica richiesta.

2. Diagnosi iniziale: Controllo della salute del cluster

Il primo passo in qualsiasi processo di risoluzione dei problemi è confermare lo stato attuale e raccogliere metriche di base utilizzando la Cluster Health API e la Nodes API.

Passo 2.1: Controllare la salute del cluster

Utilizzare l'API _cat/health per ottenere un riepilogo di alto livello. Il parametro ?v fornisce un output verboso, inclusi il numero di nodi e il conteggio totale delle shard.

GET /_cat/health?v

Esempio di output (stato Yellow):

epoch      timestamp cluster       status node.total node.data shards  pri relo init unassign pending_tasks max_task_wait_time active_shards_percent
1678233600 09:00:00  my-cluster    yellow 3          3         10     5    0    0        5 0             -                  50.0%

Se lo stato è Yellow o Red, annotare il valore sotto unassign.

Passo 2.2: Controllare lo stato dei nodi e la memoria

Assicurarsi che tutti i nodi previsti siano connessi e operino correttamente. Controllare anche l'utilizzo dell'heap (critico per prestazioni e stabilità).

GET /_cat/nodes?v&h=name,node.role,version,heap.percent,disk.total,disk.used,disk.avail

Se un nodo manca da questa lista, potrebbe esserci un problema di connettività o un servizio interrotto.

3. Risoluzione dello stato del cluster Red (Errore di shard primaria)

Uno stato Red significa che i dati sono immediatamente inaccessibili. L'obiettivo è ripristinare la shard primaria il più rapidamente possibile.

Passo 3.1: Identificare le shard primarie non assegnate

Utilizzare l'API _cat/shards per individuare l'indice e la shard esatti che causano il problema. Cercare specificamente le voci contrassegnate come UNASSIGNED con un ruolo p (primario).

GET /_cat/shards?v | grep UNASSIGNED

Esempio di output:

index_logs 0 p UNASSIGNED

Passo 3.2: Controllare la spiegazione dell'allocazione

Questo è il singolo passo diagnostico più importante. L'API Allocation Explain indica perché una specifica shard (o qualsiasi shard non assegnata) non può essere allocata.

GET /_cluster/allocation/explain

Motivi comuni per lo stato Red:

Guasto del nodo: Il nodo che conteneva la shard primaria è crashato o è stato rimosso dal cluster. Se il nodo fallito ha repliche sufficienti su altri nodi, la shard primaria dovrebbe promuovere automaticamente una replica. Se tutte le copie (primaria e repliche) si trovavano sul nodo fallito, la shard è persa a meno che il nodo non venga recuperato.
Dati corrotti: I file della shard primaria sul disco sono diventati corrotti, impedendo al nodo di inizializzarli.

Passo 3.3: Piano d'azione per lo stato Red

Scenario A: Nodo offline (preferito)
- Se il nodo che conteneva la shard primaria è semplicemente offline, ripristinare il servizio del nodo (ad es. riavviare Elasticsearch o risolvere i problemi di rete). Una volta che il nodo si ricongiunge al cluster, la shard primaria dovrebbe recuperare.
Scenario B: Shard primaria persa (ultima risorsa)
- Se il nodo è permanentemente perso e non esistevano repliche, i dati sono persi. È necessario saltare manualmente il recupero utilizzando il comando allocate_empty_primary. Avvertenza: Questo creerà una shard primaria completamente nuova e vuota, con conseguente perdita permanente dei dati per quel segmento dell'indice.

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

Best Practice: Prima di ricorrere a allocate_empty_primary, verificare sempre che non esista uno snapshot o un backup per l'indice.

4. Risoluzione dello stato del cluster Yellow (Errore di shard di replica)

Uno stato Yellow significa che il cluster è operativo ma vulnerabile. L'obiettivo primario è allocare le repliche mancanti.

Passo 4.1: Utilizzare Allocation Explain

Se lo stato è Yellow, utilizzare l'API _cluster/allocation/explain (Sezione 3.2) per capire perché la replica non può essere assegnata. La spiegazione per le repliche è tipicamente più semplice.

Motivi comuni per lo stato Yellow:

Codice motivo	Spiegazione	Soluzione
`NO_AVAILABLE_NODES`	La dimensione del cluster è troppo piccola (ad es. il conteggio delle repliche è 2, ma esistono solo 2 nodi).	Aggiungere più nodi dati o ridurre `number_of_replicas`.
`NOT_ENOUGH_DISK_SPACE`	I nodi hanno raggiunto la soglia di watermark bassa o alta.	Eliminare gli indici vecchi, liberare spazio su disco o regolare i watermark del disco.
`ALLOCATION_DISABLED`	L'allocazione delle shard è stata esplicitamente disabilitata dalle impostazioni del cluster.	Riabilitare il routing usando `PUT /_cluster/settings`.
`PRIMARY_NOT_ACTIVE`	La shard primaria è ancora in fase di inizializzazione o recupero.	Attendere che la primaria diventi attiva (Green).

Passo 4.2: Controllo dei requisiti e dei vincoli del nodo

Assicurarsi che il cluster soddisfi i requisiti di base per l'allocazione delle repliche:

Conteggio nodi: Per N repliche, sono necessari almeno N+1 nodi dati per assicurarsi che primaria e repliche non siano mai sullo stesso nodo.
Watermark del disco: Elasticsearch smette di allocare shard ai nodi quando l'utilizzo del disco supera l'high watermark (predefinito 90%).

# Controllare le impostazioni di allocazione del disco
GET /_cluster/settings?flat_settings=true&filter_path=*watermark*

# Esempio: Impostazione dell'high watermark al 95% (Temporaneamente!)
PUT /_cluster/settings
{
  "persistent": {
    "cluster.routing.allocation.disk.watermark.high": "95%"
  }
}

Passo 4.3: Reroute manuale (se la logica di allocazione fallisce)

In rari casi, se il processo di allocazione standard sembra bloccato nonostante risorse sufficienti, è possibile forzare manualmente l'allocazione della replica a un nodo sano specifico utilizzando il comando allocate_replica.

POST /_cluster/reroute
{
  "commands" : [
    {
      "allocate_replica" : {
        "index" : "[index-name]", 
        "shard" : [shard-id],
        "node" : "[target-node-name]"
      }
    }
  ]
}

5. Risoluzione avanzata dei problemi e insidie comuni

Se lo stato Red o Yellow persiste, la causa principale potrebbe essere al di fuori della logica standard di allocazione delle shard.

5.1 Connettività di rete e Split-Brain

Nei sistemi distribuiti, il partizionamento (split-brain) può causare problemi gravi. Se i nodi eleggibili come master non riescono a comunicare, il cluster potrebbe non riuscire ad eleggere un master stabile, portando a shard non assegnate.

Azione: Verificare la connettività di rete tra tutti i nodi, specialmente tra i nodi eleggibili come master.
Controllo della configurazione: Assicurarsi che l'elenco discovery.seed_hosts sia accurato e che l'impostazione cluster.initial_master_nodes sia stata utilizzata correttamente durante il bootstrap del cluster.

5.2 Alta pressione della memoria JVM

Un utilizzo eccessivo dell'heap (spesso superiore al 75%) porta a pause frequenti e lunghe del Garbage Collection (GC). Durante queste pause, un nodo può apparire non responsivo, facendo sì che il nodo master lo abbandoni, portando a shard non assegnate.

Azione: Monitorare l'utilizzo dell'heap (_cat/nodes?h=heap.percent). Se costantemente alto, considerare di aumentare la memoria del nodo, ottimizzare i processi di indicizzazione o implementare la gestione del ciclo di vita degli indici (ILM).

5.3 Filtri di allocazione delle shard

L'applicazione accidentale di filtri di allocazione (utilizzando attributi del nodo come tag o ID) può impedire che le shard vengano allocate a nodi che altrimenti sarebbero idonei.

# Controllare le regole di allocazione a livello di indice
GET /[index-name]/_settings
# Cercare: index.routing.allocation.require.*

# Ripristinare le regole di allocazione dell'indice (se necessario)
PUT /[index-name]/_settings
{
  "index.routing.allocation.require": null
}

Checklist di riepilogo per un recupero rapido

Stato	Strumento diagnostico primario	Passaggi chiave dell'azione
Yellow	`GET /_cluster/allocation/explain`	1. Controllare lo spazio su disco. 2. Verificare il conteggio dei nodi rispetto al conteggio delle repliche. 3. Cercare regole di filtro dell'allocazione. 4. Attendere il recupero della primaria.
Red	`GET /_cat/shards?v \| grep UNASSIGNED`	1. Controllare i log sul nodo precedentemente ospitante. 2. Tentare di riavviare il nodo fallito. 3. Se la primaria è confermata persa e non esiste un backup, usare `allocate_empty_primary` (Rischio di perdita di dati).

Utilizzando sistematicamente le API _cat e l'endpoint critico _cluster/allocation/explain, è possibile individuare rapidamente la causa del degrado della salute del cluster e implementare i passaggi correttivi necessari per ripristinare il cluster allo stato stabile Green.