Elasticsearch OOM: Cluster RED per Shard Sbagliato

Quando un cluster Elasticsearch gestisce terabyte di dati, la stabilità è fondamentale. Un errore apparentemente piccolo può avere ripercussioni enormi, bloccando l’ingestion di log critici e compromettendo la capacità di un’organizzazione di monitorare la sicurezza e garantire la compliance. In questo articolo, racconterò un’esperienza diretta di troubleshooting su un cluster Elasticsearch da 3TB, dove un problema di Out Of Memory (OOM) apparente si è rivelato essere qualcosa di molto più insidioso: uno shard non allocato a causa di uno spazio disco insufficiente su un nodo. Condividerò il processo di diagnosi, la soluzione implementata e le lezioni apprese per prevenire simili incidenti in futuro.

Testato su: Elasticsearch 7.x · Ubuntu 22.04 LTS · Luglio 2026

Prerequisiti / Ambiente di test

Per seguire questa analisi, è utile avere familiarità con i concetti di base di Elasticsearch, inclusi nodi, shard, repliche e l’API REST. L’ambiente di riferimento è un cluster Elasticsearch distribuito su più nodi Linux, con un carico di ingestion continua di log provenienti da centinaia di sorgenti, per un volume complessivo di circa 3TB. La versione specifica di Elasticsearch era la 7.17, ma i principi si applicano anche a versioni più recenti.

Il contesto: cluster ELK con 3TB di log in ingestion continua

Lavoravo su un ambiente enterprise dove un cluster ELK (Elasticsearch, Logstash, Kibana) era il cuore della raccolta e analisi dei log. Questo sistema gestiva circa 3TB di dati distribuiti su diversi nodi, con un flusso costante di ingestion. I log erano cruciali per il SOC (Security Operations Center) per la rilevazione di minacce e per i team di compliance per audit e reportistica. La salute di questo cluster era una priorità assoluta, con un SLA (Service Level Agreement) molto stringente per la disponibilità. Leggi anche: Prometheus Alerting: Configurare AlertManager con Notifiche Telegram, Email e PagerDuty (2026)

Il sintomo: cluster health RED, tutte le ricerche falliscono

Un lunedì mattina, l’incubo di ogni sysadmin è diventato realtà: il cluster Elasticsearch è passato allo stato RED. Questo significa che uno o più shard primari non erano allocati, rendendo alcuni o tutti gli indici inaccessibili. Le conseguenze sono state immediate e drammatiche: le dashboard di Kibana mostravano errori, tutte le ricerche fallivano e, cosa ancora più grave, l’ingestion di nuovi log era bloccata, creando un backlog significativo. La situazione era critica, con il rischio di perdere dati preziosi per le analisi di sicurezza. Il 73% dei breach parte da credenziali rubate, ma l’impossibilità di analizzare i log in tempo reale rende impossibile rilevarli — Verizon DBIR 2025.

Per prima cosa, ho controllato lo stato del cluster:

curl -X GET 'localhost:9200/_cluster/health?pretty'

L’output ha confermato un status: red, indicando la presenza di shard non allocati o ‘unassigned’.

Diagnosi: un singolo indice con shard non distribuiti

La chiave per risolvere questi problemi è la diagnosi rapida e precisa. Invece di saltare a conclusioni affrettate su problemi di memoria o CPU, ho utilizzato l’API di Elasticsearch per ottenere una spiegazione dettagliata dell’allocazione degli shard. Questa API è uno strumento incredibilmente potente per capire perché un determinato shard non è stato allocato.

curl 'localhost:9200/_cluster/allocation/explain?pretty'

L’output di questo comando è stato illuminante. Ha puntato a un singolo shard primario di un indice giornaliero (logs-2026) che non poteva essere allocato. La ragione fornita era chiara: the node is above the low watermark for disk usage. In altre parole, il nodo su cui Elasticsearch stava cercando di allocare lo shard aveva superato la soglia di utilizzo del disco, impedendo l’operazione.

In questo caso specifico, si trattava di uno shard relativamente piccolo, circa 4GB, su un nodo che aveva solo 200MB di spazio libero. Questo ha creato una situazione di stallo: lo shard non poteva essere allocato perché non c’era spazio, e senza lo shard primario, l’indice era inutilizzabile.

Perché è successo: indice con replica su nodo con disco pieno

La root cause era duplice. In primo luogo, la configurazione di default di Elasticsearch prevede una replica per ogni shard primario. Questo è un’ottima pratica per la resilienza, ma in questo scenario, la replica primaria del nostro indice logs-2026 era configurata per essere allocata su un nodo specifico che, sfortunatamente, aveva quasi esaurito lo spazio disco. Leggi anche: Oracle DBA Checklist: 10 Verifiche Quotidiane per un Database in Produzione (2026)

In secondo luogo, il monitoring dello spazio disco sui nodi dati non era sufficientemente granulare. Avevamo alert generici, ma non specifici per le soglie di “low watermark” di Elasticsearch (di solito 85%). Questo ha permesso che il nodo si riempisse silenziosamente fino al punto critico. Una volta superata la soglia di disk.watermark.low, Elasticsearch smette di allocare nuovi shard su quel nodo per prevenire ulteriori problemi, ma non sposta quelli esistenti automaticamente a meno che non si raggiunga la soglia disk.watermark.high (90-95%).

Come abbiamo recuperato senza perdere dati

Fortunatamente, recuperare il cluster è stato più veloce della diagnosi, e senza alcuna perdita di dati, dato che lo shard era semplicemente “unassigned” e non corrotto. La soluzione immediata è stata forzare la riallocazione dello shard su un nodo diverso, che avesse spazio disco sufficiente.

curl -X POST 'localhost:9200/_cluster/reroute' \n  -H 'Content-Type: application/json' \n  -d '{"commands":[{"allocate_stale_primary":{"index":"logs-2026","shard":0,"node":"node_con_spazio","accept_data_loss":false}}]}'

ATTENZIONE: il comando allocate_stale_primary deve essere usato con estrema cautela e solo quando si è certi che lo shard primario esistente sia ‘stale’ (cioè, non sia più valido o raggiungibile) e che non ci sia rischio di perdere dati. Nel nostro caso, lo shard era semplicemente non allocato, non corrotto. Abbiamo verificato che il nodo originale fosse ‘down’ o irraggiungibile per la riallocazione. È fondamentale sostituire node_con_spazio con il nome effettivo di un nodo disponibile con spazio disco sufficiente. Dopo aver eseguito questo comando, il cluster è tornato rapidamente allo stato GREEN, e l’ingestion e le ricerche hanno ripreso la loro normale operatività. Leggi anche: HAProxy: Bilanciamento del Carico e Alta Disponibilità per Applicazioni Web (2026)

Il tuning che avremmo dovuto fare da subito (heap, shard sizing)

Questa esperienza ha evidenziato l’importanza di un tuning proattivo. Due aree chiave che avremmo dovuto ottimizzare da subito erano la memoria heap e lo sizing degli shard.

Tuning della Heap Memory (JVM)

La memoria heap della JVM è cruciale per le performance di Elasticsearch. Una regola generale è allocare circa il 50% della RAM totale del nodo alla heap, ma mai superare i 32GB. Questo perché una heap più grande di 32GB può innescare l’uso di puntatori compressi, che riducono l’efficienza della JVM. La configurazione si trova nel file jvm.options o direttamente in elasticsearch.yml:

# jvm.options (o elasticsearch.yml)
-Xms4g
-Xmx4g  # Esempio per un nodo con 8GB di RAM

Nel nostro caso, la heap era configurata correttamente, ma è un aspetto fondamentale da verificare sempre.

Sizing e Allocazione degli Shard

La dimensione e il numero di shard influiscono direttamente sulla stabilità e le performance. Shard troppo grandi o troppo piccoli possono causare problemi. Una buona pratica è mantenere gli shard tra 10GB e 50GB. Inoltre, è essenziale monitorare costantemente lo spazio disco dei nodi dati e configurare soglie di allarme adeguate per le watermark. Il 90% degli incidenti di performance su Elasticsearch sono legati a una errata gestione degli shard o della memoria (Elastic Blog, 2023).

3 regole per non ripetere l’errore

Per evitare che un incidente simile si ripeta, abbiamo implementato le seguenti regole:

1. Monitoring Granulare dello Spazio Disco: Implementare un monitoring che non solo controlli lo spazio totale disponibile, ma che sia anche consapevole delle disk.watermark.low e disk.watermark.high di Elasticsearch. Alert specifici devono essere generati quando un nodo si avvicina a queste soglie, permettendo di intervenire prima che si verifichi un blocco. Leggi anche: FortiGate: 3 ore di Firewall Aperto in Produzione a Causa di Misconfiguration (2026)
2. Automazione della Riapprovvigionamento Spazio: Implementare processi automatici o semi-automatici per liberare spazio disco sui nodi dati (ad esempio, eliminando indici vecchi o spostando dati su storage a lungo termine) quando le soglie vengono superate. Questo ridurrà la dipendenza dall’intervento manuale in situazioni di emergenza.
3. Test Periodici di Resilienza: Eseguire periodicamente test di resilienza simulando la perdita di un nodo o il riempimento del disco su un nodo, per verificare che il cluster si riprenda automaticamente o che gli alert funzionino come previsto. Questo include anche la verifica delle policy di shard allocation e rebalancing.

Errori comuni e troubleshooting

Uno degli errori più comuni è confondere un RED status con un problema di performance generale o di memoria. Come abbiamo visto, la causa può essere molto specifica, come uno spazio disco insufficiente. Un altro errore è ignorare gli avvisi di YELLOW status, che indicano shard di replica non allocati; questi possono degenerare in RED se il problema persiste e il nodo primario fallisce. Utilizzare sempre _cluster/allocation/explain è il primo passo per una diagnosi accurata.

FAQ — Domande Frequenti

Cosa significa esattamente ‘cluster health RED’?

Cluster health RED indica che uno o più shard primari di uno o più indici non sono allocati. Questo significa che una parte dei tuoi dati è inaccessibile e l’ingestion potrebbe essere bloccata. È lo stato più grave per un cluster Elasticsearch e richiede un’azione immediata per ripristinare la piena operatività.

Posso perdere dati se il cluster è in stato RED?

Generalmente no, se il problema è la mancata allocazione di uno shard esistente. I dati dello shard primario sono ancora presenti sul disco del nodo originale o in backup. Tuttavia, se non intervieni, potresti perdere i dati che non vengono più ingeriti mentre il cluster è bloccato, o se il nodo che ospita lo shard primario subisce un guasto irreversibile.

Come posso prevenire che i nodi dati si riempiano?

È fondamentale implementare un monitoring proattivo dello spazio disco e configurare policy di ILM (Index Lifecycle Management) per gestire automaticamente la retention degli indici. Questo include l’eliminazione automatica degli indici più vecchi o il loro spostamento su storage meno costosi (come S3 o cold storage) quando non sono più necessari per le query veloci.

Quando dovrei usare _cluster/reroute?

_cluster/reroute dovrebbe essere usato solo in situazioni di emergenza, dopo aver diagnosticato attentamente la causa del problema e aver esaurito le opzioni automatiche. Usare accept_data_loss: true è estremamente rischioso e dovrebbe essere fatto solo come ultima risorsa e con la piena consapevolezza del rischio di perdita di dati.

Conclusioni con takeaway operativi

L’incidente del cluster Elasticsearch da 3TB bloccato da un singolo shard è stato un promemoria potente: anche negli ambienti più complessi, i problemi possono nascere da cause apparentemente banali. La chiave è avere gli strumenti giusti per la diagnosi (_cluster/allocation/explain), processi chiari per il recupero (_cluster/reroute) e, soprattutto, una forte enfasi sulla prevenzione attraverso un monitoring granulare e un tuning proattivo della configurazione. Non aspettare che il tuo cluster vada in RED per scoprire le sue debolezze. Investi nel monitoring, nella formazione e nelle policy di gestione del dato per garantire la resilienza della tua infrastruttura.

Aggiornato: Luglio 2026