Ir para o conteúdo
Promovaweb

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
  1. Serviço, tarefa e container
  2. Réplicas e serviços globais
  3. Constraints e preferências escolhem o nó
  4. Quando a tarefa fica pendente
  5. Sem reequilíbrio automático

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:

  1. Serviço

    deploy.replicas: 3

    A declaração que o manager guarda como estado desejado.

  2. Orquestrador

    web.1 web.2 web.3

    Cria uma tarefa para cada réplica que falta.

  3. Scheduler

    node.role==worker

    Escolhe um nó que atenda às constraints e aos recursos.

  4. Worker

    RUNNING

    Baixa a imagem e roda o container da tarefa.

O manager aceita a declaração do serviço, cria as tarefas e escolhe um nó para cada uma. O worker só executa o container da tarefa que recebeu.

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 scale muda 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.

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.