Instalar o kubectl e configurar o acesso ao cluster

Nesta página, você aprende a instalar e configurar a ferramenta de linha de comando kubectl para interagir com seus clusters do Google Kubernetes Engine (GKE).

Visão geral

kubectl é uma ferramenta de linha de comando que pode ser usada para interagir com seus clusters do GKE. Para usar o kubectl com o GKE, instale e configure a ferramenta para se comunicar com os clusters. Também será necessário configurar kubectl se você executar vários clusters no Google Cloud.

Essa página mostra o seguinte:

Antes de começar

Antes de começar, verifique se você realizou as tarefas a seguir:

  • Ativar a API Google Kubernetes Engine.
    • Ativar a API Google Kubernetes Engine
  • Se você quiser usar a Google Cloud CLI para essa tarefa, instale e, em seguida, inicialize a CLI gcloud. Se você instalou a CLI gcloud anteriormente, instale a versão mais recente executando gcloud components update.

Instale o kubectl (em inglês)

É possível instalar kubectl usando a CLI do Google Cloud ou um gerenciador de pacotes externo, como apt ou yum.

gcloud

  1. Instale o componente kubectl:

    gcloud components install kubectl

  2. Para confirmar se kubectl está instalado, confira se ele tem a versão mais recente:

    kubectl version --client

apt

  1. Verifique se você tem o repositório cloud-sdk:

    grep -rhE ^deb /etc/apt/sources.list* | grep "cloud-sdk"

    O resultado será assim:

    deb  [signed-by=/usr/share/keyrings/cloud.google.gpg]  https://packages.cloud.google.com/apt cloud-sdk main

  2. Se o repositório cloud-sdk não estiver listado, instale a gcloud CLI.

  3. Instale o componente kubectl:

    apt-get update
apt-get install -y kubectl

  4. Para confirmar se kubectl está instalado, confira se ele tem a versão mais recente:

    kubectl version --client

yum

  1. Verifique se você tem o repositório cloud-sdk:

    yum repolist | grep "google-cloud-sdk"

    A resposta será semelhante a:

    google-cloud-sdk    Google Cloud SDK    2,205

  2. Instale o componente kubectl:

    yum install -y kubectl

  3. Para confirmar se kubectl está instalado, confira se ele tem a versão mais recente:

    kubectl version --client

Instalar os plug-ins necessários

kubectl e outros clientes do Kubernetes exigem um plug-in de autenticação, gke-gcloud-auth-plugin, que usa o framework de plug-ins de credenciais do Client-go para fornecer tokens de autenticação a fim de se comunicar com os clusters do GKE.

Antes do lançamento da versão 1.26 do Kubernetes, a CLI gcloud começará a exigir que o binário gke-gcloud-auth-plugin seja instalado. Se não estiver instalado, as instalações atuais de kubectl ou outros clientes personalizados do Kubernetes deixarão de funcionar.

Você precisa instalar esse plug-in para usar kubectl e outros clientes para interagir com o GKE. Os clientes existentes exibirão uma mensagem de erro se o plug-in não estiver instalado.

Antes de começar, verifique se o plug-in já está instalado:

gke-gcloud-auth-plugin --version

Se o resultado exibir informações de versão, pule esta seção.

É possível instalar o plug-in de autenticação usando a CLI gcloud ou um gerenciador de pacotes externo, como apt ou yum.

gcloud

Instale o binário gke-gcloud-auth-plugin:

  gcloud components install gke-gcloud-auth-plugin

apt

Instale o binário gke-gcloud-auth-plugin:

  apt-get install google-cloud-sdk-gke-gcloud-auth-plugin

yum

Instale o binário gke-gcloud-auth-plugin:

  yum install google-cloud-sdk-gke-gcloud-auth-plugin

Verifique a instalação binária gke-gcloud-auth-plugin:

  1. Verifique a versão binária gke-gcloud-auth-plugin:

    gke-gcloud-auth-plugin --version

  2. Atualize a configuração kubectl para usar o plug-in:

    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.

  3. Para verificar a configuração:

    kubectl get namespaces

    A saída será assim:

    NAME              STATUS   AGE
default           Active   51d
kube-node-lease   Active   51d
kube-public       Active   51d
kube-system       Active   51d

Para saber mais sobre por que esse plug-in é obrigatório, consulte o Kubernetes KEP.

Interagir com kubectl

O Kubernetes usa um arquivo YAML chamado kubeconfig (em inglês) para armazenar informações de autenticação de cluster para kubectl. Por padrão, o arquivo é salvo em $HOME/.kube/config.

kubeconfig contém um grupo de parâmetros de acesso chamados contextos. Cada contexto contém um cluster do Kubernetes, um usuário e um namespace padrão opcional. kubectl refere-se a contextos ao executar comandos.

Veja a seguir as tarefas que você pode concluir para configurar o kubectl:

  • Escolha com qual cluster a kubectl se comunica.
  • Defina um cluster padrão para kubectl definindo o contexto atual no arquivo kubeconfig.
  • Execute comandos kubectl em um cluster específico usando a sinalização --cluster.

Ver kubeconfig

Para ver a kubeconfig do ambiente, execute o seguinte comando:

kubectl config view

O comando retorna uma lista de todos os clusters que têm entradas kubeconfig. Se um cluster do GKE estiver listado, será possível executar comandos kubectl no seu ambiente atual. Caso contrário, você precisará armazenar as informações do cluster para o kubectl.

Ver o contexto atual para a kubectl

O contexto atual é o cluster que é o padrão para kubectl no momento. Todos os comandos kubectl são executados nesse cluster.

Quando você cria um cluster usando gcloud container clusters create-auto, uma entrada é adicionada automaticamente ao arquivo kubeconfig em seu ambiente, e o contexto atual muda para esse cluster. Exemplo:

gcloud container clusters create-auto my-cluster
Creating my-cluster...done
Fetching cluster endpoint and auth data.
kubeconfig entry generated for my-cluster

Para visualizar o contexto atual para kubectl, execute o seguinte comando:

kubectl config current-context

Armazenar informações do cluster para kubectl

Quando você cria um cluster usando o Console do Google Cloud ou a CLI gcloud em um computador diferente, o arquivo kubeconfig do seu ambiente não é atualizado. Além disso, se um membro de equipe do projeto usa a CLI gcloud para criar um cluster a partir do próprio computador, a kubeconfig dele é atualizada, mas a sua não. A entrada kubeconfig contém uma das opções abaixo:

Para gerar um contexto kubeconfig no seu ambiente, verifique se você tem a permissão container.clusters.get. O papel do IAM com privilégio mínimo que concede essa permissão é container.clusterViewer.

Para gerar um contexto kubeconfig para um cluster específico, execute o seguinte comando:

gcloud container clusters get-credentials CLUSTER_NAME \
    --region=CLUSTER_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.

Gerar uma entrada kubeconfig usando o endereço IP interno de um cluster particular

Todos os clusters têm um endpoint canônico. O endpoint expõe o servidor da API Kubernetes que o kubectl e outros serviços usam para se comunicar com o plano de controle do cluster.

Os clusters particulares têm dois endereços IP de endpoint separados: privateEndpoint, que é um endereço IP interno, e publicEndpoint, que é um endereço externo externo. O campo endpoint refere-se ao endereço IP externo, a menos que o acesso público ao endpoint esteja desativado. Nesse caso, o endereço IP particular será usado.

Para clusters particulares, se você preferir usar o IP interno como o endpoint, execute o seguinte comando:

gcloud container clusters get-credentials CLUSTER_NAME --internal-ip

Substitua CLUSTER_NAME pelo nome do cluster.

A execução de get-credentials usa o endereço IP especificado no campo endpoint por padrão.

Definir um cluster padrão para comandos da kubectl

Se você gerou uma entrada kubeconfig para clusters anteriormente, é possível alternar o contexto atual de kubectl para esse cluster executando o seguinte comando:

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.

Por exemplo, considere um projeto com dois clusters, my-cluster e my-new-cluster. O contexto atual é my-new-cluster, mas você quer executar todos os comandos kubectl em my-cluster. Para alternar o contexto atual de my-new-cluster para my-cluster, execute o seguinte comando:

gcloud container clusters get-credentials CLUSTER_NAME \
    --region=COMPUTE_REGION

Executar comandos individuais da kubectl em um cluster específico

É possível executar comandos kubectl individuais em um cluster específico usando --cluster=CLUSTER_NAME.

Por exemplo, considere um ambiente com dois clusters, my-cluster e my-new-cluster, em que o contexto atual é my-cluster. Você quer implantar um aplicativo em my-new-cluster, mas sem alterar o contexto atual. Para implantar o aplicativo em my-new-cluster sem alterar o contexto atual, execute o comando a seguir:

kubectl run my-app --image us-docker.pkg.dev/my-project/my-repo/my-app:1.0 --cluster my-new-cluster

Solução de problemas

Para resolver outros problemas, consulte Solução de problemas comuns.

Escopos de autenticação insuficientes

Ao executar gcloud container clusters get-credentials, você 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 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.

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

Se o erro a seguir for recebido ao tentar executar kubectl ou clientes personalizados que interagem com o GKE, instale o gke-gcloud-auth-plugin conforme descrito em Instruções de instalação. As mensagens de erro são semelhantes às seguintes:

  • Amostra de erro
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.
  • Amostra de erro
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

ERRO: panic: nenhum provedor de autenticação encontrado para o nome gcp

O erro no Auth Provider found for name "gcp" será recebido se os clientes kubectl ou personalizados do Kubernetes tiverem sido criados com o Kubernetes client-go versão 1.26 ou posterior, conforme descrito em Como funciona. Isso pode ser resolvido nas seguintes etapas:

  1. Instale gke-gcloud-auth-plugin conforme descrito em Instruções de instalação.

  2. Atualize para a versão mais recente da CLI gcloud usando 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.

AVISO: o plug-in auth do gcp está obsoleto. Use a gcloud

Você verá essa mensagem de aviso depois de instalar o gke-gcloud-auth-plugin e executar um comando kubectl em um cluster do GKE. Essa mensagem será exibida se a versão do cliente for anterior à 1.26.

Para instruir seu cliente a usar o plug-in de autenticação gke-gcloud-auth-plugin, faça o seguinte:

  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.

A seguir

Faça um teste

Se você começou a usar o Google Cloud agora, crie uma conta para avaliar o desempenho do GKE em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

Faça uma avaliação gratuita do GKE