Patroni y etcd/Consul

Patroni 3.x automatiza la elección de líder de PostgreSQL, el failover y la gestión de configuración. Almacena el estado del clúster en un almacén de configuración distribuido (DCS): etcd o Consul.

Receta

Clúster Patroni de tres nodos con quorum etcd y PostgreSQL 18.4.

# /etc/patroni/patroni.yml (fragmento)
scope: prod-pg18
namespace: /service/
name: pg1
 
restapi:
  listen: 0.0.0.0:8008
  connect_address: 10.0.1.11:8008
 
etcd3:
  hosts: 10.0.2.1:2379,10.0.2.2:2379,10.0.2.3:2379
 
bootstrap:
  dcs:
    ttl: 30
    loop_wait: 10
    retry_timeout: 10
    maximum_lag_on_failover: 1048576
  initdb:
    - encoding: UTF8
    - data-checksums
 
postgresql:
  listen: 0.0.0.0:5432
  connect_address: 10.0.1.11:5432
  data_dir: /var/lib/postgresql/18/main
  authentication:
    replication:
      username: replicator
      password: repl-secret
    superuser:
      username: postgres
      password: postgres-secret

# Iniciar Patroni en cada nodo
sudo systemctl enable --now patroni
 
# Estado del clúster
patronictl -c /etc/patroni/patroni.yml list

Cuándo usar esto: PostgreSQL HA autoalojado con failover automatizado y comprobaciones de estado basadas en API.

Ejemplo de Trabajo

Despliegue de etcd, bootstrap de Patroni, verificación del candidato a failover:

# Salud del clúster etcd de 3 nodos
etcdctl endpoint health --endpoints=https://10.0.2.1:2379,https://10.0.2.2:2379,https://10.0.2.3:2379
 
# Vista del clúster Patroni
patronictl -c /etc/patroni/patroni.yml list

-- En cualquier miembro a través del endpoint gestionado por Patroni
SELECT pg_is_in_recovery();

# Cambio controlado (no failover de emergencia)
patronictl -c /etc/patroni/patroni.yml switchover --master pg1 --candidate pg2 --force

Lo que esto demuestra:

• etcd proporciona quorum para el bloqueo del líder (/service/prod-pg18/leader).
• Patroni gestiona postgresql.conf, la configuración de recuperación y la promoción.
• patronictl switchover ejerce un cambio de líder planificado con protección de lag (maximum_lag_on_failover).

Profundización

Opciones de DCS

Responsabilidades de Patroni

• Adquisición y renovación de la clave de líder en DCS
• Reconfiguración de réplicas después del failover (actualizaciones de primary_conninfo)
• Gestión opcional del modo síncrono
• API REST en el puerto 8008 para salud y orquestación
• Integración con callbacks (recargar HAProxy, notificar PgBouncer)

Configuraciones Clave de DCS

Errores Comunes

• etcd de dos nodos - Sin quorum; riesgo de split-brain en partición. Solución: Número impar de nodos etcd (3 o 5).
• Patroni sin watchdog - Rara vez doble primario si el fencing falla. Solución: Habilitar watchdog en hosts Linux.
• maximum_lag_on_failover demasiado alto - Promover réplica obsoleta, gran RPO. Solución: Establecer según el SLA de lag de bytes medido.
• Configuración errónea de ACL de token de Consul - Patroni no puede escribir la clave de líder. Solución: Probar patronictl list después de cambios en ACL.
• pg_ctl promote manual que omite Patroni - Desincronización del estado del clúster. Solución: Usar siempre patronictl failover o switchover.

Alternativas

Preguntas Frecuentes

Relacionados

• Conceptos Básicos de HA - Contexto RTO/RPO
• Prevención de Split-Brain - Fencing y quorum
• Proxies de Conexión - Integración con HAProxy
• Conceptos Básicos de Streaming Replication - Configuración de réplica

Versiones de Stack: Esta página fue escrita para PostgreSQL 18.4 (estable 18, mantenimiento 17), pgvector 0.8+, PgBouncer 1.x, Patroni 3.x, y PostGIS 3.5+.