Solução de problemas

Nesta página, mostramos as etapas de solução de problemas com o Google Kubernetes Engine (GKE).

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

Depurar recursos do Kubernetes

Para recursos do Kubernetes, se você tiver um problema com:

Resolver problemas com o comando kubectl

Esta seção contém etapas de solução de problemas para vários tipos de problemas com o comando kubectl.

Problema: comando kubectl não encontrado

Se você receber uma mensagem informando que o comando kubectl não foi encontrado, reinstale o binário kubectl e defina a variável de ambiente $PATH.

  1. Instale o kubectl binário executando o seguinte comando:

    gcloud components update kubectl

  2. Responda "sim" quando a modificação da variável de ambiente $PATH for solicitada no instalador. Quando essas variáveis são modificadas, você consegue usar os comandos kubectl sem digitar o caminho completo.

    Outra alternativa é adicionar a seguinte linha a qualquer lugar em que o shell armazene variáveis de ambiente, como ~/.bashrc (ou ~/.bash_profile no macOS):

    export PATH=$PATH:/usr/local/share/google/google-cloud-sdk/bin/

  3. Execute o comando a seguir para carregar o arquivo atualizado. O exemplo a seguir usa .bashrc:

    source ~/.bashrc

    Se você estiver usando o macOS, use ~/.bash_profile em vez de .bashrc.

Problema: comandos do kubectl retornam erro de "conexão recusada"

Se os comandos kubectl retornarem um erro de "conexão recusada", você precisará definir o contexto do cluster com o seguinte comando:

  gcloud container clusters get-credentials CLUSTER_NAME

Se você não tiver certeza sobre o que inserir em CLUSTER_NAME, use o comando a seguir para listar os clusters:

  gcloud container clusters list

Erro: o comando kubectl expirou

Se você criou um cluster e tentou executar o comando kubectl no cluster, mas o comando kubectl expirou, um erro como este será exibido:

  • Unable to connect to the server: dial tcp IP_ADDRESS: connect: connection timed out
  • Unable to connect to the server: dial tcp IP_ADDRESS: i/o timeout.

Esses erros indicam que kubectl não consegue se comunicar com o plano de controle do cluster.

Para resolver esse problema, verifique e defina o contexto em que o cluster está definido e garanta a conectividade com o cluster:

  1. Acesse $HOME/.kube/config ou execute o comando kubectl config view para verificar se o arquivo de configuração contém o contexto do cluster e o endereço IP externo do plano de controle.

  2. Defina as credenciais do cluster:

    gcloud container clusters get-credentials CLUSTER_NAME \
    --location=COMPUTE_LOCATION \
    --project=PROJECT_ID

    Substitua:

    • CLUSTER_NAME: o nome do cluster.
    • COMPUTE_LOCATION: o local do Compute Engine.
    • PROJECT_ID: ID do projeto em que o cluster do GKE foi criado.

  3. Se o cluster for um cluster particular do GKE, verifique se a lista de redes autorizadas atuais inclui o IP de saída da máquina de onde você está tentando se conectar. É possível encontrar suas redes autorizadas no console ou executando o seguinte comando:

    gcloud container clusters describe CLUSTER_NAME \
    --location=COMPUTE_LOCATION \
    --project=PROJECT_ID \
    --format "flattened(masterAuthorizedNetworksConfig.cidrBlocks[])"

    Se o IP de saída da máquina não estiver incluído na lista de redes autorizadas na saída do comando anterior, faça o seguinte:

Erro: os comandos kubectl retornam o erro "falha ao negociar versão da API"

Se os comandos kubectl retornarem um erro de "falha ao negociar versão da API", é necessário garantir que o kubectl tenha credenciais de autenticação:

  gcloud auth application-default login

Problema: os comandos kubectl logs, attach, exec e port-forward pararam de responder

Se os comandos kubectl logs, attach, exec ou port-forward pararem de responder, normalmente o servidor da API não poderá se comunicar com os nós.

Primeiro, verifique se o cluster tem nós. Se você reduziu o número de nós no cluster a zero, os túneis SSH não funcionam. Para resolver esse problema, redimensione o cluster para ter pelo menos um nó.

Se o cluster tiver pelo menos um nó, verifique se você está usando túneis SSH ou de proxy de conectividade para ativar a comunicação segura. As seções a seguir discutem as etapas de solução de problemas específicas para cada abordagem:

Resolver problemas de SSH

Se você estiver usando SSH, o GKE vai salvar um arquivo de chave pública SSH nos metadados do projeto do Compute Engine. Todas as VMs do Compute Engine que usam as imagens fornecidas pelo Google verificam regularmente os metadados comuns do projeto e os metadados da instância em busca das chaves SSH para adicionar à lista de usuários autorizados da VM. Além disso, o GKE adiciona uma regra de firewall à rede do Compute Engine, o que permite o acesso SSH do endereço IP do plano de controle a cada nó no cluster.

Os problemas com SSH podem ser causados por:

  • As regras de firewall da rede não permitem acesso SSH ao plano de controle.

    Todas as redes do Compute Engine são criadas com uma regra de firewall chamada default-allow-ssh, que permite o acesso SSH de todos os endereços IP, certamente com uma chave privada válida. O GKE também insere uma regra SSH em cada cluster público no formato gke-CLUSTER_NAME-RANDOM_CHARACTERS-ssh, que permite o acesso SSH especificamente do plano de controle do cluster aos nós do cluster.

    Se não houver nenhuma dessas regras, o plano de controle não poderá abrir os túneis SSH.

    Para verificar se essa é a causa do problema, verifique se a configuração tem essas regras.

    Para resolver esse problema, identifique a tag que está em todos os nós do cluster e adicione novamente uma regra de firewall que permita o acesso às VMs com essa tag do endereço IP do plano de controle.

  • A entrada de metadados comuns para ssh-keys está cheia.

    Se a entrada de metadados do projeto chamada "ssh-keys" estiver próxima do limite máximo de tamanho, o GKE não poderá adicionar a própria chave SSH para abrir túneis SSH.

    Para verificar se esse é o problema, verifique o comprimento da lista de chaves SSH. Para conferir os metadados do seu projeto, execute o comando abaixo, incluindo a flag --project, se quiser:

    gcloud compute project-info describe [--project=PROJECT_ID]

    Para resolver esse problema, exclua algumas chaves SSH que não são mais necessárias.

  • Você definiu um campo de metadados com a chave “ssh-keys” nas VMs no cluster.

    O agente de nó nas VMs prefere as chaves SSH por instância do que do projeto inteiro. Portanto, se você definiu essas chaves especificamente nos nós do cluster, a chave SSH do plano de controle nos metadados do projeto não será usada pelos nós.

    Para verificar se esse é o problema, execute gcloud compute instances describe VM_NAME e procure um campo ssh-keys nos metadados.

    Para corrigir o problema, exclua as chaves SSH por instância dos metadados da instância.

Resolver problemas do proxy de conectividade

Para determinar se o cluster usa o proxy Konnectivity, verifique a seguinte implantação do sistema:

  kubectl get deployments konnectivity-agent --namespace kube-system

Os problemas com o proxy de conectividade podem ser causados por:

  • As regras de firewall da rede não permitem o acesso do agente Konnectivity ao plano de controle.

    Na criação do cluster, os pods do agente Konnectivity estabelecem e mantêm uma conexão com o plano de controle na porta 8132. Quando um dos comandos kubectl é executado, o servidor da API usa essa conexão para se comunicar com o cluster.

    Se as regras de firewall da rede tiverem regras de negação de saída, elas poderão impedir a conexão do agente.

    Para verificar se essa é a causa do problema, verifique se as regras de firewall da sua rede têm regras de negação de saída.

    Para resolver esse problema, permita o tráfego de saída para o plano de controle do cluster na porta 8132. (Para comparação, o servidor da API usa 443).

  • A política de rede do cluster bloqueia a entrada do namespace kube-system para o namespace workload.

    Esses recursos não são necessários para o funcionamento correto do cluster. Se você preferir manter a rede do cluster bloqueada contra qualquer acesso externo, saiba que recursos como esse não funcionarão.

    Para verificar se essa é a causa do problema, encontre as políticas de rede no namespace afetado executando o seguinte comando:

    kubectl get networkpolicy --namespace AFFECTED_NAMESPACE

    Para resolver esse problema, adicione o seguinte ao campo spec.ingress das políticas de rede:

    - from:
  - namespaceSelector:
      matchLabels:
        kubernetes.io/metadata.name: kube-system
    podSelector:
      matchLabels:
        k8s-app: konnectivity-agent

Resolver problemas de erro 4xx

As seções a seguir ajudam você a resolver os erros 400, 401, 403, 404 e erros de autenticação e autorização relacionados.

Erros de autenticação e autorização ao se conectar a clusters do GKE

Ao se conectar a clusters do GKE, você pode receber um erro de autenticação e autorização com o código de status HTTP 401 (Não autorizado). Esse problema pode ocorrer quando você tenta executar um comando kubectl no cluster do GKE em um ambiente local.

A causa desse problema pode ser uma das seguintes:

  • O plug-in de autenticação gke-gcloud-auth-plugin não está instalado ou configurado corretamente.
  • Você não tem as permissões para se conectar ao servidor da API do cluster e executar comandos kubectl.

Para diagnosticar a causa, siga as etapas nas seções a seguir:

  1. Conecte-se ao cluster usando curl
  2. Configurar o plug-in no kubeconfig

Conecte-se ao cluster usando curl

Para diagnosticar a causa do erro de autenticação e autorização, conecte-se ao cluster usando curl. O uso de curl ignora a CLI kubectl e o plug-in gke-gcloud-auth-plugin.

  1. Defina as variáveis de ambiente:

    APISERVER=https://$(gcloud container clusters describe CLUSTER_NAME --location=COMPUTE_LOCATION --format "value(endpoint)")
TOKEN=$(gcloud auth print-access-token)

  2. Verifique se o token de acesso é válido:

    curl https://oauth2.googleapis.com/tokeninfo?access_token=$TOKEN

  3. Tente se conectar ao endpoint principal da API no servidor da API:

    gcloud container clusters describe CLUSTER_NAME --location=COMPUTE_LOCATION --format "value(masterAuth.clusterCaCertificate)" | base64 -d > /tmp/ca.crt
curl -s -X GET "${APISERVER}/api/v1/namespaces" --header "Authorization: Bearer $TOKEN" --cacert /tmp/ca.crt

    Se o comando curl for bem-sucedido, verifique se o plug-in é a causa usando as etapas na seção Configurar o plug-in no kubeconfig.

    Se o comando curl falhar com uma saída semelhante à seguinte, você não terá as permissões corretas para acessar o cluster:

    {
"kind": "Status",
"apiVersion": "v1",
"metadata": {},
"status": "Failure",
"message": "Unauthorized",
"reason": "Unauthorized",
"code": 401
}

Para resolver esse problema, adquira as permissões corretas para acessar o cluster.

Configurar o uso do plug-in no kubeconfig

Se você receber erros de autenticação e autorização ao se conectar aos clusters, mas conseguir se conectar ao cluster usando curl, verifique se é possível acessar o cluster sem precisar do plug-in gke-gcloud-auth-plugin.

Para resolver esse problema, configure seu ambiente local para ignorar o binário gke-gcloud-auth-plugin ao autenticar no cluster. Nos clientes do Kubernetes com a versão 1.25 e mais recentes, o binário gke-gcloud-auth-plugin é obrigatório. Portanto, use a CLI kubectl versão 1.24 ou anterior.

Siga estas etapas para acessar o cluster sem precisar do plug-in:

  1. Instale a CLI kubectl versão 1.24 usando curl:

    curl -LO https://dl.k8s.io/release/v1.24.0/bin/linux/amd64/kubectl

    É possível usar qualquer CLI kubectl versão 1.24 ou anterior.

  2. Abra o arquivo de script de inicialização do shell, como .bashrc para o shell Bash, em um editor de texto:

    vi ~/.bashrc

    Se você estiver usando o MacOS, use ~/.bash_profile em vez de .bashrc nestas instruções.

  3. Adicione a seguinte linha ao arquivo e salve-o:

    export USE_GKE_GCLOUD_AUTH_PLUGIN=False

  4. Execute o script de inicialização:

    source ~/.bashrc

  5. Receba credenciais para o cluster, que configura o arquivo .kube/config:

    gcloud container clusters get-credentials CLUSTER_NAME \
    --location=COMPUTE_LOCATION

    Substitua:

  6. Execute um comando kubectl:

    kubectl cluster-info

Se você receber um erro 401 ou um erro de autorização semelhante ao executar esses comandos, verifique se tem as permissões corretas e execute novamente a etapa que retornou o erro.

Erro 400: o pool de nós requer recriação

Um erro 400, o pool de nós requer recriação, é semelhante a este:

  ERROR: (gcloud.container.clusters.update) ResponseError: code=400, message=Node pool "test-pool-1" requires recreation.

Esse erro ocorre quando você tenta realizar uma ação que recria o plano de controle e os nós. Por exemplo, esse erro pode ocorrer quando você conclui uma rotação de credenciais em andamento.

No back-end, os pools de nós são marcados para recriação, mas a operação de recriação real pode levar algum tempo para começar. Portanto, a operação falha porque o GKE ainda não recriou um ou mais pools de nós no cluster.

Para resolver esse problema, faça uma das seguintes ações:

  • Espere a recriação acontecer. Isso pode levar horas, dias ou semanas, dependendo de fatores como janelas de manutenção e exclusões atuais.

  • Inicie manualmente uma recriação dos pools de nós afetados iniciando um upgrade para a mesma versão do plano de controle.

    Para iniciar uma recriação, execute o seguinte comando:

    gcloud container clusters upgrade CLUSTER_NAME \
    --node-pool=POOL_NAME

    Quando o upgrade for concluído, tente a operação novamente.

Erro 403: permissões insuficientes

Um erro 403, permissões insuficientes, semelhante ao seguinte:

  ERROR: (gcloud.container.clusters.get-credentials) ResponseError: code=403, message=Required "container.clusters.get" permission(s) for "projects/<your-project>/locations/<region>/clusters/<your-cluster>".

Este erro ocorre quando você tenta se conectar a um cluster do GKE usando gcloud container clusters get-credentials, mas a conta não tem permissão para acessar o servidor da API Kubernetes.

Para resolver esse problema, faça o seguinte:

  1. Identifique a conta com problema de acesso:

    gcloud auth list

  2. Conceda o acesso necessário à conta seguindo as instruções em Como autenticar no servidor da API Kubernetes.

Erro 403: orçamento de nova tentativa esgotado

O seguinte erro ocorre quando você tenta criar um cluster do GKE:

Error: googleapi: Error 403: Retry budget exhausted: Google Compute Engine:
Required permission 'PERMISSION_NAME' for 'RESOURCE_NAME'.

Nesta mensagem de erro, as seguintes variáveis se aplicam:

  • PERMISSION_NAME: o nome de uma permissão, como compute.regions.get.
  • RESOURCE_NAME: o caminho para o recurso do Google Cloud que você estava tentando acessar, como uma região do Compute Engine.

Esse erro ocorre se a conta de serviço do IAM anexada ao cluster não tiver as permissões mínimas necessárias para criar o cluster.

Para resolver esse problema, faça o seguinte:

  1. Crie ou modifique uma conta de serviço do IAM para ter todas as permissões necessárias para executar um cluster do GKE. Para mais instruções, consulte Usar contas de serviço IAM de privilégio mínimo.
  2. Especifique a conta de serviço do IAM atualizada no comando de criação do cluster usando a flag --service-account. Para acessar instruções, consulte Criar um cluster do Autopilot.

Como alternativa, omita a flag --service-account para permitir que o GKE use a conta de serviço padrão do Compute Engine no projeto, que tem as permissões necessárias por padrão.

Erro 404: recurso "não encontrado" ao chamar comandos gcloud container

Se você receber um erro 403, recurso não encontrado, ao chamar comandos gcloud container, resolva o problema fazendo a autenticação novamente na CLI do Google Cloud:

  gcloud auth login

Erro 400/403: permissões de edição ausentes na conta

Um erro de permissões de edição ausentes na conta (erro 400 ou 403) indica que uma das seguintes opções foi excluída ou editada manualmente:

Quando você ativa a API Compute Engine ou Kubernetes Engine, o Google Cloud cria as seguintes contas de serviço e agentes:

  • Conta de serviço padrão do Compute Engine com permissões para edição no projeto.
  • O Agente de serviço de APIs do Google com permissões para edição no projeto.
  • Conta de serviço do Google Kubernetes Engine com o papel de Agente de serviço do Kubernetes Engine no projeto.

A criação de clusters e toda a funcionalidade de gerenciamento vão falhar se, a qualquer momento, alguém editar essas permissões, remover as vinculações de papéis do projeto, remover a conta de serviço inteira ou desativar a API.

Para verificar se a conta de serviço do Google Kubernetes Engine tem o papel de Agente de serviço do Kubernetes Engine atribuído no projeto, siga estas etapas:

  1. Use o seguinte padrão para calcular o nome da sua conta de serviço do Google Kubernetes Engine:

    service-PROJECT_NUMBER@container-engine-robot.iam.gserviceaccount.com

    Substitua PROJECT_NUMBER pelo número do projeto.

  2. Verifique se a conta de serviço do Google Kubernetes Engine ainda não tem o papel de Agente de serviço do Kubernetes Engine atribuído no projeto. Neste comando, substitua PROJECT_ID pelo ID do projeto:

    gcloud projects get-iam-policy PROJECT_ID

Faça o seguinte para resolver o problema,

  • Se alguém tiver removido o papel de Agente de serviço do Kubernetes Engine da sua conta de serviço do Google Kubernetes Engine, adicione-o novamente.

  • Caso contrário, use as instruções a seguir para reativar a API Kubernetes Engine, que vai restaurar corretamente suas contas de serviço e permissões.

Console

  1. Acesse a página APIs e serviços no Console do Google Cloud.

    Acessar APIs e serviços

  2. Selecione o projeto.

  3. Clique em Ativar APIs e serviços.

  4. Procure pelo Kubernetes e selecione a API nos resultados da pesquisa.

  5. Clique em Ativar. Se já tiver ativado a API, você precisa primeiro desativá-la e, em seguida, reativá-la. Pode levar alguns minutos para que a API e os serviços relacionados sejam ativados.

gcloud

Execute o seguinte comando na gcloud CLI:

PROJECT_NUMBER=$(gcloud projects describe "PROJECT_ID"
    --format 'get(projectNumber)')
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member "serviceAccount:service-${PROJECT_NUMBER?}@container-engine-robot.iam.gserviceaccount.com" \
    --role roles/container.serviceAgent

Resolver problemas com a criação de clusters do GKE

Erro Condition_NOT_MET: restrição constraints/compute.vmExternalIpAccess violada

Você tem a restrição da política da organização constraints/compute.vmExternalIpAccess configurada como Deny All ou para restringir IPs externos a instâncias de VM específicas no nível da organização, da pasta ou do projeto em que está tentando criar um cluster público do GKE.

Quando você cria clusters públicos do GKE, as VMs subjacentes do Compute Engine, que compõem os nós de trabalho desse cluster, têm endereços IP externos atribuídos. Se você configurar a restrição constraints/compute.vmExternalIpAccess da política da organização para Deny All ou restringir IPs externos a instâncias de VM específicas, a política vai impedir que os nós de trabalho do GKE recebam endereços IP externos, o que resulta na falha na criação do cluster.

Para encontrar os registros da operação de criação de cluster, confira os registros de auditoria das operações de cluster do GKE usando o Explorador de registros com uma consulta de pesquisa semelhante a esta:

resource.type="gke_cluster"
logName="projects/test-last-gke-sa/logs/cloudaudit.googleapis.com%2Factivity"
protoPayload.methodName="google.container.v1beta1.ClusterManager.CreateCluster"
resource.labels.cluster_name="CLUSTER_NAME"
resource.labels.project_id="PROJECT_ID"

Para resolver esse problema, verifique se a política efetiva para a restrição constraints/compute.vmExternalIpAccess é Allow All no projeto em que você está tentando criar um cluster público do GKE. Consulte Como restringir endereços IP externos a instâncias de VM específicas para saber como trabalhar com essa restrição. Depois de definir a restrição como Allow All, exclua o cluster com falha e crie um novo. Isso é necessário porque não é possível reparar o cluster com falha.

Resolver problemas com cargas de trabalho implantadas

O GKE retornará um erro se houver problemas com os pods de uma carga de trabalho. Verifique o status de um pod usando a ferramenta de linha de comando kubectl ou o Console do Google Cloud.

kubectl

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

kubectl get pods

Saída:

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

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.

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 desejada. A guia Visão geral exibe o status da carga de trabalho.

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

Veja nas seções a seguir alguns erros comuns retornados por cargas de trabalho e como resolvê-los.

Erro: CrashLoopBackOff

CrashLoopBackOff indica que um contêiner está repetidamente falhando após a reinicialização. Um contêiner pode falhar por vários motivos. Verificar os registros de um pod ajuda na solução de problemas da causa raiz.

Por padrão, os contêineres com falha são reiniciados com um atraso exponencial limitado a cinco minutos. Altere esse comportamento configurando o campo restartPolicy Especificação do pod de implantação em spec: restartPolicy. O valor padrão do campo é Always.

É possível resolver erros CrashLoopBackOff usando o console do Google Cloud:

  1. Acesse o manual interativo de pods com loop de falhas:

    Acessar o manual

  2. Em Cluster, insira o nome do cluster que você quer solucionar.

  3. Em Namespace, insira o namespace que você quer solucionar.

  4. (Opcional) Crie um alerta para receber notificações sobre futuros erros do CrashLoopBackOff:

    1. Na seção Dicas de mitigação futura, selecione Criar um alerta.

Inspecionar registros

Descubra o motivo da falha no contêiner do pod usando a ferramenta de linha de comando kubectl ou o Console do Cloud.

kubectl

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

kubectl get pods

Procure o pod com o erro CrashLoopBackOff.

Para receber os registros do pod, execute o seguinte comando:

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.

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 desejada. 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.

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

Para encontrar o código de saída, execute as seguintes tarefas:

  1. Execute este comando:

    kubectl describe pod POD_NAME

    Substitua POD_NAME pelo nome do pod.

  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 aplicativo 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.

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

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.

Agora, é possível executar comandos bash no contêiner: teste a rede ou verifique se você tem acesso a arquivos ou bancos de dados usados pelo aplicativo.

Erros ImagePullBackOff e ErrImagePull

ImagePullBackOff e ErrImagePull indicam 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.

kubectl

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

kubectl describe pod POD_NAME

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 desejada. 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.

Problema: se a imagem não for encontrada

Se sua imagem não for encontrada:

  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. Tente extrair a imagem do docker manualmente:

    • Use SSH para acessar o nó:

      Por exemplo, para se conectar a uma VM por SSH:

      gcloud compute ssh VM_NAME --zone=ZONE_NAME

      Substitua:

    • Execute docker-credential-gcr configure-docker. Esse comando gera um arquivo de configuração em /home/[USER]/.docker/config.json. Verifique se esse arquivo 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"
  }
}

    • Execute docker pull IMAGE_NAME.

    Se essa opção funcionar, você provavelmente precisará especificar ImagePullSecrets em um pod. Os pods só podem referenciar segredos de extração de imagem nos próprios namespaces. 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.

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. Consulte Como usar registros privados para mais informações.

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

  1. Identifique o nó que executa o pod:

    kubectl describe pod POD_NAME | grep "Node:"

  2. Verifique se o nó 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 itens 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

  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

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

Se você tiver configurado seu cluster do GKE para enviar métricas do servidor da API Kubernetes e do programador do Kubernetes ao Cloud Monitoring, veja mais informações sobre esses erros em métricas do programador e Métricas do servidor de API de dois minutos.

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

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

    Acessar o manual

  2. Em Cluster, insira o nome do cluster que você quer solucionar.

  3. Em Namespace, insira o namespace que você quer solucionar.

  4. (Opcional) Crie um alerta para receber notificações sobre futuros erros do PodUnschedulable:

    1. 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: "não há nós disponíveis que correspondam a todos os predicados: CPU insuficiente (2)", o 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

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ó que você quer;
  • 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.

Erro: PodToleratesNodeTaints

PodToleratesNodeTaints indica que o pod não pode ser programado para qualquer nó porque nenhum deles atualmente tolera o taint do nó.

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.

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

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 desejado. 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ó desejado.

  2. Em "Detalhes do nó", clique no botão Não programável.

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.

  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. É possível tentar 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.

Erro: "falha ao alocar para o intervalo 0: nenhum endereço IP no conjunto do intervalo"

Versão 1.18.17 do GKE e versões mais recentes corrigiram um problema em que eventos de falta de memória (OOM, na sigla em inglês) resultavam na remoção incorreta do pod se o pod fosse excluído antes de seus contêineres serem iniciados. Essa remoção incorreta pode resultar em pods órfãos que continuaram tendo endereços IP reservados do intervalo de nós alocado. Com o tempo, o GKE ficou sem endereços IP para alocar a novos pods por causa da criação de pods órfãos. Isso levou à mensagem de erro failed to allocate for range 0: no IP addresses in range set, porque o intervalo de nós alocado não tinha IPs disponíveis para atribuir a novos pods.

Para resolver esse problema, faça upgrade dos pools de nós e do cluster para a versão 1.18.17 ou posterior do GKE.

Para evitar esse problema e resolvê-lo em clusters com versões do GKE anteriores à 1.18.17, aumente seus limites de recursos para evitar eventos de OOM no futuro e, em seguida, recupere os endereços IP removendo os pods órfãos.

Também é possível ver os insights de uso do endereço IP do GKE.

Remova os pods órfãos dos nós afetados

Para remover os pods órfãos, esvazie o nó, faça upgrade do pool de nós ou mova os diretórios afetados.

Drenar o nó (recomendado)

  1. Restrinja o nó para evitar que novos pods sejam programados nele:

     kubectl cordon NODE

    Substitua NODE pelo nome do nó que você quer drenar.

  2. Drene o nó. O GKE reprograma automaticamente os pods gerenciados por implantações em outros nós. Use a sinalização --force para drenar pods órfãos que não tenham um recurso de gerenciamento.

     kubectl drain NODE --force

  3. Remova a restrição do nó para permitir que o GKE programe novos pods nele:

     kubectl uncordon NODE

Como mover os diretórios afetados

É possível identificar diretórios de pods órfãos em /var/lib/kubelet/pods e retirá-los do diretório principal para permitir que o GKE encerre os pods.

Resolver problemas com o encerramento de recursos

Problema: namespace travado no estado Terminating





## Debug GKE Cluster Austoscaler issues with gcpdiag

















  
  

gcpdiag
is an open source tool. It is not an officially supported Google Cloud product.
You can use the gcpdiag tool to help you identify and fix Google Cloud
project issues. For more information, see the
gcpdiag project on GitHub.




  
This gcpdiag runbook investigates potential causes for GKE
Cluster Autoscaler failures while performing scale up or scale down operations.
It looks for the following error message in logs:
<ul>
  <li><strong>scale.up.error.out.of.resources</strong></li>
  <li><strong>scale.up.error.quota.exceeded</strong></li>
  <li><strong>scale.up.error.waiting.for.instances.timeout</strong></li>
  <li><strong>scale.up.error.ip.space.exhausted</strong></li>
  <li><strong>scale.up.error.service.account.deleted</strong></li>
  <li><strong>scale.down.error.failed.to.evict.pods</strong></li>
  <li><strong>no.scale.down.node.node.group.min.size.reached</strong></li>
</ul>







    


  
Google Cloud console

  
    
    
  1. Complete and then copy the following command. 
    2. 
       
    gcpdiag runbook gke/cluster-autoscaler --project=<var>PROJECT_ID</var> \\
    --parameter name=<var>CLUSTER_NAME</var> \\
    --parameter location=<var>LOCATION</var>
    
    
  2. Abra o console do Google Cloud e ative o Cloud Shell.
    3. 
    

Abrir Console do Cloud

    
  3. Cole o comando copiado.
    4. 
    
  4. Execute o comando gcpdiag, que faz o download da imagem Docker gcpdiag.
      e realiza verificações de diagnóstico. Se aplicável, siga as instruções de saída
      para corrigir verificações com falha.
    
    5. 
  


  

    
  
    Docker
    
  
    Você pode 
  executar gcpdiag usando um wrapper que inicia gcpdiag em um contêiner do Docker. Docker ou
  Podman precisa ser instalado.
    
  
      
    
    1. Copie e execute o seguinte comando na estação de trabalho local.
      
      curl https://gcpdiag.dev/gcpdiag.sh >gcpdiag && chmod +x gcpdiag
      
      
      2. 
      
    2.  Execute o comando gcpdiag.
        
      ./gcpdiag runbook gke/cluster-autoscaler --project=<var>PROJECT_ID</var> \\
    --parameter name=<var>CLUSTER_NAME</var> \\
    --parameter location=<var>LOCATION</var>
      
      
      3. 

   
 
    

    



    


    Veja os parâmetros disponíveis para este runbook.
    


    Substitua:
    

      
  
    • PROJECT_ID: o ID do projeto que contém o recurso
      • 
  
  
  <li><var>CLUSTER_NAME</var>: o nome do cluster do GKE de destino no seu projeto.</li>
  <li><var>LOCATION</var>: o local em que o cluster do GKE de destino está localizado (essa é a zona para o cluster zonal ou a região para o cluster regional).</li>

  

    

    Flags úteis
    



    Para conferir uma lista e descrição de todas as flags da ferramenta gcpdiag, consulte
  Instruções de uso do gcpdiag.
    


    




## Resolver problemas de métricas do cluster que não aparecem no Cloud Monitoring {:#no_metrics}

Verifique se você
[ativou a API Monitoring](/monitoring/api/enable-api) e a
[API Logging](/logging/docs/api/enable-api) no seu projeto. Você
também precisa confirmar que consegue acessar seu projeto na
[Visão geral do Cloud Monitoring](https://console.cloud.google.com/monitoring) no
console do Google Cloud.

Se o problema continuar, verifique estas possíveis causas:

1.  Verifique se o monitoramento está ativado no cluster.

    O monitoramento é ativado por padrão para clusters criados no console do Google Cloud e na CLI do Google Cloud, mas você pode conferir executando o comando a seguir ou clicando nos detalhes do cluster no [console do Google Cloud](https://console.cloud.google.com/):

```sh
    gcloud container clusters describe CLUSTER_NAME
    ```

A saída desse comando deve incluir "SYSTEM_COMPONENTS" na lista de "enableComponents" na seção "monitoringConfig", semelhante a este:

```
    monitoringConfig:
      componentConfig:
        enableComponents:
        - SYSTEM_COMPONENTS
    ```

Se o monitoramento não estiver ativado, execute o comando a seguir para ativá-lo:

```sh
    gcloud container clusters update CLUSTER_NAME --monitoring=SYSTEM
    ```

1.  Quanto tempo faz desde que o cluster foi criado ou desde que o monitoramento foi ativado?

    Pode levar até uma hora para que as métricas de um novo cluster comecem a aparecer no Cloud Monitoring.

1.  Um "heapster" ou "gke-metrics-agent" (o coletor OpenTelemetry) está em execução
    no cluster no namespace "kube-system"?

    Talvez esse pod não consiga programar cargas de trabalho porque o cluster pode estar com poucos recursos. Confira se o Heapster ou o OpenTelemetry está
    em execução chamando `kubectl get pods --namespace=kube-system` e verificando
    se há pods com `heapster` ou `gke-metrics-agent` no nome.

1.  O plano de controle do cluster pode se comunicar com os nós?

    O Cloud Monitoring depende disso. Para verificar se esse é o caso, execute o seguinte comando:

    ```sh
    kubectl logs POD_NAME
    ```

    Se esse comando retornar um erro, os túneis SSH podem estar causando o
    problema. Consulte [esta seção](/kubernetes-engine/docs/troubleshooting#kubect_commands_stops)
    para mais informações.

Se você tiver um problema relacionado ao agente do Cloud Logging, consulte a
[documentação de solução de problemas].

Para mais informações, consulte a [documentação de registro](/logging/docs/).




## Issue: cluster's root Certificate Authority expiring soon {:#ca_expiring}

A autoridade certificadora raiz do cluster vai expirar em breve. Para evitar que operações normais do cluster sejam interrompidas, é necessário executar uma [rotação de
credenciais](/kubernetes-engine/docs/how-to/credential-rotation).

## Erro: "A instância 'Foo' não contém metadados 'modelo de instância'" {:#instance-template-missing}

Você pode encontrar o erro "A instância 'Foo' não contém metadados 'modelo de instância'" como um status de um pool de nós que falha ao fazer upgrade, escalonar ou realizar o reparo automático de nós.

Essa mensagem indica que os metadados das instâncias de VM, alocados pelo GKE, foram corrompidos. Isso normalmente acontece quando scripts ou automação criados sob medida
tentam adicionar novos metadados de instância (como [`block-project-ssh-keys`](/compute/docs/connect/restrict-ssh-keys#block-keys)),
e, em vez de apenas adicionar ou atualizar valores, também exclui os metadados atuais.
Leia sobre os metadados de instância de VM em [Como definir metadados personalizados](/compute/docs/storing-retrieving-metadata#custom).

Caso algum dos valores de metadados críticos, entre outros: "instance-template",
"kube-labels", "kubelet-config", "kubeconfig", "cluster-name", "configure-sh",
"cluster-uid", foram excluídos, o nó ou o pool de nós inteiro pode ficar em
um estado instável, já que esses valores são cruciais para as operações do GKE.



Se os metadados da instância foram corrompidos, a melhor maneira de recuperá-los é
recriar o pool de nós que contém as instâncias de VM corrompidas. Você
precisa [adicionar um pool de nós](/kubernetes-engine/docs/how-to/node-pools#add) ao
cluster e aumentar a contagem de nós no novo pool de nós, além de restringir e
remover nós em outro. Consulte as instruções para [migrar cargas de trabalho entre
pools de nós](/kubernetes-engine/docs/troubleshooting/troubleshoot-node-pools#migrate-node-pools).



Para descobrir quem e quando os metadados da instância foram editados, consulte as
[informações de geração de registros de auditoria do Compute Engine](/compute/docs/logging/audit-logging)
ou use o [Análise de registros](/logging/docs/view/logs-explorer-interface)
com uma consulta de pesquisa semelhante a esta:

```none
resource.type="gce_instance_group_manager"
protoPayload.methodName="v1.compute.instanceGroupManagers.setInstanceTemplate"
```

Nos registros, você pode encontrar o endereço IP e o agente do usuário do originador da solicitação:

``` json
requestMetadata: {
  callerIp: "REDACTED"
  callerSuppliedUserAgent: "google-api-go-client/0.5 GoogleContainerEngine/v1"
}
```





Para mais informações sobre segredos no GKE, consulte
[Como criptografar segredos na camada do aplicativo](/kubernetes-engine/docs/how-to/encrypting-secrets).

## Problema: a atualização da criptografia de secrets falhou {:#secrets_encryption_update_failed}

Se a operação para ativar, desativar ou
atualizar a [chave do Cloud KMS](/kubernetes-engine/docs/how-to/encrypting-secrets) falhar, consulte o guia
[Solução de problemas de criptografia de secrets na camada do aplicativo](/kubernetes-engine/docs/troubleshooting/troubleshoot-secrets).