Instalar o kubectl e configurar o acesso ao cluster

Nesta página, você encontra instruções para instalar a ferramenta de linha de comando kubectl, que é usada para gerenciar e acessar clusters do Google Kubernetes Engine (GKE). A configuração de kubectl é necessária se você executar vários clusters em Google Cloud.

Você vai aprender a:

Esta página é destinada a administradores de TI, operadores e desenvolvedores que configuram, monitoram e gerenciam a infraestrutura em nuvem, incluindo o provisionamento e a configuração de recursos na nuvem. Para saber mais sobre papéis comuns e tarefas de exemplo referenciados na documentação do Google Cloud , consulte Tarefas e funções de usuário comuns do GKE.

Antes de ler esta página, você precisa ter familiaridade com o Kubernetes kubectl.

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 CLI do Google Cloud para essa tarefa, instale e inicialize a gcloud CLI. Se você instalou a CLI gcloud anteriormente, instale a versão mais recente executando o comando gcloud components update. Talvez as versões anteriores da CLI gcloud não sejam compatíveis com a execução dos comandos neste documento.

Instalar kubectl

É possível instalar kubectl usando a Google Cloud CLI 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 saída será assim:

    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 o plug-in 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 \
    --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.

  3. Verifique a configuração executando o comando a seguir:

    kubectl get namespaces

    O resultado será assim:

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

Para mais informações sobre esse plug-in, consulte o KEP do Kubernetes.

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.

Se quiser, configure o kubectl usando as seguintes tarefas:

  • Escolha o cluster com que a kubectl se comunica.
  • Defina o cluster padrão para kubectl definindo o contexto atual no arquivo kubeconfig.
  • Execute comandos kubectl em um cluster específico usando a flag --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 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 \
    --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.

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

Todos os clusters têm vários endereços de endpoint, cada um com características diferentes. Um desses endpoints serve como o endpoint canônico usado pelo kubectl e outros serviços para se comunicar com o plano de controle do cluster. O GKE seleciona automaticamente o endpoint com base na seguinte ordem:

  • O endereço IP externo (se você tiver ativado o endpoint externo)
  • O endereço IP interno
  • O endereço DNS (se o acesso por IP estiver desativado) Para usar o endpoint canônico por padrão, execute o comando get-credentials. Para ter mais controle sobre qual endpoint o kubectl usa, use a flag --internal-ip ou --dns-endpoint. Para atualizar o arquivo kubeconfig e usar o endereço IP interno, execute o seguinte comando:
gcloud container clusters get-credentials CLUSTER_NAME --internal-ip

Para atualizar o arquivo kubeconfig e usar o endereço DNS, execute o seguinte comando:

gcloud container clusters get-credentials CLUSTER_NAME --dns-endpoint

Substitua CLUSTER_NAME pelo nome do cluster.

Por padrão, a execução de get-credentials usa o endereço IP especificado no campo endpoint.

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

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 \
    --location=CONTROL_PLANE_LOCATION

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

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 sem custos do GKE