Failover e recuperação do cluster
Failover, no Docker Swarm, é a reação do cluster à perda de um nó. Os managers marcam como perdidas as tarefas do nó que parou de responder e criam tarefas novas nos nós disponíveis, por isso o serviço volta ao número de réplicas declarado depois da queda de um worker ou de um manager, desde que a maioria dos managers continue no ar.
Ficha e sumário da página
- Referência técnica
- Docker Engine v29.9.3
- Revisão
- 13 de novembro de 2026
- Conteúdo
- Documentação oficial consultada
Quando um worker cai
Cada nó envia heartbeats ao manager, no período padrão de 5 segundos definido pela opção --dispatcher-heartbeat do docker swarm init. Um nó que para de responder fica com o status Down no docker node ls. A partir daí, o orquestrador compara o estado real com o desejado e percebe que faltam réplicas. O caminho da recuperação de um serviço com três réplicas segue esta ordem:
Nó para
worker-2 DownO manager para de receber os heartbeats do nó.
Diferença
2/3 réplicasO orquestrador vê menos tarefas em execução do que o declarado.
Tarefa nova
web.3Cria uma tarefa para o slot que ficou vazio.
Novo nó
worker-1O scheduler escolhe um nó Active que atende às constraints.
Serviço completo
3/3 réplicasO container sobe e o serviço volta ao número declarado.
Durante a recuperação, as duas réplicas restantes recebem todo o tráfego do serviço. O routing mesh e o VIP param de mandar conexões para a tarefa perdida, porque ela saiu da lista de tarefas ativas. As conexões que estavam abertas com a réplica do nó que caiu se perdem, enquanto as conexões novas seguem para as réplicas no ar.
Além da detecção da queda, o tempo de recuperação depende da capacidade sobrando nos nós restantes e do tempo que a imagem leva para baixar e subir. Uma tarefa com reserva de memória fica pendente quando nenhum nó tem essa memória livre, assunto da página Serviços, réplicas e posicionamento.
Quando um manager cai
A queda de um manager que não é o líder não muda nada para os serviços. O cluster segue com quórum enquanto a maioria dos managers responde. Quando o líder cai, os managers restantes elegem um novo líder pelo Raft. O novo líder retoma o agendamento a partir da mesma cópia do estado, sem perder serviços, secrets nem configs.
O manager que volta depois de uma queda temporária reencontra o cluster e atualiza o estado. Um manager que não volta precisa sair do grupo de managers. O guia oficial descreve a saída com docker node demote seguido de docker node rm, além da promoção de um worker ou da entrada de um manager novo para recompor o número ímpar de managers.
O que acontece sem quórum
Quando o cluster perde a maioria dos managers, os serviços continuam no ar, porque as tarefas que já rodam nos workers seguem rodando. A administração fica parada: você não escala nem atualiza serviços e não acrescenta nem remove nós. Um comando de gestão nesse estado devolve o erro rpc error: code = 4 desc = context deadline exceeded.
A melhor saída, segundo a documentação, é trazer os managers perdidos de volta. Quando isso não é possível, o comando docker swarm init --force-new-cluster, rodado num manager que sobrou, remove todos os outros managers do grupo e deixa esse nó como manager único. O quórum volta, porque um manager único é a própria maioria. O nó mantém as informações dos serviços e das tarefas, os workers continuam no cluster e os serviços continuam rodando. Depois disso, você promove ou acrescenta managers até voltar ao número desejado.
Os casos de falha se resumem assim:
| Falha | Serviços em execução | Administração do cluster |
|---|---|---|
| Um worker cai | As réplicas dele são recriadas em outros nós | Normal |
| Um manager cai, com quórum mantido | Continuam rodando | Normal, com novo líder se ele era o líder |
| A maioria dos managers cai | Continuam rodando nos workers | Parada até recuperar os managers ou usar --force-new-cluster |
| O único manager cai | Continuam rodando | Exige criar um cluster novo |
Quando o nó volta
Um worker que volta ao cluster fica disponível para tarefas novas, mas não recebe de volta as tarefas que perdeu. O Swarm evita mover tarefas em execução só para equilibrar a carga, porque isso derrubaria conexões ativas. O nó recuperado fica ocioso até uma tarefa nova, uma atualização ou um docker service update --force levar trabalho para ele.
Manutenção planejada com Drain
A disponibilidade Drain transforma uma queda em manutenção controlada. Antes de atualizar o sistema de uma VPS, você marca o nó com docker node update --availability drain. O manager para as tarefas desse nó e cria réplicas equivalentes nos nós Active. Com a VPS vazia, você reinicia a máquina e devolve o nó com --availability active.
O Drain vale só para tarefas de serviço do Swarm. Containers avulsos, criados com docker run, com docker compose up ou pela API do Engine, continuam rodando no nó drenado.
O backup do estado do cluster
O estado do cluster fica em /var/lib/docker/swarm/ em cada manager, junto com as chaves que cifram o log do Raft. A documentação recomenda parar o Docker no manager antes de copiar o diretório, para nenhuma mudança acontecer durante a cópia. Esse manager parado reduz a margem do quórum durante o backup, motivo pelo qual o guia sugere cinco managers quando o backup é frequente.
A restauração usa o mesmo docker swarm init --force-new-cluster num nó novo com o diretório restaurado. Com o autolock ligado, a chave de desbloqueio do cluster antigo também é necessária, como explica a página Secrets e configs. Esse backup guarda só o estado do cluster. Os volumes dos apps precisam de um backup próprio.
Continue na comunidade
Leve ao Discord da Promovaweb o estado dos nós e o erro da tarefa que não inicia. A comunidade pode comparar os recursos disponíveis e as restrições do serviço.
VPS para o seu cluster
Managers e workers precisam de servidores com recursos para receber as tarefas do cluster. Consulte as VPS da StayCloud para dimensionar essas máquinas com acesso root.
Link de parceiro da Promovaweb.