Marcio Cunha

Pods travados no Terminating? Como forçar a remoção no Kubernetes

Seus pods estão presos no status Terminating? Entenda por que isso acontece e como usar flags de bypass para limpar o cluster definitivamente.

Marcio Cunha•2 min
Também disponível em:EnglishEspañol
Resumo
  • Pods travados no estado Terminating geralmente ocorrem por finalizadores pendentes de controladores externos.
  • A API do Kubernetes bloqueia a exclusão do objeto até que todos os seus finalizadores sejam processados.
  • O uso da flag --force permite ignorar a espera pelo processamento dos finalizadores pendentes.
  • Identificar a causa raiz no nível do namespace ou dos CRDs evita reincidências no cluster.
  • Remover pods à força deve ser a última alternativa após garantir que o processo no nó não está em I/O crítico.

Por que os pods ficam travados no estado Terminating?

Quem trabalha com Kubernetes certamente já passou pela frustração de deletar um pod e vê-lo permanecer no estado Terminating indefinidamente. Na prática, isso acontece porque o Kubernetes possui um mecanismo de segurança chamado finalizadores (finalizers). Eles são chaves que impedem que um recurso seja removido antes que certas tarefas de limpeza sejam concluídas, como o desmonte de um volume de rede ou a remoção de registros em um serviço de banco de dados.

Quando um controlador externo falha ao limpar esses recursos, o pod fica esperando eternamente por um sinal que nunca virá. É o equivalente a ter um processo travado no Windows aguardando uma resposta de um drive de rede desconectado. Se você já tentou comandos comuns sem sucesso, saiba que essa é uma trava de proteção, e não apenas um erro aleatório do cluster.

O papel dos finalizadores no ciclo de vida dos containers

Os finalizadores são partes essenciais da integridade de sistemas distribuídos. Eles garantem que, ao deletar uma aplicação, todos os recursos dependentes sejam devidamente liberados, evitando "lixo" ou corrupção de dados. Contudo, em cenários de alta complexidade, um CRD (Custom Resource Definition) ou um agente de rede mal configurado pode manter esse bloqueio ativo.

Antes de forçar a remoção, é vital investigar o que está segurando o recurso. Muitas vezes, um pod travado é apenas o sintoma de uma falha de comunicação entre o plano de controle do Kubernetes e os nós, algo similar ao que discutimos em nosso guia sobre como debugar o CNI no Kubernetes. Se o nó não responde, o kubelet não consegue confirmar a finalização.

Como forçar a remoção de um pod via kubectl

Quando a intervenção manual é inevitável, o Kubernetes oferece uma forma de bypass. O comando a seguir força a remoção imediata, ignorando o tempo de espera padrão e a verificação dos finalizadores pendentes. Lembre-se de substituir os nomes conforme o seu ambiente atual:

kubectl delete pod <nome-do-pod> --namespace <nome-do-namespace> --force --grace-period=0

A flag --force em conjunto com --grace-period=0 instrui o cluster a remover o objeto da memória do etcd imediatamente, sem aguardar o processo de encerramento normal. É uma medida drástica que deve ser usada com cautela, pois você está pulando o protocolo de segurança definido pelos controladores. Para complementar essa implementação em produção, vale conferir também nossas análises técnicas sobre NGINX lento? Como monitorar conexões com o stub_status e Pipeline do GitLab CI travado? Como cancelar jobs presos.

Limpando os finalizadores manualmente via patch

Se a remoção forçada não funcionar, a alternativa é editar o recurso para remover os finalizadores manualmente. Isso pode ser feito através de um comando patch na API, que remove a lista de finalizadores do objeto, liberando o Kubernetes para deletá-lo instantaneamente:

kubectl patch pod <nome-do-pod> -p '{