Serviços, réplicas e posicionamento
Um serviço do Docker Swarm é a declaração de como um app deve rodar no cluster: a imagem, o comando, o número de réplicas, as redes e os limites de recursos. O manager guarda essa declaração como estado desejado e cria uma tarefa por réplica, que o scheduler coloca num nó para rodar exatamente um container, por isso você muda o número de réplicas do serviço sem criar nem remover containers à mão.
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
Serviço, tarefa e container
O serviço é a declaração que você escreve. A partir dela, o Swarm agenda tarefas, que são a unidade de trabalho do cluster. Num serviço web com três réplicas, o orquestrador cria três tarefas, cada uma um espaço que o scheduler preenche com um container num nó. A documentação compara a tarefa a um slot: quando o container fica no ar, a tarefa passa para o estado de execução.
A tarefa anda num sentido só e atravessa estados como ASSIGNED, PREPARING e RUNNING sem voltar a um estado anterior. Quando o container falha no health check ou termina, a tarefa termina junto com ele. O orquestrador remove a tarefa e o container e cria uma tarefa nova para ocupar o lugar, de acordo com o estado desejado do serviço. O caminho de uma réplica, da declaração ao container, segue esta ordem:
Serviço
deploy.replicas: 3A declaração que o manager guarda como estado desejado.
Orquestrador
web.1 web.2 web.3Cria uma tarefa para cada réplica que falta.
Scheduler
node.role==workerEscolhe um nó que atenda às constraints e aos recursos.
Worker
RUNNINGBaixa a imagem e roda o container da tarefa.
Essa separação explica o comportamento do Swarm quando algo falha. Uma tarefa que cai vira uma tarefa nova, talvez em outro nó, com o mesmo número de slot. Por isso uma réplica web.3 continua aparecendo como web.3 depois de recriada.
Réplicas e serviços globais
O Swarm tem dois modos de serviço. No modo replicado, que é o padrão, você define quantas tarefas idênticas quer e o scheduler distribui essas tarefas pelos nós disponíveis. No modo global, o serviço roda uma tarefa em cada nó que atende às constraints, sem número fixo. Cada nó novo que entra no cluster recebe uma tarefa do serviço global assim que fica disponível.
Serviço replicado
- Você escolhe o número de réplicas em
deploy.replicas. - O scheduler distribui as réplicas entre os nós aptos.
- Um app web com três réplicas segue no ar com a perda de um nó.
- O comando
docker service scalemuda o número de réplicas.
Serviço global
- Uma tarefa por nó, com
deploy.mode: global. - O número de tarefas acompanha o número de nós aptos.
- A documentação cita agentes de monitoramento e antivírus como uso.
- Um nó novo recebe a tarefa sem mudança no serviço.
Para alta disponibilidade, o número de réplicas faz sentido junto com o número de nós. Três réplicas espalhadas em três workers sobrevivem à queda de um worker com duas réplicas no ar enquanto o Swarm recria a terceira. Três réplicas num cluster com um worker só ficam todas na mesma máquina e caem juntas com ela.
Constraints e preferências escolhem o nó
As constraints limitam os nós que podem receber as tarefas de um serviço. Cada constraint é uma comparação de igualdade ou diferença com um atributo do nó. Todas as constraints de um serviço precisam ser atendidas ao mesmo tempo. Num arquivo de stack, elas ficam em deploy.placement.constraints. A referência do docker service create lista os atributos que elas comparam, como estes:
node.role==workerMantém as tarefas fora dos managers, que ficam livres para o Raft.node.hostname==worker-1Prende o serviço a uma máquina, como a que guarda o volume do banco.node.labels.zone==spUsa um rótulo que você grava no nó com docker node update --label-add.node.platform.arch==x86_64Limita o serviço aos nós com a arquitetura da imagem.
As preferências de posicionamento distribuem as tarefas sem limitar os nós. A estratégia spread, a única disponível, tenta repartir as tarefas por igual entre os valores de um rótulo, como node.labels.zone. Quando nenhum nó tem o rótulo da preferência, o serviço sobe como se ela não existisse, enquanto uma constraint sem nó compatível deixa a tarefa pendente.
Quando a tarefa fica pendente
Um serviço fica no estado pending quando nenhum nó do cluster consegue receber as tarefas dele. A documentação dá três exemplos: todos os nós estão pausados ou em Drain, nenhum nó tem a memória reservada pelo serviço, ou as constraints não encontram nó compatível. Nos três, a tarefa espera até um nó apto aparecer. A documentação avisa que, com todos os nós em Drain, o primeiro nó que volta recebe todas as tarefas de uma vez.
A reserva de recursos, em deploy.resources.reservations, tem um efeito na recuperação de falhas. Com a reserva, o scheduler só coloca a tarefa num nó com aquela memória ou CPU livre. Se os nós restantes não têm memória livre para as tarefas do nó que caiu, essas tarefas ficam pendentes até sobrar espaço.
Sem reequilíbrio automático
O Swarm não move tarefas para um nó que volta ao cluster depois de uma queda, nem para um worker que acabou de entrar. Segundo a documentação, a escolha preserva as conexões dos clientes com as tarefas que já rodam, porque mover uma tarefa significa derrubar o container dela e criar outro. As tarefas novas e as recriadas vão para os nós menos ocupados, por isso o equilíbrio aparece com o tempo.
Para redistribuir na hora, você força a atualização do serviço com docker service update --force, que recria as tarefas seguindo a política de atualização do serviço. A página Atualizações e rollback explica essa política.
O próximo passo é entender como as tarefas de nós diferentes conversam entre si e como o tráfego externo chega até elas, na página Redes overlay e routing mesh.