Ir para o conteúdo
Promovaweb

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
  1. Quando um worker cai
  2. Quando um manager cai
  3. O que acontece sem quórum
  4. Quando o nó volta
  5. Manutenção planejada com Drain
  6. O backup do estado do cluster

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:

  1. Nó para

    worker-2 Down

    O manager para de receber os heartbeats do nó.

  2. Diferença

    2/3 réplicas

    O orquestrador vê menos tarefas em execução do que o declarado.

  3. Tarefa nova

    web.3

    Cria uma tarefa para o slot que ficou vazio.

  4. Novo nó

    worker-1

    O scheduler escolhe um nó Active que atende às constraints.

  5. Serviço completo

    3/3 réplicas

    O container sobe e o serviço volta ao número declarado.

A recuperação acontece pelo mesmo mecanismo que mantém o estado desejado no dia a dia. Os managers só precisam de quórum e de um nó apto para cada tarefa recriada.

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.

Ver a VPS da StayCloud

Link de parceiro da Promovaweb.