Cluster com failover automático usando Patroni + etcd + HAProxy

Instala e opera um cluster PostgreSQL com failover automático: em cada node o PostgreSQL é gerenciado pelo Patroni, a eleição do leader acontece em um etcd de 3 (ou 5) membros e as aplicações se conectam às portas de escrita (5000) e leitura (5001) do HAProxy, opcionalmente por um VIP do keepalived. Além da instalação, há cenários de operação para um cluster existente: verificação de saúde, switchover, reintegração do leader antigo, reinit, inclusão/remoção de node, edit-config, pause, upgrade do Patroni, desligamento/inicialização completos, troca de membro do etcd e perda de quórum do etcd. O guia pg-install não é usado nos nodes Patroni (o próprio Patroni executa o initdb); para HA sem Patroni, com failover manual, use o guia pg-streaming.

Topologia: 3 nodes PostgreSQL + etcd (compartilhados ou separados) + HAProxy (+ VIP)

Cenários

• Instalação: novo cluster Patroni — Monta do zero um cluster etcd + Patroni + HAProxy (+ VIP). Os servidores não devem ter um cluster PostgreSQL: o Patroni executa o initdb (o pg-install não é aplicado).
• Runbook de operação: switchover, teste de failover, modo de manutenção, alteração de parâmetro — Executa em sequência as operações básicas em um cluster recém-instalado: status, switchover, teste de failover (o leader é parado, breve interrupção de escrita), modo de manutenção, alteração de parâmetro. Execute em uma janela de manutenção.
• O cluster está saudável? (verificação de saúde) — Somente leitura: papéis, atraso, timeline, REST API, saúde do etcd, slots, restart pendente e modo de manutenção.
• Switchover planejado (mover o leader para outro node) — Antes da manutenção, o papel de leader passa de forma controlada para uma réplica; alguns segundos de interrupção de escrita, sem perda de dados.
• Houve failover e o leader antigo não volta ao cluster (pg_rewind / reinit) — Quando o leader antigo que caiu volta, ele deve entrar como réplica; se o pg_rewind falhar, o diretório de dados é reconstruído a partir do leader.
• Reconstruir uma réplica do zero (reinit) — A réplica está corrompida, muito atrasada ou perdeu WAL: o diretório de dados é apagado e reconstruído a partir do leader (ou de um backup). O leader não é afetado.
• Adicionar um novo node ao cluster — Adicione o novo node ao final da lista no formulário: o software é instalado, o pg_hba e o HAProxy são atualizados nos nodes existentes e o node entra como réplica.
• Remover um node do cluster — Um node que é réplica é removido definitivamente: o Patroni é parado, o registro no DCS e o slot são limpos e o node é retirado do HAProxy.
• Alterar uma configuração do PostgreSQL ou do Patroni (edit-config) — A configuração é gravada no DCS e aplicada a todos os nodes; para configurações que exigem restart, restart --pending (réplicas primeiro).
• Suspender o failover automático para manutenção (pause / resume) — Em pause, o Patroni não mexe no PostgreSQL e não faz failover; para manutenção de rede/etcd ou intervenção manual. Ao terminar, resume.
• Atualizar o software do Patroni (rolling) — O cluster entra em pause e o Patroni é atualizado e reiniciado node a node; o PostgreSQL não para e não há failover.
• Parar / iniciar o cluster inteiro (ordem correta) — Desligamento completo planejado (manutenção de storage ou de data center): primeiro as réplicas, depois o leader e por último o etcd; a inicialização segue a ordem inversa.
• Substituir ou adicionar um membro do etcd (etcdctl member) — O membro do etcd com falha é removido e um novo servidor é adicionado (ou o número de membros é aumentado); a lista de hosts etcd do Patroni é atualizada.
• Quórum do etcd perdido: o leader ficou somente leitura — Sem quórum no etcd, o Patroni coloca o leader em somente leitura e também não há failover. O etcd é recuperado ou reconstruído a partir de um único membro.

Antes de começar

• Não há cluster PostgreSQL em execução ou criado anteriormente nos nodes PostgreSQL e … está vazio (o próprio Patroni cria o cluster). O guia pg-install não foi aplicado nesses servidores.
• Todos os servidores estão na mesma versão de sistema operacional e atualizados; os relógios estão sincronizados por NTP (etcd e Patroni são sensíveis a diferença de relógio).
• … GB de RAM nos nodes PostgreSQL; … fica em disco/LV separado e com o mesmo tamanho em todos os nodes.
• Os dados do etcd (/var/lib/etcd) ficam em disco de baixa latência (SSD). Um disco lento atrapalha as eleições de leader; recomenda-se não usar o mesmo disco dos dados do PostgreSQL, que têm I/O intenso.
• Atenção: o número de nodes etcd é … (par). Um número par não aumenta a tolerância a falhas; use 3 ou 5.
• Os servidores se alcançam nestas portas: PostgreSQL …, Patroni REST 8008, etcd 2379/2380, HAProxy 5000/5001/7000…, VRRP (protocolo IP 112)…. Essas regras também estão liberadas nos equipamentos de rede intermediários.
• Os servidores alcançam por HTTPS o repositório PGDG (download.postgresql.org…, apt.postgresql.org…) e o github.com para o etcd, ou há um mirror interno configurado.
• O VIP … está livre (não é usado em nenhum servidor) e a rede (virtualização/nuvem) permite VRRP e a movimentação do mesmo IP entre servidores. Em ambientes de nuvem isso geralmente não é permitido; use o load balancer da nuvem.
• Atenção: há apenas um servidor HAProxy para o VIP; se ele cair, o VIP não tem para onde ir.
• Acesso root ou sudo em todos os servidores; janela de manutenção e plano de retorno prontos.
• …: é possível instalar o mesmo sistema operacional e a mesma versão principal do PostgreSQL dos outros nodes, há tanto disco para … quanto nos outros nodes, o relógio está sincronizado por NTP; o acesso a …, 8008 e etcd 2379 nos outros nodes está liberado.
• … (…): disco de baixa latência (SSD), relógio sincronizado por NTP, acesso liberado a 2379/2380 a partir dos outros membros do etcd e a 2379 a partir dos nodes PostgreSQL; acesso ao github.com ou o arquivo do etcd em /tmp.

Fases do guia

• Preparação (todos os servidores) — Adicionar os nomes dos servidores ao /etc/hosts · Ativar a sincronização de horário (chrony) · Configurações do kernel e THP · Regras de firewall (nodes PostgreSQL) · Regras de firewall (servidores etcd) · Regras de firewall (servidores HAProxy)
• Cluster etcd — Instalar o software do etcd · Instalar o software do etcd · Configuração do etcd: … · Criar o serviço systemd do etcd · Criar o serviço systemd do etcd · Iniciar o etcd (em todos os nodes etcd ao mesmo tempo) …
• Software do PostgreSQL e do Patroni — Adicionar o repositório PGDG · Adicionar o repositório PGDG · Instalar o PostgreSQL e o Patroni · Desativar o serviço PostgreSQL independente e preparar os diretórios
• Configuração do Patroni — Gravar as senhas no arquivo de ambiente · Vincular o arquivo de ambiente ao serviço do Patroni · patroni.yml: … · Validar a configuração
• Iniciar o cluster — Iniciar o Patroni no primeiro node · Iniciar o Patroni nos outros nodes: … · Verificar o status do cluster
• HAProxy — Instalar o HAProxy · Instalar o HAProxy · Gravar o haproxy.cfg · Gravar o haproxy.cfg · Validar e iniciar o HAProxy · Validar e iniciar o HAProxy
• VIP com keepalived — Instalar o keepalived · Instalar o keepalived · Configuração do keepalived: … · Iniciar o keepalived · Iniciar o keepalived
• Usuário da aplicação e teste de conexão — Usuário e banco de dados da aplicação · Definir a senha do usuário da aplicação · Verificar os endpoints de health check da REST API · Testar a conexão pelo HAProxy · String de conexão da aplicação
• Pós-instalação — Fazer backup snapshot do etcd · Fazer backup snapshot do etcd · Configurar o backup (obrigatório) · Conectar o monitoramento
• Status do cluster — Membros, papéis e atraso
• Switchover planejado — Executar o switchover
• Teste de failover (parar o leader) — Parar o Patroni no node leader · Acompanhar o novo leader · Iniciar novamente o leader antigo
• Modo de manutenção (pause) — Colocar o cluster em modo de manutenção · Executar a manutenção · Sair do modo de manutenção
• Alteração de parâmetro — Alterar o parâmetro no cluster inteiro · Aplicar os restarts pendentes
• Verificação de saúde (somente leitura) — Membros, papéis, timeline e atraso · Últimas trocas de leader (history) · Endpoints de saúde da REST API · Saúde do etcd · Atraso de replicação, slots e restart pendente (no leader) · Configuração e modo de manutenção
• Switchover planejado — Verificação antes do switchover · Executar o switchover · Verificar o novo leader e a reintegração do leader antigo
• Modo de manutenção (pause / resume) — Verificação antes do pause · Colocar o cluster em modo de manutenção (pause) · Executar a manutenção · Sair do modo de manutenção (resume)
• Upgrade do Patroni: preparação — Versão atual e versão de destino do Patroni · Fazer backup e validar a configuração · Colocar o cluster em modo de manutenção (pause)
• Upgrade do Patroni: finalização — Sair do modo de manutenção (resume)
• Parar o cluster (réplica → leader → etcd) — Registrar o estado e os papéis · Parar as aplicações · Parar o Patroni nas réplicas · Parar o Patroni no leader · Parar o etcd
• Iniciar o cluster (etcd → último leader → réplicas) — Iniciar o etcd (em todos os membros do etcd ao mesmo tempo) · Verificar a saúde do etcd · Iniciar primeiro o Patroni no último leader · Iniciar o Patroni nas réplicas · Verificar o cluster e liberar as aplicações
• Diagnóstico: perda de quórum do etcd — Confirmar os sintomas: sem leader, PostgreSQL somente leitura · Ver o estado dos membros do etcd
• Caminho A: trazer de volta os membros do etcd — Caminho A: iniciar os serviços do etcd · Verificar que o Patroni se recuperou
• Verificação e prevenção — Verificar o etcd e o Patroni, avaliar o failsafe