Solución de problemas de errores comunes de conmutación por error y conexión en clústeres HA de PostgreSQL

Los clústeres de alta disponibilidad (HA) de PostgreSQL están diseñados para garantizar la operación continua de la base de datos incluso ante fallos de hardware, interrupciones de red u otras disrupciones imprevistas. Un componente crítico de cualquier configuración de HA es el mecanismo de conmutación por error (failover), que promueve automáticamente una réplica para que se convierta en la nueva principal cuando la principal actual deja de estar disponible. Si bien son robustos, los procesos de conmutación por error a veces pueden encontrar problemas, lo que lleva a tiempo de inactividad de la aplicación o inconsistencias en los datos.

Este artículo profundiza en los errores comunes de conmutación por error y conexión en clústeres HA de PostgreSQL. Exploraremos problemas típicos como fallos en la reconexión de aplicaciones a través de pools de conexiones, retraso excesivo de la réplica que afecta la consistencia de los datos y transiciones de la principal estancadas. Para cada problema, analizaremos las causas subyacentes, técnicas de depuración efectivas utilizando herramientas estándar de PostgreSQL y utilidades del sistema, y soluciones prácticas para garantizar transiciones de la principal automatizadas y fluidas, y una conectividad de aplicación sin interrupciones. Al comprender y abordar estos desafíos de manera proactiva, puede mantener la confiabilidad y el rendimiento de su entorno HA de PostgreSQL.

Comprensión de los conceptos básicos de HA de PostgreSQL

Antes de sumergirse en la solución de problemas, es esencial recapitular brevemente los componentes principales de un clúster HA de PostgreSQL:

Arquitectura Principal/Réplica: Una base de datos principal maneja todas las operaciones de escritura, mientras que una o más réplicas reciben de forma asíncrona o síncrona los cambios a través de la replicación por streaming. Las réplicas son de solo lectura, pero sirven como candidatas para la promoción durante una conmutación por error.
Gestor de Conmutación por Error (Failover Manager): Herramientas como Patroni, pg_auto_failover o Corosync/Pacemaker monitorean la salud de la principal, detectan fallos, eligen una nueva principal entre las réplicas disponibles y gestionan el proceso de promoción. También se encargan de reconfigurar otras réplicas para que sigan a la nueva principal.
Agrupación de Conexiones (Connection Pooling): Las aplicaciones a menudo se conectan a un pooler de conexiones de PostgreSQL (por ejemplo, PgBouncer, Odyssey) en lugar de directamente a la base de datos. El pooler luego dirige las consultas a la principal actual, proporcionando multiplexación de conexiones, balanceo de carga y, potencialmente, abstrae la dirección de red real de la principal de las aplicaciones. Esta abstracción es crucial durante una conmutación por error.

Problemas comunes de conmutación por error y conexión y sus soluciones

1. Fallos en la agrupación de conexiones durante la conmutación por error

Uno de los problemas más frecuentes después de una conmutación por error es que las aplicaciones no logran reconectarse a la nueva principal promovida, a pesar de que la base de datos en sí está operativa. Esto a menudo apunta a problemas con el pooler de conexiones o el caché del lado del cliente.

Síntomas del problema:

Las aplicaciones informan errores de conexión a la base de datos (FATAL: database "mydb" does not exist, connection refused, server closed the connection unexpectedly).
Las conexiones existentes a través del pooler parecen estar estancadas o intentan conectarse a la IP de la principal anterior.
Las nuevas conexiones también fallan, incluso después de que se complete la conmutación por error.

Causas subyacentes:

Conexiones obsoletas en el Pooler: El pooler de conexiones podría mantener conexiones abiertas a la principal anterior e intentar reutilizarlas, lo que genera errores cuando la principal anterior está caída o ahora es una réplica.
Configuración incorrecta del Pooler: El pooler podría no estar configurado para detectar y cambiar correctamente a la nueva principal, o su server_reset_query podría faltar o ser incorrecto.
Caché DNS: Si sus aplicaciones o el pooler utilizan una entrada DNS para resolver la dirección de la principal, las entradas de caché DNS obsoletas (ya sea localmente o a nivel del resolvedor DNS) pueden hacer que continúen intentando conectarse a la IP anterior.
Falta de lógica de reintento del lado del cliente: Las aplicaciones podrían no estar construidas con mecanismos de reintento robustos para manejar problemas de conexión transitorios durante una conmutación por error.

Pasos de depuración:

Verificar el estado del Pooler: Acceda a la consola de su pooler (por ejemplo, psql -p 6432 pgbouncer -U pgbouncer) y verifique la salida de SHOW SERVERS, SHOW CLIENTS, SHOW DATABASES para ver si está al tanto de la nueva principal y si tiene conexiones activas a la dirección correcta.
Verificar la conectividad de red: Desde el host del pooler, use ping y telnet al puerto de PostgreSQL de la nueva principal (telnet new_primary_ip 5432).
Inspeccionar los registros del Pooler: Revise los registros del pooler en busca de mensajes de error relacionados con la conexión a la base de datos o intentos de resolución de nombres de host.
Verificar la resolución DNS: Utilice dig o nslookup en el host del pooler para asegurarse de que el registro DNS para el punto final de su servicio principal (por ejemplo, primary.mydomain.com) se resuelva a la dirección IP de la nueva principal.

Soluciones:

Configurar server_reset_query: Asegúrese de que su pooler tenga un server_reset_query (por ejemplo, DISCARD ALL;) para limpiar el estado de la sesión cuando una conexión se devuelve al pool y antes de que sea reutilizada por otro cliente. Esto es crucial para entornos que utilizan objetos temporales o configuraciones específicas de sesión.
max_db_connections y max_user_connections: Establezca límites apropiados para evitar que el pooler acapare todas las conexiones a la nueva principal, lo que podría agotar otros servicios.
Recargar/Reiniciar Pooler: En algunos casos, puede ser necesario recargar o reiniciar el pooler de conexiones para forzarlo a captar nuevas configuraciones o resolver DNS nuevamente. Esto debe ser un último recurso y preferiblemente automatizado por su gestor de conmutación por error.
TTL DNS más corta: Si utiliza el descubrimiento de servicios basado en DNS, configure un Time-To-Live (TTL) muy corto para el registro DNS de la principal (por ejemplo, 30-60 segundos) para minimizar el impacto del caché DNS.
Reintentos del lado del cliente: Implemente lógica de reintento y retroceso exponencial en el código de su aplicación. Esto hace que las aplicaciones sean más resistentes a problemas de conexión transitorios durante una conmutación por error.
IP Virtual (VIP): Considere usar una IP Virtual gestionada por su solución HA. La VIP se mueve con la principal, por lo que las aplicaciones se conectan a una IP estática y el servidor de base de datos subyacente cambia de forma transparente.

# Fragmento de configuración de ejemplo de PgBouncer
[databases]
mydb = host=primary_cluster_service_ip port=5432 dbname=mydb
# O usando un nombre de host que se actualiza por su gestor de conmutación por error
# 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 # Cierra conexiones rápidamente si el servidor no responde
server_check_delay = 10 # Comprueba la salud del servidor cada 10 segundos

2. Retraso excesivo de la réplica que dificulta la conmutación por error

El retraso de la réplica ocurre cuando una base de datos en espera se retrasa con respecto a la principal, lo que significa que no ha reproducido todos los registros WAL (Write-Ahead Log) enviados por la principal. Durante una conmutación por error, la promoción de una réplica con un retraso considerable puede provocar pérdida de datos o retrasar significativamente el proceso de conmutación por error si el gestor HA espera a que se ponga al día.

Síntomas del problema:

Las alertas de monitoreo indican un retraso considerable de la réplica (por ejemplo, en bytes o tiempo).
Los gestores de conmutación por error se niegan a promover una réplica debido a que excede un umbral de retraso configurado.
Después de la conmutación por error, las aplicaciones observan datos faltantes que estaban presentes en la principal anterior.

Causas subyacentes:

Alta carga de escritura principal: Un volumen sostenido y alto de operaciones de escritura en la principal puede abrumar la capacidad de la réplica para mantenerse al día, especialmente si el hardware de la réplica (E/S, CPU) es inferior.
Latencia/Ancho de banda de red: Los enlaces de red lentos o congestionados entre la principal y la réplica pueden retrasar el envío de WAL.
E/S lenta de la réplica: El subsistema de disco de la réplica podría no ser lo suficientemente rápido para escribir y reproducir registros WAL de manera eficiente.
Configuración wal_level: Si wal_level no está configurado como replica o superior, no se generará la información necesaria para la replicación.
max_wal_senders: Un max_wal_senders insuficiente en la principal puede limitar el número de ranuras de replicación activas o conexiones de replicación concurrentes, afectando el rendimiento.
Problemas con archive_command / restore_command: Si se utiliza el archivado y la recuperación de WAL, los problemas con estos comandos (por ejemplo, almacenamiento de archivo lento) pueden causar retrasos.

Pasos de depuración:

Monitorear pg_stat_replication: Esta vista proporciona información en tiempo real sobre el estado de la replicación, incluido write_lag, flush_lag y replay_lag.
Comparar LSNs: Compare manualmente el LSN de WAL actual en la principal con el último LSN reproducido en la réplica.
Verificar los recursos del sistema: Use iostat, vmstat, top en la principal y la réplica para identificar cuellos de botella de E/S, saturación de CPU o presión de memoria.
Diagnóstico de red: Pruebe el rendimiento de la red entre la principal y la réplica usando iperf.

Soluciones:

Aumentar max_wal_senders: En la principal, aumente max_wal_senders (por ejemplo, max_wal_senders = 10) para permitir más conexiones de replicación concurrentes. Se requiere reinicio.
Mejorar el hardware de la réplica: Si la E/S o la CPU son un cuello de botella, considere actualizar el hardware de la réplica u optimizar su configuración de almacenamiento (por ejemplo, SSD más rápidos, disco WAL separado).
Ajustar wal_compression: En la principal, configurar wal_compression = on (PostgreSQL 14+) puede reducir el volumen de WAL, mejorando potencialmente la velocidad de replicación en enlaces con red limitada, pero a costa de la CPU de la principal.
Ajustar wal_keep_size o wal_keep_segments: Asegúrese de que se retengan suficientes archivos WAL en la principal para evitar que las réplicas pierdan la sincronización y requieran una copia de seguridad base completa.
synchronous_commit: Si bien synchronous_commit = on proporciona garantías de durabilidad de datos más sólidas, introduce latencia para las escrituras en la principal. Use remote_write o remote_apply para tablas o transacciones específicas si se necesita replicación síncrona estricta, pero evalúe cuidadosamente el impacto en el rendimiento.
Monitoreo y Alertas: Implemente un monitoreo robusto para pg_stat_replication y configure alertas para cuando el retraso supere los umbrales aceptables.

-- En la Principal: Comprobar el LSN de WAL actual
SELECT pg_current_wal_lsn();

-- En la Réplica: Comprobar el estado de replicación y el retraso
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. Transición de principal fallida o colgada

Una conmutación por error automática debería promover una réplica de forma rápida y fiable. Cuando este proceso se estanca o falla por completo, puede provocar tiempos de inactividad prolongados y requerir intervención manual.

Síntomas del problema:

No se elige ni se promueve una nueva principal después de que la principal anterior se cae.
El clúster entra en un estado de "cerebro dividido" (split-brain) donde dos nodos creen ser la principal.
Los registros del gestor de conmutación por error muestran errores relacionados con el quórum, la elección del líder o la promoción de la base de datos.
Las aplicaciones permanecen caídas porque no hay una principal disponible.

Causas subyacentes:

Cerebro dividido (Split-Brain): Ocurre cuando las particiones de red aíslan los nodos, lo que lleva a múltiples principales o a una elección de principal ambigua. Este es el escenario más peligroso, ya que arriesga la divergencia de datos.
Problemas de quórum: El gestor de conmutación por error podría no ser capaz de alcanzar un quórum (voto mayoritario) entre sus nodos, lo que le impide tomar una decisión sobre la promoción. Esto es común en clústeres con un número par de nodos o muy pocos nodos.
Aislamiento de red: Los nodos del gestor de conmutación por error no pueden comunicarse entre sí o con las instancias de PostgreSQL, lo que impide las verificaciones de estado o la ejecución de comandos.
Privilegios insuficientes: El usuario del gestor de conmutación por error podría carecer de los permisos necesarios de PostgreSQL (por ejemplo, pg_promote()) o permisos a nivel de sistema (por ejemplo, para administrar VIP).
Errores de configuración: Configuraciones restore_command, primary_conninfo u otras configuraciones incorrectas dentro de la configuración del gestor de conmutación por error.

Pasos de depuración:

Verificar los registros del gestor de conmutación por error: Esta es la fuente principal de información. Para Patroni, mire sus registros específicos (a menudo journalctl -u patroni o el archivo de registro configurado en patroni.yml). Para pg_auto_failover, verifique los registros de journalctl -u pgautofailover_monitor y del agente.
Verificar el estado del quórum: Para Patroni, use patronictl list para ver el estado de todos los miembros del clúster y confirmar el líder electo. Para pg_auto_failover, verifique pg_autoctl show state.
Conectividad de red: Realice verificaciones de ping, traceroute y telnet entre todos los nodos HA y el almacén de consenso distribuido (por ejemplo, Etcd, Consul, ZooKeeper para Patroni).
Registros del sistema: Verifique journalctl -xe o /var/log/syslog en todos los nodos en busca de errores a nivel de sistema que puedan interferir con el gestor de conmutación por error (por ejemplo, disco lleno, problemas de memoria).
Registros de PostgreSQL: Examine los registros de PostgreSQL en la réplica candidata para la promoción para ver si informa algún problema durante el intento de promoción.

Soluciones:

Implementar Fencing/STONITH: (Shoot The Other Node In The Head) es crucial para prevenir el "cerebro dividido" asegurando que una principal fallida se apague por completo antes de que se promueva una nueva. Esto lo maneja típicamente el gestor de conmutación por error.
Número impar de nodos para el quórum: Siempre implemente un número impar de nodos de votación (por ejemplo, 3, 5) para el almacén de consenso distribuido de su gestor de conmutación por error (Etcd, Consul, ZooKeeper) para garantizar que el quórum siempre se pueda lograr, incluso si uno o dos nodos fallan.
Configuración de red robusta: Asegure rutas de red redundantes, reglas de firewall adecuadas que permitan la comunicación en puertos necesarios (PostgreSQL, almacén de consenso, API de Patroni) y una resolución de nombres de host consistente.
Verificación de permisos: Verifique que la cuenta de usuario que ejecuta el gestor de conmutación por error tenga todos los privilegios de PostgreSQL y permisos de sistema necesarios para realizar tareas de promoción y reconfiguración.
Revisar la configuración del gestor de conmutación por error: Vuelva a verificar la configuración de patroni.yml o pg_auto_failover en busca de errores tipográficos, rutas incorrectas o restore_command mal configurado.
Intervención manual (con cautela): En una conmutación por error grave y atascada, puede ser necesaria la promoción manual o la reactivación de nodos. Proceda con extrema precaución, asegurándose de que la principal anterior esté completamente apagada antes de promover una nueva para evitar la divergencia de datos.

# Ejemplo: Comprobación del estado del clúster Patroni
patronictl -c /etc/patroni/patroni.yml list

# Salida esperada (ejemplo):
# + 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. Problemas de conectividad de red y resolución DNS

En la raíz de muchos problemas de HA se encuentran problemas fundamentales de red, que impiden que los nodos se comuniquen o que las aplicaciones encuentren el punto final de base de datos correcto.

Síntomas del problema:

Errores de connection refused o no route to host de las aplicaciones o entre los nodos del clúster.
El gestor de conmutación por error informa que los nodos no son alcanzables.
Los servicios que dependen de DNS no pueden resolver correctamente el nombre de host de la principal.

Causas subyacentes:

Reglas de Firewall: Reglas de firewall configuradas incorrectamente (por ejemplo, iptables, grupos de seguridad) que bloquean el puerto de PostgreSQL (5432), los puertos del gestor de conmutación por error o los puertos del almacén de consenso.
Partición de red: División de red física o lógica que impide la comunicación entre un subconjunto de nodos.
Enrutamiento incorrecto: Enrutamiento de red mal configurado en uno o más nodos.
Caché/Error de configuración de DNS: Como se discutió en la Sección 1, los registros DNS obsoletos o una configuración incorrecta del servidor DNS pueden desviar el tráfico.
Fallo de migración de IP Virtual (VIP): Si se utiliza una VIP, podría fallar al migrar a la nueva principal, dejando el servicio inalcanzable.

Pasos de depuración:

Conectividad básica: Use ping <target_ip> entre todos los nodos.
Conectividad de puertos: Use telnet <target_ip> <port> (por ejemplo, telnet 192.168.1.10 5432) para verificar que el puerto de PostgreSQL esté abierto y escuchando.
Verificación de Firewall: En cada nodo, verifique las reglas de firewall activas (sudo iptables -L, sudo ufw status, o configuraciones de grupos de seguridad del proveedor de la nube).
Estado de la interfaz de red: Use ip addr show o ifconfig para asegurarse de que las interfaces de red estén activas y configuradas correctamente.
Resolución DNS: Use dig <hostname> o nslookup <hostname> para verificar la resolución de nombres de host desde los nodos relevantes (servidores de aplicaciones, pooler, nodos HA).

Soluciones:

Revisar las reglas de Firewall: Asegúrese de que los puertos necesarios estén abiertos para PostgreSQL (5432), el plano de control del gestor de conmutación por error (por ejemplo, 8008 para la API de Patroni, 8000/8001 para pg_auto_failover) y el almacén de consenso distribuido (por ejemplo, Etcd: 2379/2380, Consul: 8300/8301/8302).
Red consistente: Asegúrese de que todos los nodos estén en la misma subred o tengan la configuración de enrutamiento correcta si abarcan varias subredes.
Actualizaciones DNS: Automatice las actualizaciones DNS como parte del proceso de conmutación por error, o use un TTL más corto. Las VIP a menudo se prefieren por esta razón.
Gestión de VIP: Si usa una VIP, asegúrese de que la herramienta de gestión de VIP (por ejemplo, Keepalived, gestión de IP del proveedor de la nube) esté configurada correctamente y funcione. Pruebe la migración de VIP explícitamente.
Acceso basado en host: Para simplificar en clústeres más pequeños, asegúrese de que pg_hba.conf permita conexiones desde todas las direcciones IP potenciales de principal/réplica y la IP del pooler de conexiones.

Herramientas esenciales para la solución de problemas

psql: Para ejecutar consultas SQL como pg_stat_replication, pg_current_wal_lsn(), comandos SHOW *.
CLI del gestor de conmutación por error: patronictl, pg_autoctl para consultar el estado del clúster, registros e iniciar acciones.
Monitoreo del sistema: Herramientas como Prometheus + Grafana, Zabbix, Nagios o el monitoreo del proveedor de la nube para obtener información en tiempo real sobre la utilización de recursos, el retraso de la replicación y el estado del servicio.
journalctl / tail -f: Para ver registros del sistema y de aplicaciones.
Utilidades de red: ping, traceroute, telnet, iperf, netstat, dig, nslookup para diagnosticar la conectividad.
dmesg: Para errores a nivel de kernel, especialmente relacionados con E/S de disco o el asesino OOM (Out Of Memory).

Mejores prácticas para prevenir problemas de conmutación por error

Pruebas regulares de conmutación por error: Simule fallos de la principal regularmente y observe el proceso de conmutación por error. Esto genera confianza y expone configuraciones erróneas.
Monitoreo y alertas robustos: Monitoree métricas clave como el retraso de la réplica, el estado de la principal, la salud del pooler de conexiones y los recursos del sistema. Configure alertas para cualquier desviación.
Configuración adecuada del pooler de conexiones: Asegúrese de que server_reset_query esté configurado, que pool_mode sea apropiado para su aplicación y que las verificaciones de salud estén habilitadas.
Ajustar los parámetros de replicación: Configure wal_level, max_wal_senders, wal_keep_size y synchronous_commit cuidadosamente según sus requisitos de rendimiento y durabilidad.
Documentar su configuración HA: Documente claramente su arquitectura HA, la configuración del gestor de conmutación por error, la configuración de red y los procedimientos de recuperación.
Usar un gestor de conmutación por error dedicado: Confíe en soluciones probadas como Patroni o pg_auto_failover en lugar de scripts personalizados para la lógica crítica de HA.
Almacén de consenso dedicado: Si usa un gestor como Patroni, implemente un clúster separado y de alta disponibilidad para su almacén de consenso distribuido (Etcd, Consul) para evitar un único punto de fallo.

Conclusión

Construir y mantener un clúster HA de PostgreSQL robusto requiere una planificación, configuración y monitoreo proactivo cuidadosos. Si bien la conmutación por error automática reduce significativamente el tiempo de inactividad, aún pueden surgir problemas comunes relacionados con la agrupación de conexiones, el retraso de la réplica y el propio proceso de conmutación por error. Al comprender los síntomas y las causas subyacentes típicas, y utilizando las técnicas de depuración y las soluciones descritas en esta guía, puede solucionar y prevenir eficazmente estos problemas.

Recuerde que las pruebas regulares de su mecanismo de conmutación por error, combinadas con un monitoreo integral y la adhesión a las mejores prácticas, son cruciales para garantizar la resiliencia y la confiabilidad de su configuración de Alta Disponibilidad de PostgreSQL. Este enfoque proactivo garantiza que su base de datos permanezca disponible y que sus aplicaciones funcionen de manera consistente, incluso cuando se enfrentan a desafíos inesperados.