Resolver problemas com cargas de trabalho implantadas

Autopilot Standard

---

Nesta página, mostramos como resolver erros com as cargas de trabalho implantadas no Google Kubernetes Engine (GKE).

Para conselhos mais gerais sobre a solução de problemas de aplicativos, consulte Solução de problemas de aplicativos na documentação do Kubernetes.

Todos os erros: verificar o status do pod

Se houver problemas com os pods de uma carga de trabalho, o Kubernetes vai atualizar o status do pod com uma mensagem de erro. Para conferir esses erros, verifique o status de um pod usando o console do Google Cloud ou a ferramenta de linha de comando kubectl.

Console

Siga as etapas abaixo:

1. No Console do Google Cloud, acesse a página Cargas de trabalho.

   Acesse "Cargas de trabalho"

2. Selecione a carga de trabalho que você quer investigar. A guia Visão geral exibe o status da carga de trabalho.

3. Na seção Gerenciar pods, clique em qualquer mensagem de status de erro.

kubectl

Para ver todos os pods em execução no cluster, execute o seguinte comando:

kubectl get pods

O resultado será assim:

NAME       READY  STATUS             RESTARTS  AGE
POD_NAME   0/1    CrashLoopBackOff   23        8d

Os possíveis erros são listados na coluna Status.

Para mais informações sobre um pod específico, execute o seguinte comando:

kubectl describe pod POD_NAME

Substitua POD_NAME pelo nome do pod que você quer investigar.

Na saída, o campo Events mostra mais informações sobre erros.

Para mais informações, consulte os registros do contêiner:

kubectl logs POD_NAME

Esses registros podem ajudar a identificar se um comando ou código no contêiner causou a falha do pod.

Depois de identificar o erro, use as seções a seguir para tentar resolver o problema.

Erro: CrashLoopBackOff

Um status de CrashLoopBackOff não significa que há um erro específico, mas indica que um contêiner está falhando repetidamente após a reinicialização. Quando um contêiner falha ou sai logo após a inicialização (CrashLoop), o Kubernetes tenta reiniciá-lo. A cada reinicialização falha, o atraso (BackOff) antes da próxima tentativa aumenta exponencialmente (10s, 20s, 40s, etc.), até um máximo de cinco minutos.

As seções a seguir ajudam a identificar por que o contêiner pode estar falhando.

Usar o playbook interativo de pods com loop de falhas

Comece a resolver problemas sobre o que está causando um status CrashLoopBackOff usando o livro de estratégia interativo no console do Google Cloud:

1. Acesse o manual interativo de pods com Crashlooping:

   Acessar o manual

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

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

4. Siga cada uma das seções para identificar a causa:

   1. Identificar erros do aplicativo
   2. Investigar problemas de falta de memória
   3. Investigue as interrupções de nós
   4. Investigar falhas de sondagem de atividade
   5. Correlacionar eventos de mudança

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

Inspecionar registros

Um contêiner pode falhar por vários motivos. Verificar os registros de um pod ajuda na solução de problemas da causa raiz.

É possível verificar os registros com o console do Google Cloud ou a ferramenta de linha de comando kubectl.

Console

Siga as etapas abaixo:

1. Acesse a página Cargas de trabalho no console do Google Cloud.

   Acesse "Cargas de trabalho"

2. Selecione a carga de trabalho que você quer investigar. A guia Visão geral exibe o status da carga de trabalho.

3. Na seção Gerenciar Pods, clique no Pod problemático.

4. No menu do pod, clique na guia Registros.

kubectl

1. Confira todos os pods em execução no cluster:

   kubectl get pods
   

2. Na saída do comando anterior, procure um pod com o erro CrashLoopBackOff na coluna Status.

3. Acesse os registros do pod:

   kubectl logs POD_NAME
   

   Substitua POD_NAME pelo nome do pod problemático.

   Também é possível transferir a sinalização -p para conseguir os registros da instância anterior do contêiner do pod, caso existam.

Verificar o código de saída do contêiner com falha

Para entender melhor por que o contêiner falhou, encontre o código de saída:

1. Descreva o pod:

   kubectl describe pod POD_NAME
   

   Substitua POD_NAME pelo nome do pod problemático.

2. Revise o valor no campo containers: CONTAINER_NAME: last state: exit code:

   • Se o código de saída for 1, o contêiner falhou porque o aplicativo falhou.
   • Se o código de saída for 0, verifique por quanto tempo seu app estava sendo executado. Os contêineres saem quando o processo principal do aplicativo é encerrado. Se seu aplicativo concluir a execução rápido demais, o contêiner pode continuar reiniciando. Se você receber esse erro, uma solução é definir o campo restartPolicy como OnFailure. Depois de fazer essa mudança, o app só será reiniciado quando o código de saída não for 0.

Conectar-se a um contêiner em execução

Para executar comandos bash no contêiner e testar a rede ou verificar se você tem acesso a arquivos ou bancos de dados usados pelo aplicativo, abra um shell para o pod:

kubectl exec -it POD_NAME -- /bin/bash

Se houver mais de um contêiner no pod, adicione -c CONTAINER_NAME.

Erros: ImagePullBackOff e ErrImagePull

Um status de ImagePullBackOff ou ErrImagePull indica que a imagem usada por um contêiner não pode ser carregada do registro de imagem.

Verifique esse problema usando o console do Google Cloud ou a ferramenta de linha de comando kubectl.

Console

Siga as etapas abaixo:

1. No Console do Google Cloud, acesse a página Cargas de trabalho.

   Acesse "Cargas de trabalho"

2. Selecione a carga de trabalho que você quer investigar. A guia Visão geral exibe o status da carga de trabalho.

3. Na seção Gerenciar Pods, clique no Pod problemático.

4. No menu do Pod, clique na guia Eventos.

kubectl

Para mais informações sobre a imagem do contêiner do pod, execute o seguinte comando:

kubectl describe pod POD_NAME

Problema: a imagem não foi encontrada

Se a imagem não for encontrada, siga estas etapas:

1. Verifique se o nome da imagem está correto.
2. Verifique se a tag da imagem está correta. (Tente :latest ou nenhuma tag para extrair a imagem mais recente).
3. Se a imagem tiver um caminho de registro completo, verifique se ela existe no registro do Docker que você está usando. Se você fornecer apenas o nome da imagem, verifique o registro do Docker Hub.

4. Em clusters do GKE Standard, tente extrair a imagem do Docker manualmente:

   1. Use o SSH para se conectar ao nó:

      Por exemplo, para usar o SSH para se conectar a uma VM, execute o seguinte comando:

      gcloud compute ssh VM_NAME --zone=ZONE_NAME
      

      Substitua:

      • VM_NAME: o nome da VM.
      • ZONE_NAME: uma zona do Compute Engine.

   2. Gere um arquivo de configuração em /home/[USER]/.docker/config.json:

      docker-credential-gcr configure-docker
      

      Verifique se o arquivo de configuração em /home/[USER]/.docker/config.json inclui o registro da imagem no campo credHelpers. Por exemplo, o arquivo a seguir inclui informações de autenticação para imagens hospedadas em asia.gcr.io, eu.gcr.io, gcr.io, marketplace.gcr.io e us.gcr.io:

      {
      "auths": {},
      "credHelpers": {
        "asia.gcr.io": "gcr",
        "eu.gcr.io": "gcr",
        "gcr.io": "gcr",
        "marketplace.gcr.io": "gcr",
        "us.gcr.io": "gcr"
      }
      }
      

   3. Tente extrair a imagem:

      docker pull IMAGE_NAME
      

   Se a extração da imagem funcionar manualmente, provavelmente será necessário especificar ImagePullSecrets em um pod. Os pods só podem referenciar segredos de extração de imagem em seu próprio namespace, portanto, esse processo precisa ser feito uma vez por namespace.

Erro: permissão recusada

Se você encontrar um erro de "permissão negada" ou "sem acesso para extrair", verifique se você está conectado e/ou tem acesso à imagem. Tente um dos métodos a seguir, dependendo do registro em que você hospeda as imagens.

Atenção: o Container Registry foi descontinuado e está programado para ser desativado. As organizações que não usaram o Container Registry antes de 8 de janeiro de 2024 terão novos repositórios gcr.io hospedados no Artifact Registry por padrão. A partir de 15 de maio de 2024, os projetos do Google Cloud sem uso anterior do Container Registry só serão compatíveis com a hospedagem e o gerenciamento de imagens para o domínio gcr.io no Artifact Registry.

A desativação do Container Registry está programada para 18 de março de 2025. Para detalhes sobre a descontinuação, consulte Suspensão de uso do Container Registry.

Artifact Registry

Se a imagem estiver no Artifact Registry, a conta de serviço do pool de nós precisará de acesso de leitura ao repositório que contém a imagem.

Conceda o papel artifactregistry.reader à conta de serviço.

gcloud artifacts repositories add-iam-policy-binding REPOSITORY_NAME \
    --location=REPOSITORY_LOCATION \
    --member=serviceAccount:SERVICE_ACCOUNT_EMAIL \
    --role="roles/artifactregistry.reader"

Substitua:

• REPOSITORY_NAME: o nome do repositório do Artifact Registry
• REPOSITORY_LOCATION: a região do repositório do Artifact Registry
• SERVICE_ACCOUNT_EMAIL: o endereço de e-mail da conta de serviço do IAM associada ao pool de nós.

Container Registry

Se a imagem estiver no Container Registry, a conta de serviço do pool de nós precisará de acesso de leitura ao bucket do Cloud Storage que contém a imagem.

Conceda o papel roles/storage.objectViewer à conta de serviço para que ela possa ler o bucket:

gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
    --member=serviceAccount:SERVICE_ACCOUNT_EMAIL \
    --role=roles/storage.objectViewer

Substitua:

• SERVICE_ACCOUNT_EMAIL: o e-mail da conta de serviço associada ao pool de nós. Liste todas as contas de serviço no seu projeto usando gcloud iam service-accounts list.
• BUCKET_NAME: o nome do bucket do Cloud Storage que contém as imagens. É possível listar todos os buckets no seu projeto usando gcloud storage ls.

Se o administrador de registro configurar repositórios gcr.io no Artifact Registry para armazenar imagens para o domínio gcr.io em vez do Container Registry, será preciso conceder acesso de leitura a Artifact Registry, em vez do Container Registry.

Registro particular

Se a imagem estiver em um registro particular, talvez você precise de chaves para acessar as imagens. Para mais informações, consulte Como usar registros privados na documentação do Kubernetes.

Erro 401 Não autorizado: não é possível extrair imagens do repositório particular do Container Registry

Um erro semelhante ao seguinte pode ocorrer ao extrair uma imagem de um repositório particular do Container Registry:

gcr.io/PROJECT_ID/IMAGE:TAG: rpc error: code = Unknown desc = failed to pull and
unpack image gcr.io/PROJECT_ID/IMAGE:TAG: failed to resolve reference
gcr.io/PROJECT_ID/IMAGE]:TAG: unexpected status code [manifests 1.0]: 401 Unauthorized

Warning  Failed     3m39s (x4 over 5m12s)  kubelet            Error: ErrImagePull
Warning  Failed     3m9s (x6 over 5m12s)   kubelet            Error: ImagePullBackOff
Normal   BackOff    2s (x18 over 5m12s)    kubelet            Back-off pulling image

Para resolver o erro, siga estas etapas:

1. Identifique o nó que executa o pod:

   kubectl describe pod POD_NAME | grep "Node:"
   

2. Verifique se o nó identificado na etapa anterior tem o escopo de armazenamento:

   gcloud compute instances describe NODE_NAME \
       --zone=COMPUTE_ZONE --format="flattened(serviceAccounts[].scopes)"
   

   O escopo de acesso do nó precisa conter pelo menos um dos escopos a seguir:

   serviceAccounts[0].scopes[0]: https://www.googleapis.com/auth/devstorage.read_only
   serviceAccounts[0].scopes[0]: https://www.googleapis.com/auth/cloud-platform
   

   Se o nó não tiver um desses escopos, recrie o pool de nós.

3. Recrie o pool de nós ao qual o nó pertence com escopo suficiente. Não é possível modificar os nós atuais. Você precisa recriar o nó com o escopo correto.

   • Recomendado: crie um novo pool de nós com o escopo gke-default:

     gcloud container node-pools create NODE_POOL_NAME \
         --cluster=CLUSTER_NAME \
         --zone=COMPUTE_ZONE \
         --scopes="gke-default"
     

   • Crie um novo pool de nós apenas com o escopo de armazenamento:

     gcloud container node-pools create NODE_POOL_NAME \
         --cluster=CLUSTER_NAME \
         --zone=COMPUTE_ZONE \
         --scopes="https://www.googleapis.com/auth/devstorage.read_only"
     

Erro: o pod não pode ser programado

Um status de PodUnschedulable indica que o pod não pode ser programado devido a recursos insuficientes ou a algum erro de configuração.

Se você tiver configurado métricas do plano de controle, encontre mais informações sobre esses erros em métricas do programador e métricas do servidor da API.

Usar o manual interativo de pods não programáveis

É possível resolver erros PodUnschedulable usando o playbook interativo no console do Google Cloud:

1. Acesse o playbook interativo de pods não programáveis:

   Acessar o manual

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

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

4. Para ajudar a identificar a causa, siga cada uma das seções do manual:

   1. Investigar CPU e memória
   2. Investigar o máximo de pods por nó
   3. Investigar comportamento do escalador automático
   4. Investigar outros modos de falha
   5. Correlacionar eventos de mudança

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

Erro: recursos insuficientes

Talvez você encontre um erro indicando falta de CPU, memória ou outro recurso. Por exemplo: No nodes are available that match all of the predicates: Insufficient cpu (2), que indica que, em dois nós, não há CPU suficiente disponível para atender às solicitações de um pod.

Se as solicitações de recursos do pod excederem o de um único nó de qualquer pool de nós qualificado, o GKE não vai programar o pod e também não acionará o escalonamento vertical para adicionar um novo nó. Para que o GKE programe o pod, é necessário solicitar menos recursos para o pod ou criar um novo pool de nós com recursos suficientes.

Também é possível ativar o provisionamento automático de nós para que o GKE possa criar automaticamente pools de nós com nós em que os pods não programados podem ser executados.

A solicitação de CPU padrão é 100m ou 10% de uma CPU (ou um núcleo). Se quiser solicitar mais ou menos recursos, especifique o valor na especificação do pod em spec: containers: resources: requests

Observação:o cluster executa contêineres do sistema no namespace kube-system. Esses contêineres também usam recursos de cluster.

Erro: MatchNodeSelector

MatchNodeSelector indica que não há nós que correspondam ao seletor de rótulos do pod.

Para verificar isso, confira os rótulos especificados no campo nodeSelector da especificação do pod, em spec: nodeSelector.

Para ver como os nós no cluster são rotulados, execute o seguinte comando:

kubectl get nodes --show-labels

Para anexar um rótulo a um nó, execute o seguinte comando:

kubectl label nodes NODE_NAME LABEL_KEY=LABEL_VALUE

Substitua:

• NODE_NAME: o nó em que você quer adicionar um rótulo.
• LABEL_KEY: a chave do rótulo.
• LABEL_VALUE: o valor do rótulo.

Para mais informações, consulte Como atribuir pods a nós na documentação do Kubernetes.

Erro: PodToleratesNodeTaints

PodToleratesNodeTaints indica que o pod não pode ser programado para nenhum nó porque ele não tem tolerâncias que correspondam aos taints de nó existentes.

Para verificar se esse é o caso, execute o seguinte comando:

kubectl describe nodes NODE_NAME

Na saída, verifique o campo Taints, que lista pares de valor-chave e efeitos de programação.

Se o efeito listado for NoSchedule, nenhum pod poderá ser programado nesse nó, a menos que exista uma tolerância correspondente.

Uma maneira de resolver esse problema é remover o taint. Para remover um taint NoSchedule, execute o seguinte comando:

kubectl taint nodes NODE_NAME key:NoSchedule-

Erro: PodFitsHostPorts

PodFitsHostPorts indica que uma porta que um nó está tentando usar já está em uso.

Para resolver esse problema, verifique o valor hostPort da especificação do pod em spec: containers: ports: hostPort. Pode ser necessário alterar esse valor para outra porta.

Erro: não há disponibilidade mínima

Se um nó tiver recursos adequados, mas ainda exibir a mensagem Does not have minimum availability, verifique o status do pod. Se o status for SchedulingDisabled ou Cordoned, o nó não poderá programar novos pods. É possível verificar o status de um nó usando o console do Google Cloud ou a ferramenta de linha de comando kubectl.

Console

Siga as etapas abaixo:

1. Acesse a página Google Kubernetes Engine no console do Google Cloud.

   Acessar o Google Kubernetes Engine

2. Selecione o cluster que você quer investigar. A guia Nós exibe os nós e o status deles.

Para ativar a programação no nó, execute as seguintes etapas:

1. Na lista, clique no nó que você quer investigar.

2. Na seção Detalhes do nó, clique em Não programável.

kubectl

Para receber o status dos seus nós, execute o seguinte comando:

kubectl get nodes

Para ativar a programação no nó, execute:

kubectl uncordon NODE_NAME

Erro: o limite máximo de pods por nó foi atingido

Se o limite Máximo de pods por nó for atingido por todos os nós no cluster, os pods ficarão presos no estado não programável. Na guia Eventos do pod, é mostrada uma mensagem incluindo a frase Too many pods.

Para resolver esse erro, siga estas etapas:

1. Verifique a configuração de Maximum pods per node na guia "Nós" nos detalhes do cluster do GKE no console do Google Cloud.

2. Consulte uma lista de nós:

   kubectl get nodes
   

3. Para cada nó, verifique o número de pods em execução nele:

   kubectl get pods -o wide | grep NODE_NAME | wc -l
   

4. Se o limite for atingido, adicione um novo pool de nós ou adicione mais nós ao atual.

Problema: tamanho máximo do pool de nós atingido com o escalonador automático de clusters ativado

Se o pool de nós atingir seutamanho máximo De acordo com a configuração do escalonador automático de cluster, o GKE não aciona o escalonamento vertical do pod que seria programado com esse pool de nós. Se você quiser que o pod seja programado com esse pool de nós, altere a configuração do escalonador automático de clusters.

Problema: tamanho máximo do pool de nós atingido com o escalonador automático de cluster desativado

Se o pool de nós atingir o número máximo de nós e o escalonador automático de cluster estiver desativado, o GKE não poderá programar o pod com o pool de nós. Aumente o tamanho do pool de nós ou ative o escalonador automático de clusters para que o GKE redimensione seu cluster automaticamente.

Erro: PersistentVolumeClaims não vinculados

Unbound PersistentVolumeClaims indica que o pod se refere a uma PersistentVolumeClaim não vinculada. Esse erro pode acontecer caso seu PersistentVolume falhe ao provisionar. É possível verificar se o provisionamento falhou procurando por erros nos eventos do seu PersistentVolumeClaim.

Para acessar eventos, execute o seguinte comando:

kubectl describe pvc STATEFULSET_NAME-PVC_NAME-0

Substitua:

• STATEFULSET_NAME: o nome do objeto StatefulSet.
• PVC_NAME: o nome do objeto PersistentVolumeClaim.

Isso também pode acontecer se houver um erro de configuração durante o pré-provisionamento manual de um PersistentVolume e sua vinculação a um PersistentVolumeClaim.

Para resolver esse erro, tente pré-aprovisionar o volume novamente.

Erro: cota insuficiente

Verifique se o projeto tem cota suficiente do Compute Engine para o GKE escalonar verticalmente o cluster. Se o GKE tentar adicionar um nó ao cluster para programar o pod e o escalonamento vertical exceder a cota disponível do projeto, você receberá a mensagem de erro scale.up.error.quota.exceeded.

Para saber mais, consulte Erros de ScaleUp.

Problema: APIs descontinuadas

Verifique se você não está usando APIs descontinuadas que foram removidas com a versão secundária do seu cluster. Para saber mais, consulte Descontinuações do GKE.

A seguir

Se precisar de mais ajuda, entre em contato com o Cloud Customer Care.