Instalar o kubectl e configurar o acesso ao cluster

Esta página fornece instruções para instalar a ferramenta de linha de comando kubectl, usada para gerenciar e acessar clusters do Google Kubernetes Engine (GKE). A kubectl configuração é necessária se você executar vários clusters no 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. Para saber mais sobre papéis comuns e tarefas de exemplo referenciados na Google Cloud documentação, consulte Funções e tarefas comuns do usuário do GKE e tarefas.

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 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 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 CLI gcloud.

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

Também é possível configurar kubectl usando as tarefas a seguir:

  • Escolha o cluster com que 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 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. 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 Google Cloud console 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:

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ê ativou o endpoint externo)
  • O endereço IP interno
  • O endereço DNS (se o acesso IP estiver desativado)

Para gerar uma entrada kubeconfig para um cluster, execute um dos seguintes comandos:

  • Para usar o endpoint canônico por padrão, execute o gcloud container clusters get-credentials comando. Esse comando usa o endereço IP no campo endpoint da configuração do cluster.

  • Para usar o endpoint baseado em IP interno do cluster, execute o seguinte comando:

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

    Substitua CLUSTER_NAME pelo nome do cluster.

  • Para usar o endpoint baseado em DNS do cluster, execute o seguinte comando:

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

O conteúdo do arquivo de configuração gerado varia de acordo com o endpoint usado para se conectar ao cluster:

  • Endpoint baseado em DNS: como o serviço do Google Front End (GFE) que hospeda o endpoint baseado em DNS apresenta o certificado assinado por uma autoridade de certificação (CA) pública, a entrada kubeconfig omite o certificate-authority-data campo.
  • Endpoints baseados em IP: como o servidor da API apresenta um certificado que é assinado pela CA raiz do cluster, a entrada kubeconfig inclui o campo certificate-authority-data. Esse campo contém o certificado público codificado em Base64 da CA raiz do cluster, que os clientes podem usar para validar o certificado do servidor da API.

Para mais informações sobre esses certificados, consulte Segurança de transporte para conexões de plano de controle.

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 recebem US $300 em créditos para executar, testar e implantar cargas de trabalho.

Faça uma avaliação sem custos do GKE