Comportamento Esperado e o Erro CrashLoopBackOff

Ao implantar uma aplicação no Kubernetes (K8s), o comportamento esperado é que o Pod mude de Pending diretamente para Running, e os contêineres permaneçam ativos. No entanto, um dos erros mais comuns e notórios a enfrentar é o CrashLoopBackOff.

Esse status significa que um contêiner dentro do Pod está iniciando, falhando instantaneamente e o Kubernetes está continuamente tentando reiniciá-lo - com atrasos crescentes (backoffs) entre cada tentativa (10s, 20s, 40s, até 5 minutos).

Diferentemente de um estado Pending (que implica em problemas de infraestrutura), um CrashLoopBackOff diz explicitamente que a infraestrutura programou o Pod, baixou a imagem e executou o contêiner, mas a aplicação fechou voluntariamente ou o kernel forçou sua parada.

Pré-requisitos

Antes de mergulhar na Solução de Problemas, certifique-se de ter:

  • Um Cluster Kubernetes em funcionamento (Minikube, EKS, GKE, AKS).
  • A ferramenta de linha de comando kubectl instalada e configurada para apontar para o seu cluster.
  • O nome exato do Pod que exibe o erro e seu respectivo namespace.

Causa do Problema

Como o CrashLoopBackOff é apenas um sintoma, precisamos procurar o motivo. Os culpados mais frequentes incluem:

  1. Erro Fatal do Aplicativo: O código encontra uma exceção não contornável ou uma dependência não encontrada (como não conseguir se conectar a um banco de dados).
  2. Configurações e Secrets Ausentes: O aplicativo espera uma variável de ambiente mapeada a partir de um ConfigMap inexistente ou digitado incorretamente.
  3. Falhas na Liveness Probe: A sua livenessProbe falha vezes suficientes, obrigando o Kubernetes a classificar o processo como doente e tentar eliminá-lo continuadamente.
  4. OOMKilled: O contêiner requisita mais espaço na RAM do que a definição em limits.memory permite, então o Linux mata o programa à força.
  5. Entrypoint Inválido: O comando do YAML ou o CMD/ENTRYPOINT do seu Dockerfile contém erros ou não está projetado para rodar indefinidamente no primeiro plano da execução.

Solução Passo a Passo

1. Visualizar a Descrição do Pod

O primeiro comando para solucionar esse problema é o describe. Ele lhe fornecerá o Exit Code exato.

kubectl describe pod <pod-name> -n <namespace>

Desça até a seção Containers e veja o bloco Last State:

    Last State:     Terminated
      Reason:       Error
      Exit Code:    1
      Started:      Fri, 27 Feb 2026 10:00:00 GMT
      Finished:     Fri, 27 Feb 2026 10:00:02 GMT

Códigos de Saída Comuns:

  • Exit Code 1: Erro geral do programa (veja os logs).
  • Exit Code 2: Mau uso dos comandos interativos via Shell script.
  • Exit Code 126: Comando existente, porém sem privilégio de acesso ou execução.
  • Exit Code 128: Argumento de código de fechamento falho.
  • Exit Code 137: OOMKilled (Out of Memory - limite da carga estourado).
  • Exit Code 255: Pânico sem classificação na inicialização.

2. Checar os Logs Anteriores

Como a instância segue iniciando e desabando, simplesmente chamar kubectl logs às vezes parece nulo se ele for disparado junto ao re-início da cápsula. Use a tag --previous para forçar o coletor a exibir os últimos textos capturados da cópia morta do pod:

kubectl logs <pod-name> -n <namespace> --previous

Essa ação revela onde ocorreu o colapso fatal da aplicação.

3. Verificar OOMKilled

Se o código exposto pelo terminal foi 137 ou OOMKilled, a ação corretiva direta é fornecer mais teto de uso ao elemento virtual de seu Kubernetes.

Altere o arquivo YAML a seguir para aumentar a RAM:

resources:
  requests:
    memory: "256Mi"
    cpu: "250m"
  limits:
    memory: "512Mi"  # <-- Eleve este valor
    cpu: "500m"

Em seguida, re-aplique pelo comando kubectl apply -f deployment.yaml.

4. Solução Alternativa e Depuração

Se nada surtir efeito devido à problemas confusos em diretórios ou escassez de detalhes nos logs, trave a sua imagem de ser expulsa mudando sua definição central.

Mude seu manifesto de Deployment momentaneamente:

containers:
  - name: my-crashing-app
    image: my-registry/my-app:v1
    command: ["sleep", "3600"] # Força que ele sobreviva 1 hr

Submeta a atualização da estrutura. Assim que seu Pod indicar que passou a estar eternamente no status Running, chame uma ponte interativa ao seu interior:

kubectl exec -it <pod-name> -- /bin/sh

Desse modo, estando na linha interna, proceda em tentar chamar a sua função inicial através de algo como npm start, testando de primeira-mão a ocorrência que estava colapsando sua criação anteriormente durante o lançamento normal.

Prevenção

Para encolher a recorrência desta frustração operacional dentro de ambientes em atividade real (Production Stage), garanta estas políticas:

  • Prazos Estendidos nas Probes: Avalie configurar tempo ocioso maior na checagem livenessProbe permitindo tempo de boot inicial aceitável.
  • Contêineres Iniciais (InitContainers): Vincule componentes bloqueantes num modelo que prepare as respostas assíncronas aguardando a existência e atividade robusta antes da sua infraestrutura maior despertar.
  • Revalidação das Secret Keys: Insista num esteira de envio de código via CI/CD que obrigue um ateste de que sua API/Secret referenciada internamente nas instâncias efetivamente obvia existam antes que ele propague a aplicação em um lugar inválido.

Resumo

  • CrashLoopBackOff aponta que um ciclo repetitivo colidiu imediatamente seu processo.
  • Empregue kubectl describe pod mirando encontrar o dado essencial do Exit Code.
  • Aproveite kubectl logs --previous a fim de identificar vazamentos e ranhuras vitais do encerramento forçoso anterior.
  • Código 137 é puramente atrelado à contenção violenta de Limites OOM.
  • Bloqueie a morte natural subsituindo com as ordens nativas para a dormência de Shell durante depuração cirúrgica intensa de arquivos.

Artigos Relacionados