Resolver problemas com a ferramenta de linha de comando kubectl

Autopilot Standard

---

Nesta página, mostramos como resolver problemas com a ferramenta de linha de comando kubectl ao trabalhar no Google Kubernetes Engine (GKE). Para conselhos mais gerais, consulte Solução de problemas do kubectl na documentação do Kubernetes.

Erros de autenticação e autorização

Se você estiver enfrentando erros relacionados à autenticação e autorização ao usar os comandos da ferramenta de linha de comando kubectl, leia as seções a seguir para receber orientações.

Erro: 401 (não autorizado)

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 (Unauthorized). Esse problema pode ocorrer quando você tenta executar um comando kubectl no cluster do GKE em um ambiente local. Para saber mais, consulte Problema: erros de autenticação e autorização.

Erro: escopos de autenticação insuficientes

Ao executar gcloud container clusters get-credentials, você pode receber o seguinte erro:

ERROR: (gcloud.container.clusters.get-credentials) ResponseError: code=403, message=Request had insufficient authentication scopes.

Esse erro ocorre porque você está tentando acessar a API GKE de uma VM do Compute Engine que não tem o escopo cloud-platform.

Para resolver esse erro, conceda o escopo cloud-platform ausente. Para instruções sobre como mudar os escopos na instância de VM do Compute Engine, consulte Como criar e ativar contas de serviço para instâncias na documentação do Compute Engine.

Erro: gke-gcloud-auth-plugin executável não encontrado

Mensagens de erro semelhantes às seguintes podem ocorrer ao tentar executar comandos kubectl ou clientes personalizados que interagem com o GKE:

Unable to connect to the server: getting credentials: exec: executable gke-gcloud-auth-plugin not found

It looks like you are trying to use a client-go credential plugin that is not installed.

To learn more about this feature, consult the documentation available at:
      https://kubernetes.io/docs/reference/access-authn-authz/authentication/#client-go-credential-plugins

Visit cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl#install_plugin to install gke-gcloud-auth-plugin.

Unable to connect to the server: getting credentials: exec: fork/exec /usr/lib/google-cloud-sdk/bin/gke-gcloud-auth-plugin: no such file or directory

Para resolver o problema, instale o gke-gcloud-auth-plugin conforme descrito em Instalar plug-ins necessários.

Erro: nenhum provedor de autenticação foi encontrado

O seguinte erro ocorre se kubectl ou clientes personalizados do Kubernetes tiverem sido criados com o Kubernetes client-go versão 1.26 ou mais recente:

no Auth Provider found for name "gcp"

Para resolver esse problema, siga estas etapas:

1. Instale gke-gcloud-auth-plugin conforme descrito em Instalar os plug-ins necessários.

2. Atualize para a versão mais recente da CLI gcloud:

   gcloud components update
   

3. Atualize o arquivo kubeconfig:

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

   Substitua:

   • CLUSTER_NAME: o nome do cluster.
   • CONTROL_PLANE_LOCATION: o local do Compute Engine do plano de controle do cluster. Forneça uma região para clusters regionais ou uma zona para clusters zonais.

Erro: o plug-in auth do gcp está descontinuado. Use a gcloud

Você poderá ver a seguinte mensagem de aviso depois de instalar o gke-gcloud-auth-plugin e executar um comando kubectl em um cluster do GKE:

WARNING: the gcp auth plugin is deprecated in v1.22+, unavailable in v1.25+; use gcloud instead.

Essa mensagem vai aparecer se a versão do cliente for anterior à 1.26.

Para resolver esse problema, instrua seu cliente a usar o plug-in de autenticação gke-gcloud-auth-plugin:

1. Abra seu script de login do shell em um editor de texto:

   Bash

   vi ~/.bashrc

   Zsh

   vi ~/.zshrc

   Se você estiver usando o PowerShell, pule esta etapa.

2. Defina a variável de ambiente a seguir:

   Bash

   export USE_GKE_GCLOUD_AUTH_PLUGIN=True
   

   Zsh

   export USE_GKE_GCLOUD_AUTH_PLUGIN=True
   

   PowerShell

   [Environment]::SetEnvironmentVariable('USE_GKE_GCLOUD_AUTH_PLUGIN', True, 'Machine')
   

3. Aplique a variável no seu ambiente:

   Bash

   source ~/.bashrc

   Zsh

   source ~/.zshrc
   

   PowerShell

   Saia do terminal e abra uma nova sessão de terminal.

4. Atualizar a CLI gcloud:

   gcloud components update
   

5. Autenticar no cluster:

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

   Substitua:

   • CLUSTER_NAME: o nome do cluster.
   • CONTROL_PLANE_LOCATION: o local do Compute Engine do plano de controle do cluster. Forneça uma região para clusters regionais ou uma zona para clusters zonais.

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 binário kubectl:

   gcloud components update kubectl
   

2. Quando o instalador solicitar que você modifique a variável de ambiente $PATH, insira y para continuar. Quando essa variável é modificada, você consegue usar os comandos kubectl sem digitar o caminho completo.

   Outra alternativa é adicionar a seguinte linha ao local em que o shell armazena 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 seguinte comando 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", defina o contexto do cluster com o seguinte comando:

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

Substitua:

• CLUSTER_NAME: o nome do cluster.
• CONTROL_PLANE_LOCATION: o local do Compute Engine do plano de controle do cluster. Forneça uma região para clusters regionais ou uma zona para clusters zonais.

Se você não tiver certeza sobre o que inserir no nome ou local do cluster, 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 um comando kubectl nele, mas o comando kubectl atingiu o tempo limite, vai aparecer um erro semelhante a este:

• 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 ele:

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=CONTROL_PLANE_LOCATION \
       --project=PROJECT_ID
   

   Substitua:

   • CLUSTER_NAME: o nome do cluster.
   • CONTROL_PLANE_LOCATION: o local do Compute Engine do plano de controle do cluster. Forneça uma região para clusters regionais ou uma zona para clusters zonais.
   • PROJECT_ID: o ID do projeto em que o cluster foi criado.

3. Se você tiver ativado as redes autorizadas no cluster, 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=CONTROL_PLANE_LOCATION \
       --project=PROJECT_ID \
       --format "flattened(controlPlaneEndpointsConfig.ipEndpointsConfig.authorizedNetwork
   sConfig.cidrBlocks[])"
   

   Se o IP de saída da máquina não estiver incluído na lista de redes autorizadas da saída do comando anterior, siga uma das etapas abaixo:

   • Se você estiver usando o console, siga as instruções em Não é possível acessar o plano de controle de um cluster sem endpoint externo.
   • Se você estiver se conectando pelo Cloud Shell, siga as instruções em Usar o Cloud Shell para acessar um cluster com o endpoint externo desativado.

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

Se os comandos kubectl retornarem um erro failed to negotiate an API version, verifique se o kubectl tem credenciais de autenticação:

gcloud auth application-default login

Problema: o comando kubectl logs, attach, exec ou port-forward parou de responder

Se os comandos kubectl logs, attach, exec ou port-forward pararem de responder, geralmente o servidor de API não consegue 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 comandos não vão funcionar. 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 serviço:

• SSH
• Proxy Konnectivity

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. O GKE também adiciona uma regra de firewall à rede do Compute Engine para permitir o acesso SSH do endereço IP do plano de controle a cada nó no cluster.

As seguintes configurações podem causar problemas na comunicação SSH:

• 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, confira 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, confira o comprimento da lista de ssh-keys. Veja os metadados do seu projeto executando o seguinte comando, incluindo opcionalmente a flag --project:

  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 resolver esse 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

Se o cluster usar o proxy Konnectivity, a saída será semelhante a esta:

NAME                 READY   UP-TO-DATE   AVAILABLE   AGE
konnectivity-agent   3/3     3            3           18d

Depois de verificar se você está usando o proxy do Konnectivity, confira se os agentes do Konnectivity têm o acesso necessário ao firewall e se as políticas de rede estão configuradas corretamente.

Permitir o acesso necessário ao firewall

Verifique se as regras de firewall da sua rede permitem o acesso às seguintes portas:

• Porta do plano de controle: na criação do cluster, os agentes do Konnectivity estabelecem conexões com o plano de controle na porta 8132. Quando você executa um comando kubectl, o servidor da API usa essa conexão para se comunicar com o cluster. 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. Se você tiver regras que negam o acesso de saída, talvez seja necessário modificar as regras ou criar exceções.

• Porta kubelet: como os agentes do Konnectivity são pods do sistema implantados nos nós do cluster, verifique se as regras de firewall permitem os seguintes tipos de tráfego:

  • Tráfego de entrada para suas cargas de trabalho na porta 10250 dos intervalos de pods.
  • Tráfego de saída dos seus intervalos de pods.

  Se as regras de firewall não permitirem esse tipo de tráfego, modifique as regras.

Ajustar a política de rede

O proxy do Konnectivity pode ter problemas se a política de rede do cluster fizer o seguinte:

• Bloqueia a entrada do namespace kube-system para o namespace workload.
• Bloqueia a saída para o plano de controle do cluster na porta 8132

Quando a entrada é bloqueada pela política de rede dos pods de carga de trabalho, os registros do konnectivity-agent incluem uma mensagem de erro semelhante a esta:

"error dialing backend" error="dial tcp POD_IP_ADDRESS:PORT: i/o timeout"

Na mensagem de erro, POD_IP_ADDRESS é o endereço IP do pod da carga de trabalho.

Quando a saída é bloqueada pela política de rede, os registros konnectivity-agent incluem uma mensagem de erro semelhante a esta:

"cannot connect once" err="rpc error: code = Unavailable desc = connection error: desc = "transport: Error while dialing: dial tcp CP_IP_ADDRESS:8132: i/o timeout

No erro, CP_IP_ADDRESS é o endereço IP do plano de controle do cluster.

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 as regras de entrada ou saída da política de rede são 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 o problema com a política de entrada, adicione o seguinte ao campo spec.ingress das políticas de rede:

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

Para resolver o problema com a política de saída, adicione o seguinte ao campo spec.egress das políticas de rede:

egress:
- to:
  - ipBlock:
      cidr: CP_IP_ADDRESS/32
  ports:
  - protocol: TCP
    port: 8132

Se a política de rede usar uma combinação de regras de entrada e saída, ajuste as duas.

Ajustar o agente de mascaramento de IP

O plano de controle do cluster aceita o tráfego dos agentes do Konnectivity se o endereço IP de origem estiver nos intervalos de endereços IP do pod. Se você modificar a configuração do ip-masq-agent para mascarar o endereço IP de origem do tráfego para o plano de controle do cluster, os agentes do Konnectivity poderão apresentar erros de conectividade.

Para resolver o problema e garantir que o tráfego dos agentes do Konnectivity para o plano de controle do cluster não seja mascarado para o endereço IP do nó, adicione o endereço IP do plano de controle à lista nonMasqueradeCIDRs no ip-masq-agent ConfigMap:

nonMasqueradeCIDRs:
- CONTROL_PLANE_IP_ADDRESS/32

Para mais informações sobre essa configuração, consulte Agente de mascaramento de IP.

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.