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 informações relacionadas, consulte os seguintes recursos:

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

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:

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 modificá-las 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.

Erro: os comandos kubectl falham com o erro "nenhum agente disponível"

Ao executar comandos kubectl que precisam se conectar do plano de controle do GKE a um pod, por exemplo, kubectl exec, kubectl logs ou kubectl port-forward, o comando pode falhar com mensagens de erro semelhantes a estas:

Error from server: error dialing backend: No agent available

failed to call webhook: Post "https://WEBHOOK_SERVICE.WEBHOOK_NAMESPACE.svc:PORT/PATH?timeout=10s": No agent available

v1beta1.metrics.k8s.io failed with: failing or missing response from https://NODE_IP:10250/apis/metrics.k8s.io/v1beta1: Get "https://NODE_IP:10250/apis/metrics.k8s.io/v1beta1": No agent available

Esses erros indicam um problema com o Konnectivity, o túnel de comunicação seguro entre o plano de controle do GKE e os nós do cluster. Em particular, isso significa que o konnectivity-server no plano de controle não pode se conectar a nenhum pod konnectivity-agent íntegro no namespace kube-system.

Para resolver esse problema, tente o seguinte:

  1. Verifique a integridade dos pods konnectivity-agent:

    1. Verifique se os pods konnectivity-agent estão em execução:

      kubectl get pods -n kube-system -l k8s-app=konnectivity-agent

      O resultado será assim:

      NAME                                   READY   STATUS    RESTARTS  AGE
konnectivity-agent-abc123def4-xsy1a    2/2     Running   0         31d
konnectivity-agent-abc123def4-yza2b    2/2     Running   0         31d
konnectivity-agent-abc123def4-zxb3c    2/2     Running   0         31d

      Revise o valor na coluna Status. Se os pods tiverem o status Running, analise os registros para problemas de conexão. Caso contrário, investigue por que os pods não estão em execução.

    2. Analise os registros para identificar problemas de conexão. Se os pods tiverem o status Running, verifique os registros para problemas de conexão. Como o comando kubectl logs depende do Konnectivity, use o Explorador de registros no consoleGoogle Cloud :

      1. No console do Google Cloud , acesse Análise de registros.

        Acessar o Explorador de registros

      2. No painel de consulta, insira o seguinte:

        resource.type="k8s_container"
resource.labels.cluster_name="CLUSTER_NAME"
resource.labels.namespace_name="kube-system"
labels."k8s-pod/k8s-app"="konnectivity-agent"
resource.labels.container_name="konnectivity-agent"

        Substitua CLUSTER_NAME pelo nome do cluster.

      3. Clique em Executar consulta.

      4. Verifique a saída. Ao analisar os registros konnectivity-agent, procure erros que indiquem por que o agente não consegue se conectar. Erros de autenticação ou permissão geralmente indicam um webhook mal configurado que bloqueia as revisões de token. Os erros "Connection refused" ou "timeout" geralmente significam que uma regra de firewall ou uma política de rede está bloqueando o tráfego para o plano de controle na porta TCP 8132 ou entre o agente do Konnectivity e outros nós. Erros de certificado sugerem que um firewall ou proxy está inspecionando e interferindo no tráfego TLS criptografado.

    3. Investigue por que os pods não estão em execução. Se os pods tiverem o status Pending ou outro estado não em execução, investigue a causa. O konnectivity-agent é executado como uma implantação, não como um DaemonSet. Como ele é executado como uma implantação, os pods do agente só precisam ser executados em um subconjunto de nós. No entanto, se esse subconjunto específico de nós estiver indisponível, todo o serviço poderá falhar.

      Confira algumas causas comuns de um pod não em execução:

      • Taints de nó personalizados que impedem a programação de um pod.
      • Recursos insuficientes do nó (CPU ou memória).
      • Políticas restritivas de autorização binária que bloqueiam imagens do sistema do GKE.

      Para mais detalhes sobre por que um pod específico não está em execução, use o comando kubectl describe:

      kubectl describe pod POD_NAME -n kube-system

      Substitua POD_NAME pelo nome do pod que não está em execução.

  2. Investigue seus webhooks de admissão para garantir que nenhum esteja bloqueando solicitações de API TokenReview. O konnectivity-agent depende de tokens de conta de serviço. Portanto, interferências nas revisões de tokens podem impedir que os agentes se conectem. Se um webhook for a causa, o Konnectivity não poderá se recuperar até que o webhook com falha seja removido ou corrigido.

  3. Verifique se as regras de firewall permitem o tráfego de saída TCP dos nós do GKE para o endereço IP do plano de controle na porta 8132. Essa conexão é necessária para que o konnectivity-agent alcance o serviço Konnectivity. Para mais informações, consulte Permitir o acesso necessário ao firewall.

  4. Verifique se não há regras de política de rede que restringem o tráfego essencial do Konnectivity. As regras de política de rede precisam permitir o tráfego intracluster (pod para pod) no namespace kube-system e o tráfego de saída dos pods konnectivity-agent para o plano de controle do GKE.

A seguir

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