Arquitectura del cluster Patroni

Un cluster Patroni típico tiene estos componentes:

  • Patroni (daemon Python): corre en cada nodo PostgreSQL. Gestiona el ciclo de vida de PostgreSQL, compite por el liderazgo en el DCS y coordina el failover.
  • DCS (Distributed Configuration Store): etcd, Consul o ZooKeeper. Actúa como árbitro único de quién es el líder. Debe tener al menos 3 nodos para tolerancia a fallos.
  • HAProxy: balanceador que detecta el líder actual via el endpoint REST de Patroni (/primary y /replica) y distribuye conexiones.
  • PgBouncer: pooler de conexiones que se sitúa entre la aplicación y HAProxy, reutilizando conexiones de PostgreSQL y reduciendo la carga de max_connections.
  • Watchdog: dispositivo del SO (/dev/watchdog) que reinicia el servidor si Patroni deja de alimentarlo, previniendo split-brain.

Síntomas que indican problemas en el cluster

  • patronictl list muestra un nodo con rol Replica pero estado stopped o unknown
  • patronictl list no muestra ningún nodo como Leader
  • La aplicación recibe errores de conexión durante un failover inesperado
  • Logs de Patroni muestran "DCS is not accessible" o "failover is not allowed during pause"
  • El lag de replicación entre el líder y las réplicas supera el umbral de seguridad
  • HAProxy muestra todos los backends en estado DOWN

Riesgos para el negocio

  • Un failover mal configurado puede resultar en split-brain y pérdida o corrupción de datos
  • Si el DCS no tiene quórum, el cluster pausa y no acepta failover — la disponibilidad depende del DCS
  • Una réplica muy atrasada puede promoverse con datos incompletos si el líder falla
  • Si PgBouncer no está configurado con reconexión automática, las sesiones no se recuperan solas

Comandos de operación diaria con patronictl

Checklist de configuración y operación

  • 1. El DCS tiene al menos 3 nodos para quórum Con 2 nodos o 1 solo etcd, la falla del DCS paraliza el cluster completamente. La recomendación mínima es 3 nodos etcd.
  • 2. TTL y loop_wait están correctamente configurados ttl debe ser mayor que loop_wait * 2. Un TTL muy bajo genera failovers espurios; muy alto retrasa la detección de fallos.
  • 3. Watchdog habilitado para prevenir split-brain Sin watchdog, un nodo que pierde conexión con el DCS podría seguir aceptando escrituras mientras una réplica se promueve.
  • 4. HAProxy configurado con healthcheck al endpoint de Patroni
  • 5. maximum_lag_on_failover configurado Evita que una réplica muy atrasada se promueva automáticamente. Si el lag en bytes supera este valor, la réplica no es elegible.
  • 6. La aplicación maneja reconexiones después de un failover En un failover, las conexiones activas se cortan. La aplicación debe reintentar la conexión. PgBouncer con reconnect_timeout adecuado ayuda a absorber el impacto.
  • 7. Verificar lag de replicación entre nodos periódicamente
  • 8. Realizar un switchover de prueba periódicamente Un cluster que nunca ha sido switcheado puede fallar en el momento crítico por razones no previstas. Los switchovers programados verifican que todo funciona y entrenan al equipo.

Cuándo escalar el incidente a un DBA especialista

  • El cluster entró en estado de pausa por pérdida de DCS y la primaria sigue activa sin failover posible
  • Hay evidencia de split-brain: dos nodos que creen ser el líder simultáneamente
  • El failover automático no ocurrió después de la muerte del líder y hay downtime prolongado
  • Hay pérdida de datos después de un failover no planeado (timeline divergence)
  • El cluster tiene un nodo "Replica" que no puede re-incorporarse al cluster después de una pausa

Preguntas frecuentes

¿Qué pasa con el cluster si el DCS (etcd) se cae?

Patroni entra en modo de pausa: no realiza cambios en el cluster, no permite failover automático y no puede elegir un nuevo líder hasta que el DCS se recupere. El líder actual puede continuar sirviendo tráfico de escritura, pero no puede confirmar su liderazgo. Este comportamiento es intencional para prevenir split-brain. Por eso etcd debe tener al menos 3 nodos (tolerancia a 1 falla) o 5 nodos (tolerancia a 2 fallos) para garantizar quórum.

¿Qué es el split-brain en Patroni y cómo se previene?

Split-brain ocurre cuando dos nodos creen simultáneamente que son el líder del cluster, ambos aceptan escrituras y los datos divergen — situación que puede ser irrecuperable. Patroni lo previene usando el DCS como árbitro único de quién posee el leader lock. Adicionalmente, el watchdog del sistema operativo reinicia o apaga el nodo que pierde conexión con el DCS, garantizando que no haya dos primarios activos al mismo tiempo.

¿Cuánto tiempo tarda un failover automático?

Típicamente entre 15 y 45 segundos desde que Patroni detecta la falla del líder hasta que la réplica más avanzada se promueve y HAProxy redirige el tráfico. El tiempo depende del valor de ttl configurado en el DCS (tiempo que tarda el lock de liderazgo en expirar), la velocidad de respuesta del DCS, y el tiempo que tarda la réplica en completar su promoción. Valores típicos de producción: ttl=30s, loop_wait=10s.

¿Patroni puede usarse con instancias PostgreSQL en la nube?

Sí. Patroni funciona bien en EC2, GCE, VMs de Azure y entornos on-premises. Para Kubernetes existe el operador Patroni (Zalando Postgres Operator) que gestiona clusters Patroni como recursos nativos de Kubernetes. El DCS puede ser etcd externo, un etcd gestionado (como el de EKS) o Consul. La principal consideración es que el DCS tenga baja latencia con los nodos de PostgreSQL.

Recursos relacionados