Ir para o conteúdo
Promovaweb

O que é o Docker Swarm e para que serve

O Docker Swarm é o modo de cluster do Docker Engine, que junta várias máquinas com Docker num único cluster. Os managers guardam o estado desejado de cada serviço e comparam esse estado com o que está rodando, por isso as réplicas de um nó que para voltam a rodar nos nós que continuam disponíveis.

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. Um cluster feito de Docker Engines
  2. O estado desejado no lugar do comando
  3. O que a alta disponibilidade cobre
  4. Limites do Swarm
  5. O Swarm nas stacks da Promovaweb

Um cluster feito de Docker Engines

Cada máquina do cluster é um nó, uma VPS ou um servidor físico com o Docker Engine instalado. O modo Swarm vem dentro do próprio Engine, por isso você não instala outro programa para ter um cluster: o comando docker swarm init transforma a máquina atual no primeiro manager. O docker swarm join acrescenta as outras máquinas com o token que esse manager gera. O Docker Engine é construído sobre o Moby, projeto de código aberto sob licença Apache 2.0.

Cada nó tem um de dois papéis. Os managers guardam o estado do cluster, escolhem onde cada tarefa roda e respondem à API do Swarm, enquanto os workers apenas executam containers. Como um manager também recebe tarefas por padrão, do mesmo jeito que um worker, o cluster mais simples possível tem um manager e nenhum worker. O diagrama abaixo mostra um cluster com três managers, dois workers e um serviço com três réplicas:

  • swarmO cluster inteiro, administrado pelos managers.
  • manager-1 (Leader)Manager líder do Raft, que agenda as tarefas.
  • manager-2 (Reachable)Manager com a cópia do estado, pronto para assumir a liderança.
  • manager-3 (Reachable)Terceiro manager, que completa a maioria de dois em três.
  • worker-1Executa as tarefas web.1 e web.3.
  • worker-2Executa a tarefa web.2.
Exemplo de cluster com cinco nós. Os managers guardam o estado e decidem o posicionamento. As tarefas do serviço web ficam espalhadas pelos nós que aceitam trabalho.

Os managers usam o algoritmo de consenso Raft para manter a mesma cópia do estado em todos eles. A consequência prática aparece quando o manager líder cai: qualquer outro manager com a cópia atualizada assume o agendamento, desde que a maioria dos managers continue no ar. A página Managers, workers e quórum explica essa maioria e o tamanho certo do grupo de managers.

O estado desejado no lugar do comando

No Docker sem Swarm, o container que você cria com docker run ou com o Compose fica aos cuidados do Docker daquela máquina. No Swarm, a unidade de trabalho é o serviço. Você declara a imagem, o número de réplicas, as redes, os limites de memória e a política de atualização. O manager guarda essa declaração como o estado desejado do serviço.

A partir daí, o manager compara o estado desejado com o estado real do cluster de forma contínua. A documentação oficial usa um exemplo direto: um serviço com dez réplicas perde duas quando o worker que as rodava trava. O manager cria duas réplicas novas nos workers disponíveis para voltar a dez. Você não reinicia nada nem escolhe a máquina de destino.

Container no Docker Engine

  • Roda na máquina onde você executou o comando.
  • A política de reinício age só naquela máquina.
  • Se a VPS para, o container para junto com ela.
  • A atualização de imagem recria o container no mesmo lugar.

Serviço no modo Swarm

  • Roda nos nós que o scheduler escolhe.
  • O manager recria a tarefa que falha, em qualquer nó apto.
  • Se uma VPS para, as réplicas dela são recriadas em outras.
  • A atualização troca as réplicas em etapas, com volta automática possível.

Um conjunto de serviços descrito num arquivo vira uma stack. O comando docker stack deploy lê um arquivo no formato do Compose e cria ou atualiza todos os serviços, redes, secrets e configs da stack de uma vez. A documentação avisa que esse comando usa o formato legado da versão 3 do Compose, diferente da especificação atual. Por isso algumas chaves dos arquivos de Compose recentes não funcionam numa stack.

O que a alta disponibilidade cobre

O Swarm mantém um serviço no ar quando uma máquina falha porque várias peças trabalham juntas. Os managers replicam o estado entre si e toleram a perda de uma parte deles. As réplicas de um serviço ficam em nós diferentes, de modo que a perda de um nó leva só uma parte delas. A rede overlay liga os containers de nós diferentes. O routing mesh recebe o tráfego de uma porta publicada em qualquer nó, inclusive num nó sem réplica do serviço.

As outras peças cuidam da configuração e da troca de versão. Os secrets guardam senhas e certificados no log cifrado dos managers e chegam só às tarefas que têm acesso a eles. A atualização em etapas troca uma réplica de cada vez e pausa quando a nova versão falha. Cada peça tem uma página própria: Serviços, réplicas e posicionamento, Redes overlay e routing mesh, Secrets e configs, Atualizações e rollback e Failover e recuperação.

Limites do Swarm

O Swarm recria a tarefa em outro nó, mas não leva junto o disco do nó que caiu. Um volume local existe só na máquina onde foi criado. Quando a tarefa de um banco de dados volta em outro nó, o Swarm cria ali um volume novo, de acordo com a especificação do serviço, sem os arquivos gravados no nó antigo. A alta disponibilidade de serviços com estado gravado em disco exige um driver de volume compartilhado, a replicação do próprio banco ou uma constraint que prenda o serviço ao nó do volume.

O cluster também tem um ponto de parada administrativa. Sem a maioria dos managers, as tarefas que já rodam nos workers continuam rodando, mas você não cria, escala nem atualiza serviços até recuperar os managers. Num cluster com um único manager, os serviços continuam no ar quando esse manager cai, porém a recuperação exige criar um cluster novo.

O Swarm não aponta domínios para as máquinas nem emite certificados HTTPS, por isso o registro DNS continua com você. O HTTPS dos apps fica com um proxy como o Traefik, que lê os serviços do Swarm pelo provider próprio. Cada nó baixa a imagem do serviço de um registry, por isso uma imagem construída só numa máquina precisa estar num registry que todos os nós alcançam.

O Swarm nas stacks da Promovaweb

As stacks de referência da Promovaweb rodam em Docker Swarm, com os apps ligados à rede overlay network_swarm_public e o Traefik na frente deles. A automação com Ansible que acompanha essas stacks prepara as VPS, inicia o cluster e aplica as stacks. Para administrar essas stacks pelo navegador, o Portainer lê o mesmo cluster pela API do Swarm.

O próximo passo para entender o Swarm é ver como os managers mantêm o estado do cluster e quantos deles você precisa, na página Managers, workers e quórum.

StayCloud

Uma VPS para desenvolver com agentes

Servidor da StayCloud em São Paulo, com acesso root e disco NVMe, para deixar seus agentes de IA rodando o dia todo.

Montar minha VPS

Link de parceiro da Promovaweb.