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
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:
Para a antiga
order: stop-firstO Swarm para a tarefa antiga do grupo, que é o padrão.
Sobe a nova
parallelism: 1Cria a tarefa com a declaração nova no lugar dela.
Monitora
monitorObserva se a tarefa nova fica em execução no período definido.
Espera
delay: 10sAguarda o intervalo antes de trocar o próximo grupo.
Próximo grupo
RUNNINGRepete o ciclo até todas as tarefas estarem na versão nova.
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:
pause, continue ou rollback.failure_action.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.