Ir para o conteúdo
Promovaweb

Atualizações em etapas e rollback

A atualização de um serviço no Docker Swarm é a troca das tarefas antigas por tarefas novas, feita em grupos conforme a política de atualização do serviço. Com o padrão de uma tarefa por vez, as outras réplicas continuam atendendo enquanto cada tarefa troca de versão, por isso um serviço com várias réplicas recebe a imagem nova sem sair do 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. O que dispara uma atualização
  2. A política de atualização
  3. Parar antes ou subir antes
  4. Rollback manual e automático
  5. Health check e atualização forçada

O que dispara uma atualização

Toda mudança na declaração de um serviço que afeta as tarefas gera uma atualização: uma imagem nova, outra variável de ambiente, um secret acrescentado, um limite de memória diferente. Você aplica a mudança com docker service update ou com um novo docker stack deploy do arquivo alterado. O manager compara a declaração nova com a anterior e troca as tarefas que precisam mudar.

A troca acontece em etapas porque o serviço tem várias réplicas. Com três réplicas e o paralelismo padrão de uma tarefa por vez, duas réplicas continuam no ar enquanto a terceira troca de versão. O fluxo de cada grupo segue esta ordem:

  1. Para a antiga

    order: stop-first

    O Swarm para a tarefa antiga do grupo, que é o padrão.

  2. Sobe a nova

    parallelism: 1

    Cria a tarefa com a declaração nova no lugar dela.

  3. Monitora

    monitor

    Observa se a tarefa nova fica em execução no período definido.

  4. Espera

    delay: 10s

    Aguarda o intervalo antes de trocar o próximo grupo.

  5. Próximo grupo

    RUNNING

    Repete o ciclo até todas as tarefas estarem na versão nova.

Com o paralelismo padrão, o Swarm troca uma tarefa por vez. A tarefa nova passa pelo período de monitoramento antes de o scheduler seguir para a próxima. Uma falha nesse período pausa a atualização.

Se uma tarefa nova retorna FAILED, o scheduler pausa a atualização por padrão. As réplicas que já trocaram ficam na versão nova, enquanto as outras seguem na antiga, por isso o serviço fica dividido entre as duas versões até você escolher o próximo passo.

A política de atualização

Num arquivo de stack, a política fica em deploy.update_config. As opções e os padrões abaixo vêm da referência do comando docker service create:

OpçãoPadrãoO que controla
parallelism1Quantas tarefas trocam ao mesmo tempo. Zero troca todas de uma vez.
delay0sA espera entre um grupo e o próximo.
failure_actionpauseO que fazer quando uma tarefa falha: pause, continue ou rollback.
monitor5sPor quanto tempo uma tarefa nova é observada depois de subir.
max_failure_ratio0A fração de tarefas que pode falhar sem acionar o failure_action.
orderstop-firstSe a tarefa antiga para antes da nova subir ou se as duas convivem por um momento.

O padrão do monitor aparece diferente em três páginas oficiais: 5 segundos na referência do docker service create, 30 segundos no guia de serviços e 0 segundo na especificação do deploy do Compose. Com o valor escrito no arquivo da stack, o período de monitoramento fica definido por você, de acordo com o tempo que o seu app leva para falhar quando sobe com erro.

O Swarm só considera a falha que acontece dentro do período de monitoramento. Uma tarefa que não sobe, ou que para antes do fim desse período, entra na fração de falhas da atualização. Uma tarefa que cai depois dele é uma queda comum, que o orquestrador resolve recriando a tarefa sem pausar nem reverter a atualização.

Parar antes ou subir antes

A ordem stop-first, que é o padrão, para a tarefa antiga e só então sobe a nova. Durante a troca, o serviço fica com uma réplica a menos. Num serviço com uma réplica só, essa troca deixa o app fora do ar pelo tempo que a tarefa nova leva para subir.

A ordem start-first sobe a tarefa nova primeiro, com as duas versões rodando juntas por um momento. O serviço não perde capacidade durante a troca, mas o nó precisa de memória e CPU para as duas tarefas ao mesmo tempo. Uma tarefa que publica porta em modo host também não convive com a antiga no mesmo nó, porque as duas disputam a mesma porta.

Rollback manual e automático

O comando docker service update --rollback leva o serviço de volta à configuração anterior ao último docker service update. O rollback roda no lado do servidor e segue a política própria de rollback, em deploy.rollback_config, com paralelismo padrão de uma tarefa, espera de 0 segundo, ação de falha pause e monitoramento de 5 segundos na referência da CLI.

O rollback automático usa failure_action: rollback na política de atualização. Quando a fração de tarefas com falha passa do max_failure_ratio, o Swarm para de trocar tarefas e reverte o serviço para a declaração anterior sem você entrar no servidor. Com essa combinação, uma imagem defeituosa deixa o serviço dividido entre duas versões só pelo tempo de reverter as tarefas já trocadas.

Health check e atualização forçada

O monitoramento fica mais preciso quando a imagem tem um health check. A tarefa cujo container falha no health check termina, o que faz a falha aparecer dentro do período de monitoramento. Sem health check, o Swarm só percebe a falha quando o processo do container termina. Um app que sobe mas não responde passa como tarefa saudável.

O comando docker service update --force recria as tarefas mesmo sem mudança na declaração, respeitando a política de atualização. Com ele, você redistribui as tarefas pelos nós, como mostra a página Serviços, réplicas e posicionamento, ou reinicia um serviço em etapas.

O próximo passo é ver o que o cluster faz quando a falha vem de uma máquina inteira, na página Failover e recuperação.

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.