Resolver problemas com a ferramenta de linha de comando kubectl

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 com 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 conselhos.

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 Kubernetes Engine a partir 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 alterar 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 à seguinte 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 erro a seguir ocorre se os clientes kubectl ou 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 \
    --region=COMPUTE_REGION

    Substitua:

    • CLUSTER_NAME: o nome do cluster.
    • COMPUTE_REGION: a região do Compute Engine do cluster; Para clusters zonais, use --zone=COMPUTE_ZONE.

Erro: o plug-in auth do gcp foi descontinuado. Use o gcloud.

Você pode receber 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 \
    --region=COMPUTE_REGION

    Substitua:

    • CLUSTER_NAME: o nome do cluster.
    • COMPUTE_REGION: a região do Compute Engine do cluster; Para clusters zonais, use --zone=COMPUTE_ZONE.

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 a modificação da variável de ambiente $PATH, digite 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 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

Substitua CLUSTER_NAME pelo nome do cluster. Se você não tiver certeza sobre o que inserir no nome 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 expirou, 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 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: o ID do projeto em que o cluster foi criado.

  3. Se você ativou 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=COMPUTE_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 destas etapas:

Erro: os comandos kubectl retornam falha ao negociar 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 para 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 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 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:

Resolver problemas de SSH

Se você estiver usando SSH, o GKE vai salvar um arquivo de chave pública SSH nos metadata do projeto do Compute Engine. Todas as VMs do Compute Engine que usam imagens fornecidas pelo Google verificam regularmente os metadados comuns do projeto e os metadados da instância em busca de 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.

As configurações a seguir podem causar problemas com a 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, 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 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. 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 a chaves SSH 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 da Konnectivity, verifique se os agentes da Konnectivity têm o acesso de firewall necessário e se as políticas de rede estão configuradas corretamente.

Permitir 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 da 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 de conectividade 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 as cargas de trabalho na porta 10250 dos intervalos de pods.
    • Tráfego de saída dos intervalos de pod.

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

Ajustar a política de rede

Se a política de rede do cluster bloquear a entrada do namespace kube-system para o namespace workload, isso poderá causar problemas com o proxy da Konnectivity.

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

A seguir

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