Resolver problemas de eventos CrashLoopBackOff

Esta página ajuda a resolver problemas com pods que estão passando por eventos CrashLoopBackOff no Google Kubernetes Engine (GKE).

Esta página é destinada a desenvolvedores de aplicativos que querem identificar problemas no nível do app, como erros de configuração ou bugs relacionados ao código, que causam falhas nos contêineres. Também é para administradores e operadores de plataforma que precisam identificar causas raiz no nível da plataforma para reinicializações de contêineres, como esgotamento de recursos, interrupções de nós ou sondagens de atividade configuradas incorretamente. Para mais informações sobre papéis comuns e tarefas de exemplo referenciados no conteúdo do Trusted Cloud by S3NS , consulte Funções e tarefas de usuário comuns do GKE.

Entender um evento CrashLoopBackOff

Quando o pod fica preso no estado CrashLoopBackOff, um contêiner dentro dele é iniciado e falha ou sai repetidamente. Esse CrashLoop aciona o Kubernetes para tentar reiniciar o contêiner seguindo o restartPolicy. A cada reinicialização com falha, o atraso de BackOff antes da próxima tentativa aumenta exponencialmente (por exemplo, 10s, 20s, 40s) até um máximo de cinco minutos.

Embora esse evento indique um problema no seu contêiner, ele também é um sinal de diagnóstico valioso. Um evento CrashLoopBackOff confirma que muitas etapas fundamentais da criação de pods, como atribuição a um nó e extração da imagem do contêiner, já foram concluídas. Assim, você pode concentrar sua investigação no app ou na configuração do contêiner, em vez da infraestrutura do cluster.

O estado CrashLoopBackOff ocorre devido à forma como o Kubernetes, especificamente o kubelet, processa o encerramento do contêiner com base na política de reinicialização do pod. O ciclo geralmente segue este padrão:

1. O contêiner é iniciado.
2. O contêiner sai.
3. O kubelet observa o contêiner interrompido e o reinicia de acordo com o restartPolicy do pod.
4. Esse ciclo se repete, com o contêiner reiniciado após um atraso de espera exponencial crescente.

O restartPolicy do pod é a chave para esse comportamento. A política padrão, Always, é a causa mais comum desse loop porque reinicia um contêiner se ele for encerrado por qualquer motivo, mesmo após uma saída bem-sucedida. A política OnFailure tem menos probabilidade de causar um loop porque só reinicia em códigos de saída diferentes de zero, e a política Never evita uma reinicialização por completo.

Identificar sintomas de um evento CrashLoopBackOff

Um pod com o status CrashLoopBackOff é a principal indicação de um evento CrashLoopBackOff.

No entanto, você pode sentir alguns sintomas menos óbvios de um evento de CrashLoopBackOff:

• Zero réplicas íntegras para uma carga de trabalho.
• Uma diminuição acentuada nas réplicas íntegras.
• As cargas de trabalho com o escalonamento automático horizontal de pods ativado estão sendo escalonadas lentamente ou não estão sendo escalonadas.

Se uma carga de trabalho system (por exemplo, um agente de registros ou métricas) tiver o status CrashLoopBackOff, você também poderá notar os seguintes sintomas:

• Algumas métricas do GKE não são informadas.
• Alguns painéis e gráficos do GKE têm lacunas.
• Problemas de conectividade na rede no nível do pod.

Se você observar algum desses sintomas menos óbvios, a próxima etapa será confirmar se um evento CrashLoopBackOff ocorreu.

Confirmar um evento CrashLoopBackOff

Para confirmar e investigar um evento CrashLoopBackOff, colete evidências de eventos do Kubernetes e dos registros de apps do contêiner. Essas duas fontes oferecem visões diferentes, mas complementares, do problema:

• Os eventos do Kubernetes confirmam que um pod está falhando.
• Os registros de apps do contêiner podem mostrar por que o processo dentro dele está falhando.

Para conferir essas informações, selecione uma das seguintes opções:

Usar o playbook interativo de pods com loop de falhas

Depois de confirmar um evento CrashLoopBackOff, comece a resolver problemas com o manual interativo:

1. No console Trusted Cloud , acesse a página Manual interativo do GKE: pods com loop de falhas.

   Acessar "Pods com loop de falhas"

2. Na lista Cluster, selecione o cluster que você quer resolver problemas. Se não encontrar o cluster, digite o nome dele no campo Filtro.

3. Na lista Namespace, selecione o namespace que você quer resolver. Se você não encontrar seu namespace, digite-o no campo Filtro.

4. Siga cada seção para responder às seguintes perguntas:

   1. Identificar erros de app: quais contêineres estão reiniciando?
   2. Investigue problemas de falta de memória: há um erro de configuração ou relacionado ao app?
   3. Investigue as interrupções de nós: o contêiner está sendo reinicializado por conta de interrupções no recurso de nó?
   4. Investigar falhas de sondagem de atividade: as sondagens de atividade estão interrompendo seus contêineres?
   5. Correlacionar eventos de mudança: o que aconteceu quando os contêineres começaram a falhar?

5. Opcional: para receber notificações sobre futuros eventos do CrashLoopBackOff, na seção Dicas de mitigação futura, selecione Criar um alerta.

Se o problema persistir depois de usar o playbook, leia o restante do guia para mais informações sobre como resolver eventos CrashLoopBackOff.

Resolver um evento de CrashLoopBackOff

As seções a seguir ajudam você a resolver as causas mais comuns de eventos CrashLoopBackOff:

• Exaustão de recursos (OOMKilled)
• Falha na sondagem de atividade
• App com configuração incorreta

Resolver o esgotamento de recursos

Um evento CrashLoopBackOff geralmente é causado por um problema de falta de memória (OOM). Para confirmar se essa é a causa, verifique se a saída de kubectl describe mostra o seguinte:

Last State: Terminated
  Reason: OOMKilled

Para saber como diagnosticar e resolver eventos de falta de memória, consulte Resolver problemas de falta de memória.

Resolver falhas de sondagem de atividade

Uma sondagem de atividade é uma verificação de integridade periódica realizada pelo kubelet. Se a sondagem falhar um número especificado de vezes (o número padrão é três), o kubelet vai reiniciar o contêiner, o que pode causar um evento CrashLoopBackOff se as falhas continuarem.

Confirmar se uma sondagem de atividade é a causa

Para confirmar se as falhas de sondagem de atividade estão acionando o evento CrashLoopBackOff, consulte os registros kubelet. Esses registros geralmente contêm mensagens explícitas indicando falhas de sondagem e reinicializações subsequentes.

1. No console do Trusted Cloud , acesse a página Análise de registros.

   Acessar o Explorador de registros

2. No painel de consulta, filtre reinicializações relacionadas a sondagens de atividade inserindo a seguinte consulta:

   resource.type="k8s_node"
   log_id("kubelet")
   jsonPayload.MESSAGE:"failed liveness probe, will be restarted"
   resource.labels.cluster_name="CLUSTER_NAME"
   

   Substitua CLUSTER_NAME pelo nome do cluster.

3. Verifique a saída. Se uma falha na sondagem de atividade for a causa dos eventos CrashLoopBackOff, a consulta vai retornar mensagens de registro semelhantes a estas:

   Container probe failed liveness probe, will be restarted
   

Depois de confirmar que as sondagens de atividade são a causa do evento CrashLoopBackOff, resolva as causas comuns:

• Analise a configuração da sondagem de atividade.
• Inspecione a utilização da CPU e da E/S do disco.
• Abordar implantações grandes.
• Corrija erros temporários.
• Resolver o consumo de recursos de sondagem de endereço.

Analisar a configuração da sondagem de atividade

Sondas mal configuradas são uma causa frequente de eventos CrashLoopBackOff. Verifique as seguintes configurações no manifesto da sondagem:

• Verifique o tipo de sondagem: a configuração da sondagem precisa corresponder à forma como o app informa a integridade. Por exemplo, se o app tiver um URL de verificação de integridade (como /healthz), use o tipo de sondagem httpGet. Se a integridade for determinada pela execução de um comando, use o tipo de sondagem exec. Por exemplo, para verificar se uma porta de rede está aberta e escutando, use o tipo de sondagem tcpSocket.
• Verificar parâmetros de sondagem:
  • Caminho (para o tipo de sondagem httpGet): verifique se o caminho HTTP está correto e se o app faz verificações de integridade nele.
  • Porta: verifique se a porta configurada na sondagem é usada e exposta pelo app.
  • Comando (para o tipo de sondagem exec): verifique se o comando existe no contêiner, retorna um código de saída 0 em caso de sucesso e é concluído no período timeoutSeconds configurado.
  • Tempo limite: verifique se o valor timeoutSeconds é suficiente para o app responder, principalmente durante a inicialização ou sob carga.
  • Atraso inicial (initialDelaySeconds): verifique se o atraso inicial é suficiente para que o app seja iniciado antes do início das sondagens.

Para mais informações, consulte Configurar sondagens de atividade, prontidão e inicialização na documentação do Kubernetes.

Inspecionar a utilização da CPU e da E/S do disco

A disputa de recursos resulta em tempos limite de sondagem, que é uma das principais causas de falhas de sondagem de atividade. Para saber se o uso de recursos é a causa da falha da sondagem de atividade, tente as seguintes soluções:

• Analise o uso da CPU: monitore o uso da CPU do contêiner afetado e do nó em que ele está sendo executado durante os intervalos de sondagem. Uma métrica importante para acompanhar é kubernetes.io/container/cpu/core_usage_time. O uso alto da CPU no contêiner ou no nó pode impedir que o app responda à sondagem a tempo.
• Monitorar E/S de disco: verifique as métricas de E/S de disco do nó. Use a métrica compute.googleapis.com/guest/disk/operation_time para avaliar o tempo gasto nas operações de disco, que são categorizadas por leituras e gravações. Uma E/S de disco alta pode diminuir significativamente a inicialização do contêiner, a inicialização do app ou o desempenho geral do app, causando tempos limite de sondagem.

Abordar implantações grandes

Em cenários em que um grande número de pods é implantado simultaneamente (por exemplo, por uma ferramenta de CI/CD como o ArgoCD), um aumento repentino de novos pods pode sobrecarregar os recursos do cluster, levando ao esgotamento dos recursos do plano de controle. Essa falta de recursos atrasa a inicialização do app e pode fazer com que as sondagens de atividade falhem repetidamente antes que os apps estejam prontos.

Para resolver esse problema, tente o seguinte:

• Implemente implantações escalonadas: implemente estratégias para implantar pods em lotes ou por um período mais longo para evitar sobrecarregar os recursos do nó.
• Reconfigure ou escalone nós: se implantações escalonadas não forem viáveis, considere fazer upgrade de nós com discos mais rápidos ou maiores ou reivindicações de volume permanente para lidar melhor com o aumento da demanda de E/S. Verifique se o escalonamento automático do cluster está configurado corretamente.
• Aguarde e observe: em alguns casos, se o cluster não estiver com poucos recursos, as cargas de trabalho poderão ser implantadas após um atraso significativo (às vezes, 30 minutos ou mais).

Corrigir erros temporários

O app pode apresentar erros temporários ou lentidão durante a inicialização ou inicialização, o que faz com que a sondagem falhe inicialmente. Se o app se recuperar, considere aumentar os valores definidos nos campos initialDelaySeconds ou failureThreshold no manifesto da sua sondagem de atividade.

Como lidar com o consumo de recursos de sondagem de endereço

Em casos raros, a execução da sondagem de atividade pode consumir recursos significativos, o que pode acionar restrições de recursos que podem levar ao encerramento do contêiner devido a uma ação de OOM. Verifique se os comandos de sondagem são leves. Uma sondagem leve tem mais chances de ser executada com rapidez e confiabilidade, o que aumenta a fidelidade na geração de relatórios precisos sobre a integridade real do app.

Resolver erros de configuração de apps

Configurações incorretas de apps causam muitos eventos CrashLoopBackOff. Para entender por que o app está parando, a primeira etapa é examinar o código de saída. Esse código determina o caminho da solução de problemas:

• O código de saída 0 indica uma saída bem-sucedida, o que é inesperado para um serviço de longa duração e aponta para problemas com o ponto de entrada do contêiner ou design do app.
• Um código de saída diferente de zero indica uma falha no app, direcionando o foco para erros de configuração, problemas de dependência ou bugs no código.

Encontrar o código de saída

Para encontrar o código de saída do app, faça o seguinte:

1. Descreva o pod:

   kubectl describe pod POD_NAME -n NAMESPACE_NAME
   

   Substitua:

   • POD_NAME: o nome do pod com problemas.
   • NAMESPACE_NAME: o namespace do pod.

2. Na saída, revise o campo Exit Code localizado na seção Last State do contêiner relevante. Se o código de saída for 0, consulte Solução de problemas de saídas bem-sucedidas (código de saída 0). Se o código de saída for um número diferente de 0, consulte Resolver problemas de falhas de apps (código de saída diferente de zero).

Resolver problemas de saídas bem-sucedidas (código de saída 0)

Um código de saída 0 geralmente significa que o processo do contêiner foi concluído com sucesso. Embora esse seja o resultado desejado para um job baseado em tarefas, ele pode indicar um problema para um controlador de longa duração, como um Deployment, StatefulSet ou ReplicaSet.

Esses controladores trabalham para garantir que um pod esteja sempre em execução, então eles tratam qualquer saída como uma falha a ser corrigida. O kubelet impõe esse comportamento aderindo ao restartPolicy do pod (que tem como padrão Always), reiniciando o contêiner mesmo após uma saída bem-sucedida. Essa ação cria um loop que aciona o status CrashLoopBackOff.

Os motivos mais comuns para saídas bem-sucedidas inesperadas são:

• O comando do contêiner não inicia um processo persistente: um contêiner permanece em execução apenas enquanto o processo inicial (command ou entrypoint) estiver em execução. Se esse processo não for um serviço de longa duração, o contêiner será encerrado assim que o comando for concluído. Por exemplo, um comando como ["/bin/bash"] é encerrado imediatamente porque não tem um script para executar. Para resolver esse problema, verifique se o processo inicial do contêiner inicia um processo que é executado continuamente.

• O app worker sai quando uma fila de trabalho está vazia: muitos apps worker são projetados para verificar uma fila em busca de uma tarefa e sair corretamente se ela estiver vazia. Para resolver isso, use um controlador de job (projetado para tarefas que são executadas até a conclusão) ou modifique a lógica do app para ser executado como um serviço persistente.

• Saídas do app devido a configuração ausente ou inválida: o app pode sair imediatamente se não tiver instruções de inicialização necessárias, como argumentos de linha de comando, variáveis de ambiente ou um arquivo de configuração crítico.

  Para resolver esse problema, primeiro inspecione os registros do app em busca de mensagens de erro específicas relacionadas ao carregamento da configuração ou a parâmetros ausentes. Em seguida, verifique o seguinte:

  • Argumentos ou ambiente do app: verifique se todos os argumentos de linha de comando e variáveis de ambiente necessários estão sendo transmitidos corretamente para o contêiner, conforme esperado pelo app.
  • Presença do arquivo de configuração: confirme se todos os arquivos de configuração necessários estão nos caminhos esperados dentro do contêiner.
  • Conteúdo do arquivo de configuração: valide o conteúdo e o formato dos arquivos de configuração para erros de sintaxe, campos obrigatórios ausentes ou valores incorretos.

  Um exemplo comum desse problema é quando um app é configurado para ler de um arquivo ativado com um volume ConfigMap. Se o ConfigMap não estiver anexado, estiver vazio ou tiver chaves com nomes incorretos, um app projetado para sair quando a configuração estiver faltando poderá parar com um código de saída 0. Nesses casos, verifique as seguintes configurações: - O nome ConfigMap na definição de volume do pod corresponde ao nome real. - As chaves em ConfigMap correspondem ao que o app espera encontrar como nomes de arquivos no volume montado.

Resolver problemas de falhas de apps (código de saída diferente de zero)

Quando um contêiner é encerrado com um código diferente de zero, o Kubernetes o reinicia. Se o problema que causou o erro persistir, o app vai falhar de novo e o ciclo vai se repetir, culminando em um estado CrashLoopBackOff.

O código de saída diferente de zero é um sinal claro de que ocorreu um erro no próprio app, o que direciona seus esforços de depuração para o funcionamento interno e o ambiente dele. Os seguintes problemas costumam causar esse encerramento:

• Erros de configuração: um código de saída diferente de zero geralmente indica problemas com a configuração do app ou o ambiente em que ele está sendo executado. Verifique se o app tem estes problemas comuns:

  • Arquivo de configuração ausente: o app talvez não consiga localizar ou acessar um arquivo de configuração necessário.
  • Configuração inválida: o arquivo de configuração pode conter erros de sintaxe, valores incorretos ou configurações incompatíveis, causando falha no app.
  • Problemas de permissão: o app pode não ter as permissões necessárias para ler ou gravar o arquivo de configuração.
  • Variáveis de ambiente: variáveis de ambiente incorretas ou ausentes podem causar mau funcionamento ou falha na inicialização do app.
  • entrypoint ou command inválido: o comando especificado no campo entrypoint ou command do contêiner pode estar incorreto. Esse problema pode ocorrer com imagens recém-implantadas em que o caminho para o executável está incorreto ou o arquivo não está presente na imagem do contêiner. Essa configuração incorreta geralmente resulta no código de saída 128.

  • Atualizações de imagens não controladas (tag :latest): se as imagens da sua carga de trabalho usarem a tag :latest, novos pods poderão extrair uma versão atualizada da imagem que introduz mudanças incompatíveis.

    Para garantir consistência e reprodutibilidade, sempre use tags de imagem específicas e imutáveis (por exemplo, v1.2.3) ou resumos SHA (por exemplo, sha256:45b23dee08...) em ambientes de produção. Essa prática ajuda a garantir que o mesmo conteúdo de imagem seja extraído todas as vezes.

• Problemas de dependência: o app pode falhar se não conseguir se conectar aos outros serviços de que depende ou se não for autenticado ou tiver permissões insuficientes para acessá-los.

  • Serviço externo indisponível: o app pode depender de serviços externos (por exemplo, bancos de dados ou APIs) que não podem ser acessados devido a problemas de conectividade de rede ou interrupções de serviço. Para resolver esse problema, conecte-se ao pod. Para mais informações, consulte Depurar pods em execução na documentação do Kubernetes.

    Depois de se conectar ao pod, é possível executar comandos para verificar o acesso a arquivos, bancos de dados ou para testar a rede. Por exemplo, você pode usar uma ferramenta como curl para tentar acessar o URL de um serviço. Essa ação ajuda a determinar se um problema é causado por políticas de rede, DNS ou pelo próprio serviço.

  • Falhas de autenticação: o app pode não conseguir se autenticar com serviços externos devido a credenciais incorretas. Inspecione os registros do contêiner para mensagens como 401 Unauthorized (credenciais inválidas) ou 403 Forbidden (permissões insuficientes), que geralmente indicam que a conta de serviço do pod não tem os papéis do IAM necessários para fazer chamadas de serviço Trusted Cloud by S3NSexternas.

    Se você usa a federação de identidade da carga de trabalho do GKE, verifique se o identificador principal tem as permissões necessárias para a tarefa. Para mais informações sobre como conceder papéis do IAM a principais usando a Federação de identidade da carga de trabalho do GKE, consulte Configurar autorização e principais. Também é necessário verificar se o uso de recursos do servidor de metadados do GKE não excedeu os limites.

  • Tempos limite: o app pode sofrer tempos limite ao aguardar respostas de serviços externos, o que causa falhas.

• Erros específicos do app: se a configuração e as dependências externas parecem corretas, o erro pode estar no código do app. Inspecione os registros do app para encontrar estes erros internos comuns:

  • Exceções não processadas: os registros do app podem conter stack traces ou mensagens de erro que indicam exceções não processadas ou outros bugs relacionados ao código.
  • Deadlocks ou livelocks: o app pode estar preso em um deadlock, em que vários processos estão aguardando a conclusão uns dos outros. Nesse cenário, o app não sai, mas para de responder indefinidamente.
  • Conflitos de porta: o app pode não iniciar se tentar se vincular a uma porta que já está em uso por outro processo.
  • Bibliotecas incompatíveis: o app pode depender de bibliotecas ou dependências ausentes ou incompatíveis com o ambiente de execução.

  Para encontrar a causa raiz, inspecione os registros do contêiner em busca de uma mensagem de erro ou um stack trace específico. Essas informações ajudam você a decidir se é necessário corrigir o código do app, ajustar os limites de recursos ou corrigir a configuração do ambiente. Para mais informações sobre registros, consulte Sobre os registros do GKE.

A seguir

• Se você não encontrar uma solução para seu problema na documentação, consulte Receber suporte para mais ajuda, incluindo conselhos sobre os seguintes tópicos:

  • Abrir um caso de suporte entrando em contato com o Cloud Customer Care.
  • Receber suporte da comunidade fazendo perguntas no StackOverflow e usando a tag google-kubernetes-engine para pesquisar problemas semelhantes. Você também pode participar do canal do Slack #kubernetes-engine para receber mais suporte da comunidade.
  • Abrir bugs ou solicitações de recursos usando o Issue Tracker público.