Managers, workers e o quórum do Raft
Os managers do Docker Swarm são os nós que guardam o estado do cluster e escolhem onde cada tarefa roda. Eles mantêm esse estado igual entre si pelo algoritmo de consenso Raft, que só aceita uma mudança aprovada pela maioria dos managers, o quórum, por isso o tamanho dessa maioria define quantos managers o cluster perde sem parar de aceitar comandos.
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
O que cada manager faz
Além de guardar o estado, um manager agenda os serviços nos nós e responde aos endpoints da API do Swarm. Quando você roda docker service create ou docker stack deploy, o comando chega a um manager, que grava a mudança no estado compartilhado. Entre os managers, um é o líder do Raft. Ele propõe as mudanças, recebe a confirmação dos outros e conduz o agendamento das tarefas.
Os outros managers guardam uma cópia completa do mesmo estado. Por isso a queda do líder não apaga nada: os managers restantes elegem um novo líder, que retoma o agendamento e reequilibra as tarefas para chegar ao estado desejado. O comando docker node ls mostra essa situação na coluna MANAGER STATUS, com Leader no líder, Reachable nos managers que respondem e Unreachable no manager que os outros não alcançam.
Workers executam containers
Os workers também são instâncias do Docker Engine, com uma função só: executar containers. Eles não participam do Raft, não escolhem posicionamento e não servem a API do Swarm. Um worker não existe sem pelo menos um manager no cluster, mas um cluster pode ter só um manager e nenhum worker. Nesse desenho, o scheduler coloca todas as tarefas na própria máquina.
O comando docker node promote transforma um worker em manager, por exemplo para cobrir um manager que vai sair para manutenção. O docker node demote faz o caminho inverso e devolve um manager ao papel de worker. A identidade de cada nó vem de um certificado TLS emitido pelo manager no momento da entrada, com o papel gravado no próprio certificado. Os nós renovam esse certificado a cada três meses por padrão.
Quórum, a maioria que mantém o cluster administrável
O Raft tolera a falha de até (N-1)/2 managers e exige que (N/2)+1 deles concordem com cada mudança, com a divisão arredondada para baixo. O guia de administração oficial traz o resultado para os tamanhos mais comuns:
| Managers | Maioria exigida | Managers que podem cair |
|---|---|---|
| 1 | 1 | 0 |
| 2 | 2 | 0 |
| 3 | 2 | 1 |
| 4 | 3 | 1 |
| 5 | 3 | 2 |
| 7 | 4 | 3 |
A tabela explica a recomendação de um número ímpar de managers. Com quatro managers, você continua tolerando a perda de um só, exatamente como com três, mas cada mudança precisa de uma confirmação a mais. Dois managers são o pior caso: a queda de qualquer um deles derruba o quórum, porque um único manager não forma maioria de dois. A documentação também registra que um número ímpar aumenta a chance de um dos lados manter a maioria quando a rede se divide em dois grupos.
O diagrama abaixo mostra um cluster com cinco managers logo depois da queda de dois deles:
managers (5)Maioria exigida de três managers.manager-1 LeaderLíder atual, conduz o agendamento.manager-2 ReachableConfirma as mudanças propostas pelo líder.manager-3 ReachableCompleta a maioria de três.manager-4 UnreachableFora do ar, sem voto até voltar.manager-5 UnreachableFora do ar, sem voto até voltar.
O cluster sem quórum não derruba os seus apps, porque as tarefas que já rodam nos workers continuam rodando. A perda fica na administração: você não acrescenta nem remove nós e não cria nem atualiza serviços. Nenhuma tarefa começa, para ou muda de lugar até o quórum voltar. A página Failover e recuperação mostra como o cluster sai dessa situação.
Quantos managers usar e onde colocar
Com três managers, o cluster tolera a perda de um. Com cinco, tolera a perda de dois ao mesmo tempo. Essa margem aparece quando você desliga um manager de propósito para copiar o diretório /var/lib/docker/swarm no backup: com esse manager parado, o cluster ainda aguenta outra falha sem perder o quórum. Para o quórum resistir à queda de um datacenter inteiro, a documentação recomenda espalhar os managers por pelo menos três zonas, na proporção 1-1-1 para três managers e 2-2-1 para cinco.
O endereço de cada manager precisa ser fixo, porque o docker swarm init anuncia esse endereço aos outros nós pela opção --advertise-addr. Se o cluster inteiro reinicia e todos os managers voltam com IP novo, nenhum nó encontra os managers nos endereços antigos e o cluster fica travado. Para os workers, a documentação aceita IP dinâmico.
Managers dedicados com Drain
Por padrão, o scheduler coloca tarefas nos managers como em qualquer worker. Em clusters pequenos, com limites de CPU e memória nos serviços, a documentação considera essa configuração aceitável. O Raft, porém, é sensível à falta de recursos: um container que consome toda a memória de um manager pode atrasar o heartbeat e a eleição de líder, a ponto de o manager perder o contato com os outros.
A disponibilidade Drain separa a gestão do cluster da execução de containers. O comando docker node update --availability drain tira as tarefas do manager, recria essas tarefas em outros nós e impede que o scheduler mande tarefas novas para ele. O manager continua votando no Raft e respondendo à API, só sem containers de serviço. O diagrama do cluster na home deste portal segue esse desenho, com três managers em Drain e os serviços nos workers.
O próximo passo é ver como o Swarm transforma um serviço em tarefas e escolhe o nó de cada uma, na página Serviços, réplicas e posicionamento.