kubectl rollout: como gerenciar, reverter e reiniciar Deployments

kubectl rollout é o comando que você usa para controlar e inspecionar como o Kubernetes aplica mudanças em um workload. Quando você altera um Deployment, o Kubernetes substitui os pods antigos por novos, e o kubectl rollout é a forma de acompanhar esse processo, pausá-lo, revertê-lo, reiniciá-lo e consultar seu histórico.

Neste guia, você vai aprender como o Kubernetes realmente executa um rollout por baixo dos panos, todos os subcomandos do kubectl rollout com exemplos, por que rollouts travam e como diagnosticá-los, além das práticas que tornam os rollouts seguros em produção.

kubectl rollout undo

kubectl rollout undo reverte um workload. Sem argumentos, ele volta para a revisão anterior e, com --to-revision, vai para uma revisão específica do histórico:

kubectl rollout undo deployment/api
kubectl rollout undo deployment/api --to-revision=2

Isso funciona porque o Kubernetes ainda tem o ReplicaSet antigo e simplesmente o escala novamente. Um rollback é, em si, um rollout, então execute rollout status na sequência para confirmar que ele terminou.

Uma limitação importante é que o undo restaura apenas o template de pod. Isso inclui a imagem do contêiner, as variáveis de ambiente e as configurações de recursos. Ele não desfaz mudanças feitas fora do template de pod. Por exemplo, se o release também alterou um ConfigMap, Secret, schema de banco de dados ou sistema externo, reverter o Deployment não desfaz essas mudanças.

Por isso, trate o rollout undo como uma ferramenta de recuperação rápida, não como sua estratégia habitual de deploy. Ele pode restaurar rapidamente uma versão anterior dos pods, mas não consegue reverter tudo o que pode ter mudado durante um release.

kubectl rollout restart

kubectl rollout restart reinicia todos os pods de um workload sem mudar a imagem:

kubectl rollout restart deployment/api

O comando adiciona ao template de pod uma annotation kubectl.kubernetes.io/restartedAt com o timestamp atual; como isso altera o template de pod, o Kubernetes trata a operação como um rollout normal. Ele cria um novo ReplicaSet e substitui os pods antigos gradualmente, seguindo maxSurge, maxUnavailable e os readiness probes. Com probes configurados corretamente, isso permite que a aplicação reinicie sem downtime.

Um caso de uso comum é aplicar mudanças que não reiniciam os pods automaticamente. Por exemplo, quando você atualiza um ConfigMap ou Secret que a aplicação lê apenas na inicialização, os pods existentes continuam usando os valores antigos. Um rollout restart substitui esses pods para que eles iniciem com os novos valores.

Um rollout restart é mais controlado do que excluir pods manualmente ou escalar um Deployment para zero. Excluir pods manualmente faz com que sejam substituídos, mas sem o mesmo processo controlado de rollout, e escalar para zero interrompe todos os pods antes de iniciar os novos, o que causa downtime. Um rollout restart substitui os pods gradualmente, respeitando as configurações de rollout do Deployment.

kubectl rollout pause e resume

kubectl rollout pause impede que um Deployment reaja a mudanças, e kubectl rollout resume permite que ele continue:

kubectl rollout pause deployment/api
kubectl rollout resume deployment/api

Há duas situações em que isso é útil. A primeira é agrupar várias mudanças em um único rollout. Se você pausar primeiro, depois alterar a imagem, os recursos e as variáveis de ambiente, e então retomar, o Kubernetes realiza um único rollout com todas as mudanças, em vez de um rollout separado para cada edição:

kubectl rollout pause deployment/api
kubectl set image deployment/api api=api:1.5.0
kubectl set resources deployment/api -c=api --limits=cpu=500m,memory=512Mi
kubectl rollout resume deployment/api

A segunda é pausar no meio de um rollout para validar um canary parcial. Você inicia um rollout alterando a imagem, deixa alguns pods novos subirem e então pausa. Nesse momento, uma pequena parcela do tráfego está na versão nova enquanto o restante permanece na antiga, e você pode observar as métricas e os logs dela. Se tudo parecer saudável, retome para concluir o rollout; se não, use undo para reverter. Lembre-se de que não é possível reverter um Deployment pausado, então retome-o antes de executar undo.

Por que rollouts travam e como diagnosticá-los?

Um rollout trava quando os novos pods não conseguem ficar disponíveis, e o Deployment acaba reportando ProgressDeadlineExceeded. Estas são as causas mais comuns:

a. Falta de capacidade no cluster para os pods de surge: um rolling update cria pods extras (maxSurge) antes de remover os antigos, então o rollout precisa de CPU e memória de sobra para agendá-los. Se o cluster não tiver espaço, os pods de surge ficam em Pending e o rollout não consegue avançar. Verifique o pod pendente com kubectl get pods e kubectl describe pod e veja se o Cluster Autoscaler consegue adicionar um nó.

b. Falhas de readiness probe e CrashLoopBackOff: se os novos pods iniciam, mas nunca passam no readiness probe, ou sofrem crash e reiniciam em loop, eles nunca contam como disponíveis e o rollout fica parado. Leia os logs do pod novo com kubectl logs e seus eventos com kubectl describe pod. É aqui que um probe mal configurado ou uma imagem nova com problema aparecem.

c. OOMKills por requests e limits de memória subdimensionados: se a nova versão precisa de mais memória do que o limite permite, o kernel mata cada pod novo assim que ele inicia, então o pod aparece como OOMKilled com código de saída 137 e o rollout nunca é concluído. Os logs do próprio pod geralmente estão vazios, porque o contêiner foi encerrado à força em vez de sofrer crash, então o sinal está em kubectl describe pod, no último estado.

d. PodDisruptionBudgets não bloqueiam o rollout em si: um PodDisruptionBudget não restringe o rolling update de um Deployment. PDBs não limitam rolling updates de workloads porque o rollout substitui os pods diretamente, e não por meio da API de eviction. O que um PDB restringe são evictions voluntárias: drains de nós, scale-down do Cluster Autoscaler e situações semelhantes. Assim, um PDB pode bloquear um drain de nó que esteja acontecendo ao mesmo tempo que o seu rollout, e um PDB mal configurado (por exemplo, minAvailable igual ao número de réplicas) pode bloquear drains completamente, mas não é ele que está segurando o rollout em si.

e. Conflitos entre Horizontal Pod Autoscaler e réplicas: se um HPA gerencia as réplicas de um Deployment e você também fixa replicas no manifesto, cada kubectl apply redefine a contagem para o valor do manifesto até o HPA corrigi-la novamente. Isso pode causar um comportamento de escala confuso durante um rollout. A solução é deixar replicas fora do manifesto de qualquer Deployment gerenciado por um HPA.

A maioria desses problemas se resume ao dimensionamento de recursos. Pods de surge que não cabem no cluster e pods novos que sofrem OOMKilled apontam para configurações de recursos incorretas. É aí que o PerfectScale ajuda. Sua plataforma de governança de Kubernetes observa como seus workloads realmente usam CPU e memória e transforma isso em recomendações de right-sizing acionáveis e automatizadas, que você pode aplicar manualmente ou de forma autônoma. Com requests e limits que refletem a realidade, seus pods de surge cabem no cluster e seus pods novos têm a memória de que precisam, então os rollouts terminam sem travar. Equipes como Paramount Pictures e Creditas usam o PerfectScale para manter seus clusters eficientes, e você pode criar sua conta ou agendar uma sessão técnica.

Boas práticas para executar o kubectl rollout em produção

Aqui vão algumas práticas simples para manter os rollouts em produção seguros e tranquilos:

a. Faça right-sizing de requests e limits antes do rollout: defina resource requests e limits precisos antes de iniciar um rollout. Isso dá aos pods de surge espaço suficiente para serem agendados e reduz o risco de novos pods sofrerem OOMKilled.

b. Verifique métricas e logs, não apenas o rollout status: um rollout status bem-sucedido significa apenas que os novos pods ficaram prontos. Não significa que a aplicação está funcionando corretamente. Verifique taxas de erro, latência e logs depois de um rollout, especialmente ao usar um canary pausado.

c. Defina progressDeadlineSeconds e --timeout explicitamente: defina um progressDeadlineSeconds razoável para que o Kubernetes marque um Deployment travado como falho. Use --timeout com o rollout status para que seu pipeline pare de esperar após um período definido.

d. Adicione uma annotation de change-cause a cada mudança: defina kubernetes.io/change-cause ao fazer mudanças, para que o rollout history mostre claramente o que mudou em cada revisão. Isso facilita escolher a revisão certa durante um rollback.

e. Mantenha o revisionHistoryLimit alto o suficiente para reverter com segurança: o padrão de 10 é adequado para a maioria dos workloads, mas, se você faz deploys com muita frequência, garanta que ele ainda cubra as revisões às quais você pode realmente precisar voltar.

f. Limite o raio de impacto fazendo o rollout de forma gradual: evite enviar uma mudança arriscada para todos os namespaces ou clusters de uma vez. Faça o rollout em etapas para detectar problemas cedo e parar antes que eles afetem tudo.

g. Migre de comandos manuais para GitOps e progressive delivery: o kubectl rollout é útil para aprender e gerenciar rollouts manualmente. Para ambientes de produção maiores, ferramentas como Argo CD ou Flux podem gerenciar deploys via GitOps, enquanto Argo Rollouts ou Flagger podem automatizar deploys canary e blue-green.