Dépannage des erreurs courantes de basculement et de connexion dans les clusters PostgreSQL HA

Les clusters PostgreSQL à haute disponibilité (HA) sont conçus pour assurer le fonctionnement continu de la base de données, même en cas de pannes matérielles, d'interruptions de réseau ou d'autres perturbations imprévues. Le mécanisme de basculement (failover) est un composant essentiel de toute configuration HA; il promeut automatiquement une réplique pour qu'elle devienne la nouvelle primaire lorsque la primaire actuelle devient indisponible. Bien que robustes, les processus de basculement peuvent parfois rencontrer des problèmes, entraînant des temps d'arrêt des applications ou des incohérences de données.

Cet article explore les erreurs courantes de basculement et de connexion dans les clusters PostgreSQL HA. Nous examinerons des problèmes typiques tels que les applications qui ne parviennent pas à se reconnecter via les gestionnaires de pools de connexions, le retard excessif des répliques affectant la cohérence des données, et les transitions primaires bloquées. Pour chaque problème, nous discuterons des causes sous-jacentes, des techniques de débogage efficaces utilisant les outils PostgreSQL standard et les utilitaires système, et des solutions concrètes pour garantir des transitions primaires fluides et automatisées ainsi qu'une connectivité applicative transparente. En comprenant et en abordant ces défis de manière proactive, vous pouvez maintenir la fiabilité et la performance de votre environnement PostgreSQL HA.

Comprendre les bases de PostgreSQL HA

Avant de nous plonger dans le dépannage, il est essentiel de récapituler brièvement les composants fondamentaux d'un cluster PostgreSQL HA :

Architecture Primaire/Réplique (Primary/Replica): Une base de données primaire gère toutes les opérations d'écriture, tandis qu'une ou plusieurs répliques reçoivent les changements de manière asynchrone ou synchrone via la réplication en flux (streaming replication). Les répliques sont en lecture seule mais servent de candidates à la promotion lors d'un basculement.
Gestionnaire de Basculement (Failover Manager): Des outils comme Patroni, pg_auto_failover, ou Corosync/Pacemaker surveillent la santé de la primaire, détectent les pannes, élisent une nouvelle primaire parmi les répliques disponibles et gèrent le processus de promotion. Ils gèrent également la reconfiguration des autres répliques pour qu'elles suivent la nouvelle primaire.
Pool de Connexions (Connection Pooling): Les applications se connectent souvent à un gestionnaire de pool de connexions PostgreSQL (par exemple, PgBouncer, Odyssey) plutôt que directement à la base de données. Le gestionnaire de pool achemine ensuite les requêtes vers la primaire actuelle, offrant un multiplexage des connexions, un équilibrage de charge, et potentiellement une abstraction de l'adresse réseau réelle de la primaire pour les applications. Cette abstraction est cruciale pendant le basculement.

Problèmes courants de basculement et de connexion et leurs solutions

1. Problèmes de pool de connexions pendant le basculement

L'un des problèmes post-basculement les plus fréquents est l'échec de reconnexion des applications à la nouvelle primaire promue, même si la base de données elle-même est opérationnelle. Cela indique souvent des problèmes avec le gestionnaire de pool de connexions ou la mise en cache côté client.

Symptômes du problème :

Les applications signalent des erreurs de connexion à la base de données (FATAL: database "mydb" does not exist, connection refused, server closed the connection unexpectedly).
Les connexions existantes via le pooler semblent bloquées ou tentent de se connecter à l'adresse IP de l'ancienne primaire.
Les nouvelles connexions échouent également, même après la fin du basculement.

Causes sous-jacentes :

Connexions périmées dans le Pooler: Le gestionnaire de pool de connexions pourrait maintenir des connexions ouvertes vers l'ancienne primaire et tenter de les réutiliser, ce qui entraîne des erreurs lorsque l'ancienne primaire est hors service ou est maintenant une réplique.
Configuration incorrecte du Pooler: Le pooler pourrait ne pas être configuré pour détecter et basculer correctement vers la nouvelle primaire, ou son paramètre server_reset_query pourrait être manquant/incorrect.
Mise en Cache DNS: Si vos applications ou votre pooler utilisent une entrée DNS pour résoudre l'adresse de la primaire, des entrées de cache DNS périmées (localement ou au niveau du résolveur DNS) peuvent les amener à continuer d'essayer de se connecter à l'ancienne IP.
Manque de logique de réessai côté client: Les applications pourraient ne pas être conçues avec des mécanismes de réessai robustes pour gérer les problèmes de connexion transitoires pendant un basculement.

Étapes de débogage :

Vérifier l'état du Pooler : Accédez à la console de votre pooler (par exemple, psql -p 6432 pgbouncer -U pgbouncer) et vérifiez le résultat de ses commandes SHOW SERVERS, SHOW CLIENTS, SHOW DATABASES pour voir s'il est au courant de la nouvelle primaire et s'il a des connexions actives à la bonne adresse.
Vérifier la connectivité réseau : Depuis l'hôte du pooler, utilisez ping et telnet vers le port PostgreSQL de la nouvelle primaire (telnet new_primary_ip 5432).
Inspecter les journaux du Pooler : Examinez les journaux du pooler pour détecter les messages d'erreur liés à la connexion à la base de données ou à la tentative de résolution des noms d'hôte.
Vérifier la résolution DNS : Utilisez dig ou nslookup sur l'hôte du pooler pour vous assurer que l'enregistrement DNS de votre point de service primaire (par exemple, primary.mydomain.com) se résout vers l'adresse IP de la nouvelle primaire.

Solutions :

Configurer server_reset_query : Assurez-vous que votre pooler dispose d'un server_reset_query (par exemple, DISCARD ALL;) pour nettoyer l'état de la session lorsqu'une connexion est renvoyée au pool et avant qu'elle ne soit réutilisée par un autre client. Ceci est crucial pour les environnements utilisant des objets temporaires ou des paramètres spécifiques à la session.
max_db_connections et max_user_connections : Définissez des limites appropriées pour empêcher le pooler d'accaparer toutes les connexions à la nouvelle primaire, risquant potentiellement d'affamer d'autres services.
Recharger/Redémarrer le Pooler : Dans certains cas, un rechargement ou un redémarrage gracieux du gestionnaire de pool de connexions peut être nécessaire pour le forcer à prendre en compte de nouvelles configurations ou à résoudre à nouveau le DNS. Cela devrait être un dernier recours et de préférence automatisé par votre gestionnaire de basculement.
TTL DNS plus court : Si vous utilisez la découverte de service basée sur DNS, configurez une durée de vie (TTL) très courte pour l'enregistrement DNS de la primaire (par exemple, 30 à 60 secondes) afin de minimiser l'impact de la mise en cache DNS.
Mécanismes de réessai côté client : Implémentez une logique de réessai et de backoff exponentiel dans le code de votre application. Cela rend les applications plus résilientes aux problèmes de connexion transitoires pendant le basculement.
IP Virtuelle (VIP) : Envisagez d'utiliser une IP Virtuelle gérée par votre solution HA. Le VIP se déplace avec la primaire, de sorte que les applications se connectent à une IP statique, et le serveur de base de données sous-jacent change de manière transparente.

# Exemple d'extrait de configuration PgBouncer
[databases]
mydb = host=primary_cluster_service_ip port=5432 dbname=mydb
# Ou en utilisant un nom d'hôte qui est mis à jour par votre gestionnaire de basculement
# 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 # Fermer rapidement les connexions si le serveur ne répond pas
server_check_delay = 10 # Vérifier l'état du serveur toutes les 10 secondes

2. Retard excessif de la réplique entravant le basculement

Le retard de la réplique (replica lag) se produit lorsqu'une base de données de secours prend du retard sur la primaire, ce qui signifie qu'elle n'a pas rejoué tous les enregistrements WAL (Write-Ahead Log) envoyés par la primaire. Lors d'un basculement, la promotion d'une réplique très en retard peut entraîner une perte de données ou retarder considérablement le processus de basculement si le gestionnaire HA attend qu'elle se rattrape.

Symptômes du problème :

Les alertes de surveillance indiquent un retard de réplique élevé (par exemple, en octets ou en temps).
Les gestionnaires de basculement refusent de promouvoir une réplique car elle dépasse un seuil de retard configuré.
Après le basculement, les applications constatent des données manquantes qui étaient présentes sur l'ancienne primaire.

Causes sous-jacentes :

Charge d'écriture primaire élevée : Un volume élevé et soutenu d'opérations d'écriture sur la primaire peut dépasser la capacité de la réplique à suivre, surtout si le matériel de la réplique (E/S, CPU) est inférieur.
Latence/Bande passante réseau : Des liaisons réseau lentes ou congestionnées entre la primaire et la réplique peuvent retarder l'expédition des WAL.
E/S de la réplique lentes : Le sous-système de disque de la réplique pourrait ne pas être assez rapide pour écrire et rejouer les enregistrements WAL efficacement.
Paramètre wal_level : Si wal_level n'est pas défini sur replica ou plus, les informations nécessaires à la réplication ne seront pas générées.
max_wal_senders : Un max_wal_senders insuffisant sur la primaire peut limiter le nombre de slots de réplication actifs ou de connexions de réplication concurrentes, impactant le débit.
Problèmes archive_command / restore_command : Si vous utilisez l'archivage et la récupération WAL, des problèmes avec ces commandes (par exemple, un stockage d'archives lent) peuvent entraîner des retards.

Étapes de débogage :

Surveiller pg_stat_replication : Cette vue fournit des informations en temps réel sur l'état de la réplication, y compris write_lag, flush_lag et replay_lag.
Comparer les LSN : Comparez manuellement le LSN WAL actuel sur la primaire avec le dernier LSN rejoué sur la réplique.
Vérifier les ressources système : Utilisez iostat, vmstat, top sur la primaire et la réplique pour identifier les goulots d'étranglement d'E/S, la saturation du CPU ou la pression de la mémoire.
Diagnostics réseau : Testez les performances réseau entre la primaire et la réplique à l'aide d'iperf.

Solutions :

Augmenter max_wal_senders : Sur la primaire, augmentez max_wal_senders (par exemple, max_wal_senders = 10) pour autoriser plus de connexions de réplication concurrentes. Un redémarrage est nécessaire.
Améliorer le matériel de la réplique : Si les E/S ou le CPU constituent un goulot d'étranglement, envisagez de mettre à niveau le matériel de la réplique ou d'optimiser sa configuration de stockage (par exemple, des SSD plus rapides, un disque WAL séparé).
Optimiser wal_compression : Sur la primaire, le réglage de wal_compression = on (PostgreSQL 14+) peut réduire le volume de WAL, améliorant potentiellement la vitesse de réplication sur les liaisons réseau limitées, mais au prix du CPU de la primaire.
Ajuster wal_keep_size ou wal_keep_segments : Assurez-vous que suffisamment de fichiers WAL sont conservés sur la primaire pour empêcher les répliques de se désynchroniser et de nécessiter une sauvegarde de base complète.
synchronous_commit : Bien que synchronous_commit = on offre des garanties de durabilité des données plus solides, il introduit une latence pour les écritures sur la primaire. Utilisez remote_write ou remote_apply pour des tables ou des transactions spécifiques si une réplication synchrone stricte est nécessaire, mais évaluez attentivement l'impact sur les performances.
Surveillance et Alertes : Mettez en œuvre une surveillance robuste de pg_stat_replication et configurez des alertes lorsque le retard dépasse les seuils acceptables.

-- Sur la Primaire : Vérifier le LSN WAL actuel
SELECT pg_current_wal_lsn();

-- Sur la Réplique : Vérifier l'état et le retard de la réplication
SELECT
    usename, application_name, client_addr, state, sync_state,
    pg_wal_lsn_diff(pg_current_wal_lsn(), replay_lsn) AS replay_lag_bytes,
    EXTRACT(EPOCH FROM (now() - pg_last_wal_replay_lsn())) AS replay_lag_seconds
FROM pg_stat_replication;

3. Transition primaire échouée ou bloquée

Un basculement automatisé doit promouvoir une réplique rapidement et de manière fiable. Lorsque ce processus cale ou échoue complètement, cela peut entraîner un temps d'arrêt prolongé et nécessiter une intervention manuelle.

Symptômes du problème :

Aucune nouvelle primaire n'est élue ou promue après la panne de l'ancienne primaire.
Le cluster entre dans un état de « split-brain » (cerveau divisé) où deux nœuds pensent être la primaire.
Les journaux du gestionnaire de basculement affichent des erreurs liées au quorum, à l'élection du leader ou à la promotion de la base de données.
Les applications restent hors service car aucune primaire n'est disponible.

Causes sous-jacentes :

Split-Brain : Se produit lorsque des partitions réseau isolent des nœuds, conduisant à plusieurs primaires ou à une élection primaire ambiguë. C'est le scénario le plus dangereux, risquant une divergence des données.
Problèmes de Quorum : Le gestionnaire de basculement pourrait ne pas être en mesure d'atteindre un quorum (vote majoritaire) parmi ses nœuds, l'empêchant de prendre une décision concernant la promotion. Cela est fréquent dans les clusters avec un nombre pair de nœuds ou trop peu de nœuds.
Isolation Réseau : Les nœuds du gestionnaire de basculement ne peuvent pas communiquer entre eux ou avec les instances PostgreSQL, empêchant les vérifications de santé ou l'exécution de commandes.
Privilèges Insuffisants : L'utilisateur du gestionnaire de basculement pourrait manquer des autorisations PostgreSQL nécessaires (par exemple, pg_promote()) ou des autorisations au niveau du système (par exemple, pour gérer les VIP).
Erreurs de Configuration : restore_command, primary_conninfo incorrects ou autres paramètres mal configurés au sein du gestionnaire de basculement.

Étapes de débogage :

Vérifier les journaux du gestionnaire de basculement : C'est la source d'information principale. Pour Patroni, consultez ses journaux spécifiques (souvent journalctl -u patroni ou le fichier journal configuré dans patroni.yml). Pour pg_auto_failover, vérifiez journalctl -u pgautofailover_monitor et les journaux de l'agent.
Vérifier l'état du Quorum : Pour Patroni, utilisez patronictl list pour voir l'état de tous les membres du cluster et confirmer le leader élu. Pour pg_auto_failover, vérifiez pg_autoctl show state.
Connectivité réseau : Effectuez des vérifications ping, traceroute et telnet entre tous les nœuds HA et le magasin de consensus distribué (par exemple, Etcd, Consul, ZooKeeper pour Patroni).
Journaux Système : Consultez journalctl -xe ou /var/log/syslog sur tous les nœuds pour toute erreur au niveau du système susceptible d'interférer avec le gestionnaire de basculement (par exemple, disque plein, problèmes de mémoire).
Journaux PostgreSQL : Examinez les journaux PostgreSQL sur la réplique candidate à la promotion pour voir si elle signale des problèmes pendant la tentative de promotion.

Solutions :

Mettre en œuvre le Fencing/STONITH : (Shoot The Other Node In The Head) est crucial pour éviter le split-brain en garantissant qu'une primaire défaillante est véritablement arrêtée avant qu'une nouvelle ne soit promue. Ceci est généralement géré par le gestionnaire de basculement.
Nombre Impair de Nœuds pour le Quorum : Déployez toujours un nombre impair de nœuds votants (par exemple, 3, 5) pour le magasin de consensus distribué de votre gestionnaire de basculement (Etcd, Consul, ZooKeeper) afin de garantir qu'un quorum puisse toujours être atteint même si un ou deux nœuds échouent.
Configuration Réseau Robuste : Assurez-vous d'avoir des chemins réseau redondants, des règles de pare-feu appropriées autorisant la communication sur les ports nécessaires (PostgreSQL, magasin de consensus, API Patroni) et une résolution de nom d'hôte cohérente.
Vérification des Autorisations : Vérifiez que le compte utilisateur exécutant le gestionnaire de basculement dispose de tous les privilèges PostgreSQL et des autorisations système nécessaires pour effectuer les tâches de promotion et de reconfiguration.
Examiner la Configuration du Gestionnaire de Basculement : Vérifiez à nouveau les paramètres de patroni.yml ou pg_auto_failover pour les fautes de frappe, les chemins incorrects ou un restore_command mal configuré.
Intervention Manuelle (Avec prudence) : Dans un cas grave de basculement bloqué, une promotion manuelle ou la réintégration des nœuds pourrait être nécessaire. Procédez avec une extrême prudence, en vous assurant que l'ancienne primaire est complètement arrêtée avant d'en promouvoir une nouvelle pour éviter la divergence des données.

# Exemple : Vérification de l'état du cluster Patroni
patronictl -c /etc/patroni/patroni.yml list

# Sortie attendue (exemple) :
# + 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. Problèmes de connectivité réseau et de résolution DNS

À la racine de nombreux problèmes HA se trouvent des problèmes réseau fondamentaux, empêchant les nœuds de communiquer ou les applications de trouver le bon point d'accès à la base de données.

Symptômes du problème :

Erreurs connection refused ou no route to host des applications ou entre les nœuds du cluster.
Le gestionnaire de basculement signale que les nœuds sont inaccessibles.
Les services dépendant du DNS ne peuvent pas résoudre correctement le nom d'hôte de la primaire.

Causes sous-jacentes :

Règles de Pare-feu : Règles de pare-feu mal configurées (par exemple, iptables, groupes de sécurité) bloquant le port PostgreSQL (5432), les ports du gestionnaire de basculement ou les ports du magasin de consensus.
Partition Réseau : Division réseau physique ou logique empêchant la communication entre un sous-ensemble de nœuds.
Routage Incorrect : Routes réseau mal configurées sur un ou plusieurs nœuds.
Mise en Cache/Mauvaise Configuration DNS : Comme discuté dans la section 1, des enregistrements DNS périmés ou une configuration de serveur DNS incorrecte peuvent mal diriger le trafic.
Échec de Migration d'IP Virtuelle (VIP) : Si vous utilisez un VIP, il pourrait échouer à migrer vers la nouvelle primaire, laissant le service inaccessible.

Étapes de débogage :

Connectivité de Base : Utilisez ping <target_ip> entre tous les nœuds.
Connectivité de Port : Utilisez telnet <target_ip> <port> (par exemple, telnet 192.168.1.10 5432) pour vérifier que le port PostgreSQL est ouvert et en écoute.
Vérification du Pare-feu : Sur chaque nœud, vérifiez les règles de pare-feu actives (sudo iptables -L, sudo ufw status, ou les configurations de groupe de sécurité du fournisseur cloud).
État de l'Interface Réseau : Utilisez ip addr show ou ifconfig pour vous assurer que les interfaces réseau sont actives et correctement configurées.
Résolution DNS : Utilisez dig <hostname> ou nslookup <hostname> pour vérifier la résolution du nom d'hôte à partir des nœuds pertinents (serveurs d'applications, pooler, nœuds HA).

Solutions :

Examiner les Règles de Pare-feu : Assurez-vous que les ports nécessaires sont ouverts pour PostgreSQL (5432), le plan de contrôle du gestionnaire de basculement (par exemple, 8008 pour l'API Patroni, 8000/8001 pour pg_auto_failover) et le magasin de consensus distribué (par exemple, Etcd : 2379/2380, Consul : 8300/8301/8302).
Réseau Cohérent : Assurez-vous que tous les nœuds sont sur le même sous-réseau ou que le routage correct est configuré s'ils s'étendent sur plusieurs sous-réseaux.
Mises à Jour DNS : Automatisez les mises à jour DNS dans le cadre du processus de basculement, ou utilisez un TTL plus court. Les VIP sont souvent préférées pour cette raison.
Gestion des VIP : Si vous utilisez un VIP, assurez-vous que l'outil de gestion des VIP (par exemple, Keepalived, gestion d'IP du fournisseur cloud) est correctement configuré et fonctionne. Testez explicitement la migration du VIP.
Accès Basé sur l'Hôte : Pour simplifier dans les clusters plus petits, assurez-vous que pg_hba.conf autorise les connexions à partir de toutes les adresses IP potentielles de la primaire/réplique et de l'IP du gestionnaire de pool de connexions.

Outils essentiels pour le dépannage

psql : Pour exécuter des requêtes SQL comme pg_stat_replication, pg_current_wal_lsn(), commandes SHOW *.
CLI du Gestionnaire de Basculement : patronictl, pg_autoctl pour interroger l'état du cluster, les journaux et initier des actions.
Surveillance Système : Outils comme Prometheus + Grafana, Zabbix, Nagios, ou la surveillance du fournisseur cloud pour des informations en temps réel sur l'utilisation des ressources, le retard de réplication et l'état du service.
journalctl / tail -f : Pour visualiser les journaux système et d'application.
Utilitaires Réseau : ping, traceroute, telnet, iperf, netstat, dig, nslookup pour diagnostiquer la connectivité.
dmesg : Pour les erreurs au niveau du noyau, en particulier celles liées aux E/S disque ou au tueur OOM (Out Of Memory).

Meilleures pratiques pour prévenir les problèmes de basculement

Test Régulier du Basculement : Simulez régulièrement les pannes primaires et observez le processus de basculement. Cela renforce la confiance et révèle les mauvaises configurations.
Surveillance et Alertes Robustes : Surveillez les métriques clés comme le retard de réplication, l'état de la primaire, la santé du pooler de connexions et les ressources système. Configurez des alertes pour toute déviation.
Configuration Appropriée du Pooler de Connexions : Assurez-vous que server_reset_query est configuré, que pool_mode est approprié pour votre application et que les vérifications de santé sont activées.
Ajuster les Paramètres de Réplication : Configurez wal_level, max_wal_senders, wal_keep_size et synchronous_commit avec soin en fonction de vos exigences de performance et de durabilité.
Documenter votre Configuration HA : Documentez clairement votre architecture HA, la configuration du gestionnaire de basculement, les paramètres réseau et les procédures de récupération.
Utiliser un Gestionnaire de Basculement Dédié : Fiez-vous à des solutions éprouvées comme Patroni ou pg_auto_failover plutôt qu'à des scripts personnalisés pour la logique HA critique.
Magasin de Consensus Dédié : Si vous utilisez un gestionnaire comme Patroni, déployez un cluster séparé et hautement disponible pour son magasin de consensus distribué (Etcd, Consul) afin d'éviter un point de défaillance unique.

Conclusion

Construire et maintenir un cluster PostgreSQL HA robuste nécessite une planification, une configuration et une surveillance proactive minutieuses. Bien que le basculement automatisé réduise considérablement les temps d'arrêt, des problèmes courants liés au pool de connexions, au retard de réplication et au processus de basculement lui-même peuvent toujours survenir. En comprenant les symptômes typiques et les causes sous-jacentes, et en utilisant les techniques de débogage et les solutions décrites dans ce guide, vous pouvez dépanner et prévenir efficacement ces problèmes.

N'oubliez pas que le test régulier de votre mécanisme de basculement, combiné à une surveillance complète et au respect des meilleures pratiques, est crucial pour garantir la résilience et la fiabilité de votre configuration PostgreSQL à haute disponibilité. Cette approche proactive garantit que votre base de données reste disponible et que vos applications fonctionnent de manière cohérente, même face à des défis inattendus.