Risoluzione dei Problemi Comuni di Failover e Connessione nei Cluster HA di PostgreSQL

I cluster ad alta disponibilità (HA) di PostgreSQL falliscono in due modi diversi. A volte il failover del database stesso si rompe: nessuna replica viene promossa, due nodi non concordano sul primario, o il nuovo primario non può accettare scritture. Altre volte il database funziona correttamente, ma l'applicazione non riesce comunque a connettersi perché un pooler, un record DNS, un IP virtuale, una regola del firewall o un ciclo di tentativi del client non hanno seguito la promozione.

Quando sei nell'incidente, separa questi livelli rapidamente. Prima chiedi: esiste esattamente un primario scrivibile? Poi chiedi: il pooler può raggiungerlo? Poi chiedi: l'applicazione può raggiungere il pooler o l'endpoint del servizio? Questo ordine impedisce di perdere molto tempo a fissare i log dell'applicazione mentre il gestore del cluster è ancora bloccato nell'elezione del leader.

Comprensione delle Basi dell'HA di PostgreSQL

Prima di immergerci nella risoluzione dei problemi, è essenziale ricapitolare brevemente i componenti principali di un cluster HA di PostgreSQL:

Architettura Primario/Replica: Un database primario gestisce tutte le operazioni di scrittura, mentre una o più repliche ricevono in modo asincrono o sincrono le modifiche tramite streaming replication. Le repliche sono di sola lettura ma fungono da candidati per la promozione durante un failover.
Gestore del Failover: Strumenti come Patroni, pg_auto_failover o Corosync/Pacemaker monitorano la salute del primario, rilevano i guasti, eleggono un nuovo primario dalle repliche disponibili e gestiscono il processo di promozione. Gestiscono anche la riconfigurazione di altre repliche per seguire il nuovo primario.
Connection Pooling: Le applicazioni spesso si connettono a un pooler di connessioni PostgreSQL (ad es., PgBouncer, Odyssey) piuttosto che direttamente al database. Il pooler quindi instrada le query al primario corrente, fornendo multiplexing delle connessioni, bilanciamento del carico e potenzialmente astraendo l'indirizzo di rete effettivo del primario dalle applicazioni. Questa astrazione è cruciale durante il failover.

Problemi Comuni di Failover e Connessione e le Loro Soluzioni

1. Problemi di Connection Pooling Durante il Failover

Uno dei problemi più frequenti post-failover è che le applicazioni non riescono a riconnettersi al primario appena promosso, nonostante il database stesso sia operativo. Questo spesso indica problemi con il pooler di connessione o la cache lato client.

Sintomi del Problema:

Le applicazioni segnalano errori di connessione al database (FATAL: database "mydb" does not exist, connection refused, server closed the connection unexpectedly).
Le connessioni esistenti attraverso il pooler sembrano bloccate o tentano di connettersi all'IP del vecchio primario.
Anche le nuove connessioni falliscono, anche dopo il completamento del failover.

Cause Sottostanti:

Connessioni Stale nel Pooler: Il pooler di connessione potrebbe mantenere connessioni aperte al vecchio primario e tentare di riutilizzarle, portando a errori quando il vecchio primario è giù o ora è una replica.
Configurazione Errata del Pooler: Il pooler potrebbe non essere configurato per rilevare e passare correttamente al nuovo primario, oppure il suo server_reset_query potrebbe essere mancante/errato.
Caching DNS: Se le tue applicazioni o il pooler utilizzano una voce DNS per risolvere l'indirizzo del primario, voci DNS obsolete nella cache (a livello locale o del resolver DNS) possono far sì che continuino a tentare di connettersi al vecchio IP.
Mancanza di Logica di Retry Lato Client: Le applicazioni potrebbero non essere costruite con meccanismi di retry robusti per gestire problemi di connessione transitori durante un failover.

Passaggi di Debug:

Controlla lo Stato del Pooler: Accedi alla console del tuo pooler (ad es., psql -p 6432 pgbouncer -U pgbouncer) e controlla l'output di SHOW SERVERS, SHOW CLIENTS, SHOW DATABASES per vedere se è a conoscenza del nuovo primario e se ha connessioni attive all'indirizzo corretto.
Verifica la Connettività di Rete: Dall'host del pooler, esegui ping e telnet alla porta PostgreSQL del nuovo primario (telnet new_primary_ip 5432).
Ispeziona i Log del Pooler: Esamina i log del pooler per messaggi di errore relativi alla connessione al database o al tentativo di risolvere hostname.
Controlla la Risoluzione DNS: Usa dig o nslookup sull'host del pooler per assicurarti che il record DNS per il tuo endpoint del servizio primario (ad es., primary.mydomain.com) risolva l'indirizzo IP del nuovo primario.

Soluzioni:

Configura server_reset_query: Assicurati che il tuo pooler abbia un server_reset_query (ad es., DISCARD ALL;) per pulire lo stato della sessione quando una connessione viene restituita al pool e prima che venga riutilizzata da un altro client. Questo è cruciale per ambienti che utilizzano oggetti temporanei o impostazioni specifiche della sessione.
max_db_connections e max_user_connections: Imposta limiti appropriati per impedire al pooler di monopolizzare tutte le connessioni al nuovo primario, potenzialmente affamando altri servizi.
Ricarica/Riavvia il Pooler: In alcuni casi, potrebbe essere necessario un ricaricamento o riavvio graduale del pooler di connessione per forzarlo a raccogliere nuove configurazioni o risolvere nuovamente il DNS. Questa dovrebbe essere l'ultima risorsa e preferibilmente automatizzata dal tuo gestore del failover.
TTL DNS più Breve: Se utilizzi il discovery di servizi basato su DNS, configura un Time-To-Live (TTL) molto breve per il record DNS del primario (ad es., 30-60 secondi) per minimizzare l'impatto del caching DNS.
Retry Lato Client: Implementa la logica di backoff esponenziale e retry nel codice della tua applicazione. Questo rende le applicazioni più resilienti ai problemi di connessione transitori durante il failover.
IP Virtuale (VIP): Considera l'utilizzo di un IP virtuale gestito dalla tua soluzione HA. Il VIP si sposta con il primario, quindi le applicazioni si connettono a un IP statico e il server di database sottostante cambia in modo trasparente.

# Esempio di Frammento di Configurazione PgBouncer
[databases]
mydb = host=primary_cluster_service_ip port=5432 dbname=mydb
# Oppure usando un hostname che viene aggiornato dal tuo gestore del failover
# mydb = host=primary.mydomain.com port=5432 dbname=mydb

[pgbouncer]
listen_addr = 0.0.0.0
listen_port = 6432
auth_type = md5
auth_file = /etc/pgbouncer/userlist.txt
pool_mode = session
server_reset_query = DISCARD ALL;
server_fast_close = 1 # Chiudi le connessioni rapidamente se il server non risponde
server_check_delay = 10 # Controlla la salute del server ogni 10 secondi

2. Lag Eccessivo della Replica che Ostacola il Failover

Il lag della replica si verifica quando un database standby rimane indietro rispetto al primario, il che significa che non ha riprodotto tutti i record WAL (Write-Ahead Log) inviati dal primario. Durante un failover, promuovere una replica con molto lag può portare a perdita di dati o ritardare significativamente il processo di failover se il gestore HA attende che si metta in pari.

Sintomi del Problema:

Gli avvisi di monitoraggio indicano un lag elevato della replica (ad es., in byte o tempo).
I gestori del failover rifiutano di promuovere una replica a causa del superamento di una soglia di lag configurata.
Dopo il failover, le applicazioni osservano dati mancanti che erano presenti sul vecchio primario.

Cause Sottostanti:

Carico Elevato di Scrittura sul Primario: Un volume elevato e sostenuto di operazioni di scrittura sul primario può sopraffare la capacità della replica di tenere il passo, specialmente se l'hardware della replica (I/O, CPU) è inferiore.
Latenza/Banda di Rete: Collegamenti di rete lenti o congestionati tra primario e replica possono ritardare l'invio del WAL.
I/O Lento della Replica: Il sottosistema disco della replica potrebbe non essere abbastanza veloce per scrivere e riprodurre i record WAL in modo efficiente.
Impostazione wal_level: Se wal_level non è impostato su replica o superiore, le informazioni necessarie per lo streaming replication non verranno generate.
max_wal_senders: Un max_wal_senders insufficiente sul primario può limitare il numero di slot di replica attivi o connessioni di replica concorrenti, influenzando la produttività.
Problemi con archive_command / restore_command: Se si utilizzano l'archiviazione e il recupero WAL, problemi con questi comandi (ad es., storage di archivio lento) possono causare ritardi.

Passaggi di Debug:

Monitora pg_stat_replication: Questa vista fornisce informazioni in tempo reale sullo stato della replica, inclusi write_lag, flush_lag e replay_lag.
Confronta gli LSN: Confronta manualmente l'LSN WAL corrente sul primario con l'ultimo LSN riprodotto sulla replica.
Controlla le Risorse di Sistema: Usa iostat, vmstat, top sia sul primario che sulla replica per identificare colli di bottiglia I/O, saturazione della CPU o pressione della memoria.
Diagnostica di Rete: Testa le prestazioni di rete tra primario e replica usando iperf.

Soluzioni:

Aumenta max_wal_senders: Sul primario, aumenta max_wal_senders (ad es., max_wal_senders = 10) per consentire più connessioni di replica concorrenti. Riavvio richiesto.
Migliora l'Hardware della Replica: Se I/O o CPU sono un collo di bottiglia, considera l'aggiornamento dell'hardware della replica o l'ottimizzazione della sua configurazione di storage (ad es., SSD più veloci, disco WAL separato).
Ottimizza wal_compression: Sul primario, impostare wal_compression = on può ridurre il volume del WAL, migliorando potenzialmente la velocità di replica su collegamenti con vincoli di rete, ma a costo della CPU del primario.
Regola wal_keep_size o wal_keep_segments: Assicurati che sul primario vengano conservati abbastanza file WAL per impedire alle repliche di perdere la sincronizzazione e richiedere un backup di base completo.
synchronous_commit: Mentre synchronous_commit = on fornisce garanzie più forti di durabilità dei dati, introduce latenza per le scritture sul primario. Usa remote_write o remote_apply per tabelle o transazioni specifiche se è necessaria una replica sincrona rigorosa, ma valuta attentamente l'impatto sulle prestazioni.
Monitoraggio e Avvisi: Implementa un monitoraggio robusto per pg_stat_replication e imposta avvisi per quando il lag supera soglie accettabili.

-- Sul Primario: Controlla l'LSN WAL corrente
SELECT pg_current_wal_lsn();

-- Sul Primario: Controlla gli standby connessi e il lag
SELECT
    usename, application_name, client_addr, state, sync_state,
    pg_wal_lsn_diff(pg_current_wal_lsn(), replay_lsn) AS replay_lag_bytes,
    write_lag, flush_lag, replay_lag
FROM pg_stat_replication;

Su uno standby, usa:

SELECT
    pg_is_in_recovery() AS is_standby,
    pg_last_wal_receive_lsn(),
    pg_last_wal_replay_lsn(),
    now() - pg_last_xact_replay_timestamp() AS time_since_last_replay;

La query sul timestamp può essere fuorviante su un sistema inattivo perché potrebbe non essere stata riprodotta alcuna transazione recente. Usala con confronti LSN e contesto del carico di lavoro.

3. Transizione del Primario Fallita o Bloccata

Un failover automatizzato dovrebbe promuovere una replica rapidamente e in modo affidabile. Quando questo processo si blocca o fallisce completamente, può portare a tempi di inattività prolungati e richiedere un intervento manuale.

Sintomi del Problema:

Nessun nuovo primario viene eletto o promosso dopo che il vecchio primario è andato giù.
Il cluster entra in uno stato split-brain in cui due nodi credono di essere il primario.
I log del gestore del failover mostrano errori relativi a quorum, elezione del leader o promozione del database.
Le applicazioni rimangono giù perché nessun primario è disponibile.

Cause Sottostanti:

Split-Brain: Si verifica quando partizioni di rete isolano i nodi, portando a più primari o a un'elezione ambigua del primario. Questo è lo scenario più pericoloso, rischiando la divergenza dei dati.
Problemi di Quorum: Il gestore del failover potrebbe non essere in grado di raggiungere un quorum (voto di maggioranza) tra i suoi nodi, impedendogli di prendere una decisione sulla promozione. Questo è comune in cluster con un numero pari di nodi o con troppo pochi nodi.
Isolamento di Rete: I nodi del gestore del failover non possono comunicare tra loro o con le istanze PostgreSQL, impedendo i controlli di salute o l'esecuzione dei comandi.
Privilegi Insufficienti: L'utente del gestore del failover potrebbe non avere i permessi PostgreSQL necessari (ad es., pg_promote()) o i permessi a livello di sistema (ad es., per gestire i VIP).
Errori di Configurazione: restore_command, primary_conninfo o altre impostazioni errate all'interno della configurazione del gestore del failover.

Passaggi di Debug:

Controlla i Log del Gestore del Failover: Questa è la fonte primaria di informazioni. Per Patroni, guarda i suoi log specifici (spesso journalctl -u patroni o il file di log configurato in patroni.yml). Per pg_auto_failover, controlla journalctl -u pgautofailover_monitor e i log dell'agente.
Verifica lo Stato del Quorum: Per Patroni, usa patronictl list per vedere lo stato di tutti i membri del cluster e confermare il leader eletto. Per pg_auto_failover, controlla pg_autoctl show state.
Connettività di Rete: Esegui controlli ping, traceroute e telnet tra tutti i nodi HA e il datastore di consenso distribuito (ad es., Etcd, Consul, ZooKeeper per Patroni).
Log di Sistema: Controlla journalctl -xe o /var/log/syslog su tutti i nodi per eventuali errori a livello di sistema che potrebbero interferire con il gestore del failover (ad es., disco pieno, problemi di memoria).
Log di PostgreSQL: Esamina i log di PostgreSQL sulla replica candidata per la promozione per vedere se segnala problemi durante il tentativo di promozione.

Soluzioni:

Implementa Fencing/STONITH: Il fencing è cruciale per prevenire lo split-brain assicurando che un primario guasto non possa continuare ad accettare scritture prima che ne venga promosso uno nuovo. Questo è tipicamente gestito dal gestore del failover o dal livello dell'infrastruttura.
Numero Dispari di Nodi per il Quorum: Distribuisci sempre un numero dispari di nodi votanti (ad es., 3, 5) per il datastore di consenso distribuito del tuo gestore del failover (Etcd, Consul, ZooKeeper) per garantire che il quorum possa essere sempre raggiunto anche se uno o due nodi falliscono.
Configurazione di Rete Robusta: Assicurati percorsi di rete ridondanti, regole del firewall appropriate che consentano la comunicazione sulle porte necessarie (PostgreSQL, datastore di consenso, API Patroni) e risoluzione degli hostname coerente.
Controllo dei Permessi: Verifica che l'account utente che esegue il gestore del failover abbia tutti i privilegi PostgreSQL necessari e i permessi di sistema per eseguire attività di promozione e riconfigurazione.
Rivedi la Configurazione del Gestore del Failover: Ricontrolla le impostazioni di patroni.yml o pg_auto_failover per errori di battitura, percorsi errati o restore_command configurato in modo errato.
Intervento Manuale (Con Cautela): In un failover bloccato grave, potrebbe essere necessaria la promozione manuale o la riunione dei nodi. Procedi con estrema cautela, assicurandoti che il vecchio primario sia completamente spento prima di promuoverne uno nuovo per evitare la divergenza dei dati.

# Esempio: Controllo dello stato del cluster Patroni
patronictl -c /etc/patroni/patroni.yml list

# Output previsto (esempio):
# + Cluster: my_ha_cluster (6979219803154942080) ------+----+-----------+----+-----------+
# | Member  | Host         | Role    | State    | TL | Lag |
# +---------+--------------+---------+----------+----+-----+
# | node1   | 192.168.1.10 | Leader  | running  | 2  |     |
# | node2   | 192.168.1.11 | Replica | running  | 2  | 0   |
# | node3   | 192.168.1.12 | Replica | running  | 2  | 0   |
# +---------+--------------+---------+----------+----+-----+

4. Problemi di Connettività di Rete e Risoluzione DNS

Alla radice di molti problemi HA ci sono problemi di rete fondamentali, che impediscono ai nodi di comunicare o alle applicazioni di trovare l'endpoint del database corretto.

Sintomi del Problema:

Errori connection refused o no route to host dalle applicazioni o tra i nodi del cluster.
Il gestore del failover segnala nodi come irraggiungibili.
I servizi che si basano sul DNS non riescono a risolvere correttamente l'hostname del primario.

Cause Sottostanti:

Regole del Firewall: Regole del firewall configurate in modo errato (ad es., iptables, gruppi di sicurezza) che bloccano la porta PostgreSQL (5432), le porte del gestore del failover o le porte del datastore di consenso.
Partizione di Rete: Split di rete fisico o logico che impedisce la comunicazione tra un sottoinsieme di nodi.
Routing Errato: Route di rete configurate in modo errato su uno o più nodi.
Caching/Configurazione DNS Errata: Come discusso nella Sezione 1, record DNS obsoleti o configurazione del server DNS errata possono deviare il traffico.
Fallimento della Migrazione dell'IP Virtuale (VIP): Se si utilizza un VIP, potrebbe non riuscire a migrare verso il nuovo primario, lasciando il servizio irraggiungibile.

Passaggi di Debug:

Connettività di Base: Usa ping <target_ip> tra tutti i nodi.
Connettività delle Porte: Usa telnet <target_ip> <port> (ad es., telnet 192.168.1.10 5432) per verificare che la porta PostgreSQL sia aperta e in ascolto.
Controllo del Firewall: Su ogni nodo, controlla le regole del firewall attive (sudo iptables -L, sudo ufw status o le configurazioni del gruppo di sicurezza del provider cloud).
Stato dell'Interfaccia di Rete: Usa ip addr show o ifconfig per assicurarti che le interfacce di rete siano attive e configurate correttamente.
Risoluzione DNS: Usa dig <hostname> o nslookup <hostname> per verificare la risoluzione dell'hostname dai nodi pertinenti (server applicativi, pooler, nodi HA).

Soluzioni:

Rivedi le Regole del Firewall: Assicurati che le porte necessarie siano aperte per PostgreSQL (5432), il piano di controllo del gestore del failover (ad es., 8008 per l'API Patroni, 8000/8001 per pg_auto_failover) e il datastore di consenso distribuito (ad es., Etcd: 2379/2380, Consul: 8300/8301/8302).
Rete Coerente: Assicurati che tutti i nodi siano sulla stessa subnet o abbiano il routing corretto configurato se si estendono su più subnet.
Aggiornamenti DNS: Automatizza gli aggiornamenti DNS come parte del processo di failover o usa un TTL più breve. I VIP sono spesso preferiti per questo motivo.
Gestione VIP: Se si utilizza un VIP, assicurati che lo strumento di gestione del VIP (ad es., Keepalived, gestione IP del provider cloud) sia configurato e funzioni correttamente. Testa esplicitamente la migrazione del VIP.
Accesso Basato su Host: Per semplicità in cluster più piccoli, assicurati che pg_hba.conf permetta le connessioni da tutti i potenziali indirizzi IP del primario/replica e dall'IP del pooler di connessione.

Strumenti Essenziali per la Risoluzione dei Problemi

psql: Per eseguire query SQL come pg_stat_replication, pg_current_wal_lsn(), comandi SHOW *.
CLI del Gestore del Failover: patronictl, pg_autoctl per interrogare lo stato del cluster, i log e avviare azioni.
Monitoraggio di Sistema: Strumenti come Prometheus + Grafana, Zabbix, Nagios o il monitoraggio del provider cloud per approfondimenti in tempo reale sull'utilizzo delle risorse, il lag della replica e lo stato del servizio.
journalctl / tail -f: Per visualizzare i log di sistema e dell'applicazione.
Utilità di Rete: ping, traceroute, telnet, iperf, netstat, dig, nslookup per diagnosticare la connettività.
dmesg: Per errori a livello di kernel, specialmente relativi a I/O del disco o killer OOM (Out Of Memory).

Una Checklist Rapida per gli Incidenti

Quando scatta un avviso di failover HA, usa una breve checklist prima di modificare qualsiasi cosa:

Conferma la vista del cluster:

patronictl -c /etc/patroni/patroni.yml list

Conferma il ruolo di PostgreSQL stesso su ogni nodo raggiungibile:

SELECT pg_is_in_recovery();

false significa che il nodo è un primario scrivibile. true significa che è uno standby. Se più di un nodo riporta false, fermati e tratta l'incidente come un possibile split-brain.

Conferma l'endpoint dell'applicazione:

dig primary-db.internal.example.com
nc -vz primary-db.internal.example.com 5432

Conferma la destinazione del pooler, se usi PgBouncer:

SHOW SERVERS;
SHOW POOLS;

Controlla se gli errori sono vecchi o attuali. I log delle applicazioni spesso conservano messaggi di retry dai primi secondi del failover. Confronta i timestamp prima di presumere che il fallimento sia ancora in corso.

Questa checklist è volutamente semplice. Durante un failover reale, il comando migliore è quello che tutti nel team capiscono e possono eseguire senza indovinare.

Best Practice per Prevenire Problemi di Failover

Test Regolari del Failover: Simula regolarmente i guasti del primario e osserva il processo di failover. Questo crea fiducia ed espone configurazioni errate.
Monitoraggio e Avvisi Robusto: Monitora metriche chiave come il lag della replica, lo stato del primario, la salute del pooler di connessione e le risorse di sistema. Imposta avvisi per qualsiasi deviazione.
Configurazione Corretta del Connection Pooler: Assicurati che server_reset_query sia configurato, pool_mode sia appropriato per la tua applicazione e i controlli di salute siano abilitati.
Ottimizza i Parametri di Replica: Configura wal_level, max_wal_senders, wal_keep_size e synchronous_commit attentamente in base ai tuoi requisiti di prestazioni e durabilità.
Documenta la Tua Configurazione HA: Documenta chiaramente la tua architettura HA, la configurazione del gestore del failover, le impostazioni di rete e le procedure di ripristino.
Usa un Gestore del Failover Dedicato: Affidati a soluzioni comprovate come Patroni o pg_auto_failover piuttosto che a script personalizzati per la logica HA critica.
Datastore di Consenso Dedicato: Se usi un gestore come Patroni, distribuisci un cluster separato e ad alta disponibilità per il suo datastore di consenso distribuito (Etcd, Consul) per evitare un singolo punto di guasto.

I test HA più utili non sono demo pulite in cui il primario viene arrestato educatamente. Testa anche i casi brutti: il vecchio primario perde la rete ma continua a funzionare, il DNS si aggiorna lentamente, PgBouncer mantiene connessioni server stale, una replica è in ritardo di 30 secondi o il datastore di consenso perde un membro. Quei test mostrano se i tuoi runbook corrispondono al sistema che effettivamente gestisci.