Como configurar o acesso a clusters para a kubectl

Nesta página, você aprenderá a configurar o acesso a clusters para a ferramenta de linha de comando kubectl no Google Kubernetes Engine.

Visão geral

Se você executar vários clusters no projeto do Google Cloud, precisará escolher com qual cluster a kubectl (em inglês) se comunica. Para definir um cluster padrão para a kubectl, defina o contexto atual no arquivo kubeconfig do Kubernetes. Além disso, é possível executar comandos kubectl em um cluster específico usando a sinalização --cluster.

Nas seções a seguir, você aprenderá como kubeconfig funciona, como definir um cluster padrão para kubectl e como executar comandos kubectl individuais em um cluster específico.

Antes de começar

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

Defina as configurações padrão da gcloud usando um dos métodos a seguir:

  • Use gcloud init se quiser orientações para definir os padrões.
  • Use gcloud config para definir individualmente a região, a zona e o ID do projeto.

Como usar o gcloud init

Se você receber o erro One of [--zone, --region] must be supplied: Please specify location, conclua esta seção.

  1. Execute gcloud init e siga as instruções:

    gcloud init

    Se você estiver usando SSH em um servidor remoto, utilize a sinalização --console-only para impedir que o comando inicie um navegador:

    gcloud init --console-only
  2. Siga as instruções para autorizar a gcloud a usar sua conta do Google Cloud.
  3. Crie uma nova configuração ou selecione uma atual.
  4. Escolha um projeto do Google Cloud.
  5. Escolha uma zona padrão do Compute Engine.

Como usar o gcloud config

  • Defina o ID do projeto padrão:
    gcloud config set project project-id
  • Se você estiver trabalhando com clusters zonais, defina a zona do Compute padrão:
    gcloud config set compute/zone compute-zone
  • Se você estiver trabalhando com clusters regionais, defina a região do Compute padrão:
    gcloud config set compute/region compute-region
  • Atualize gcloud para a versão mais recente:
    gcloud components update

Arquivo de configuração do Kubernetes

O Kubernetes usa um arquivo YAML chamado kubeconfig (em inglês) para armazenar informações de autenticação de cluster para kubectl. kubeconfig contém uma lista de contextos para os quais a kubectl se refere ao executar comandos. Por padrão, o arquivo é salvo em $HOME/.kube/config.

Um contexto é um grupo de parâmetros de acesso. Cada contexto contém um cluster do Kubernetes, um usuário e um namespace. 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, uma entrada é adicionada automaticamente a kubeconfig em seu ambiente, e o contexto atual muda para esse cluster:

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

Ao criar um cluster usando o Console do Google Cloud ou a gcloud de um computador diferente, a kubeconfig do ambiente não é atualizada. Além disso, se um membro de equipe do projeto usa gcloud para criar um cluster a partir do próprio computador, a kubeconfig dele é atualizada, mas a sua não. Siga as instruções abaixo para adicionar esses clusters à sua kubeconfig local.

Sobre o endpoint de cluster

Todos os clusters têm um endpoint canônico. O endpoint é o endereço IP do servidor da API Kubernetes que a kubectl e outros serviços usam para se comunicar com o mestre do cluster. O endpoint é exibido no Console do Cloud tanto no campo Endpoint da guia "Detalhes" do cluster quanto na saída de gcloud container clusters describe no campo endpoint.

Ao executar gcloud container clusters get-credentials, o comando consegue o endpoint de cluster como parte da atualização de kubeconfig.

Os clusters particulares têm dois valores de endpoint exclusivos: privateEndpoint, que é um endereço IP interno, e publicEndpoint, que é um externo. A execução de get-credentials em um cluster particular define o endereço IP externo como o endpoint por padrão. Se você preferir usar o IP interno como o endpoint, consulte Como gerar uma entrada kubeconfig usando um endereço IP interno de um cluster particular.

Sobre a autenticação para kubectl

Todos os clusters do GKE são configurados para aceitar identidades de usuário e de conta de serviço do Google Cloud. Para isso, eles validam as credenciais apresentadas pela kubectl e recuperam o endereço de e-mail associado à identidade de conta de serviço ou usuário. Como resultado, as credenciais dessas contas precisam incluir o escopo userinfo.email do OAuth para realizar a autenticação com êxito.

Quando você usa a gcloud para configurar a kubeconfig do seu ambiente para um cluster novo ou atual, a gcloud concede à kubectl as mesmas credenciais usadas pela própria gcloud. Por exemplo, se você usar gcloud auth login, suas credenciais pessoais serão fornecidas para a kubectl, incluindo o escopo userinfo.email. Com isso, o cluster do GKE pode autenticar o cliente da kubectl.

Outra alternativa é configurar a kubectl para usar as credenciais de uma conta de serviço do Google Cloud durante a execução em uma instância do Compute Engine. No entanto, o escopo userinfo.email não é incluído por padrão nas credenciais criadas por instâncias do Compute Engine. Portanto, você precisa adicionar esse escopo explicitamente. Isso pode ser feito usando a sinalização --scopes quando a instância do Compute Engine é criada.

Depois que as contas de serviço do Google Cloud e os usuários forem autenticados, eles também precisarão estar autorizados a executar qualquer ação em um cluster do GKE. Para mais informações sobre como configurar a autorização, consulte Controle de acesso baseado em papéis.

Para informações sobre os métodos de autenticação compatíveis ao se conectar ao servidor da API Kubernetes, consulte Como autenticar no servidor da API Kubernetes.

Como visualizar o contexto atual para kubectl

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

kubectl config current-context

Como visualizar 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á gerar uma entrada kubeconfig para o cluster.

Como gerar uma entrada kubeconfig

Para executar comandos kubectl em um cluster criado no Console do Cloud, em outro computador ou por outro membro do projeto, é necessário gerar uma entrada kubeconfig no ambiente.

Para gerar uma entrada kubeconfig, execute o comando a seguir:

gcloud container clusters get-credentials cluster-name

em que cluster-name é o nome do cluster.

Esse comando exige que você tenha a permissão container.clusters.get. O papel do Cloud IAM com menos privilégios que concede essa permissão é container.clusterViewer.

A entrada kubeconfig contém uma das opções abaixo:

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

Ao executar get-credentials, é possível especificar --internal-ip para gravar o endereço IP interno de um cluster particular na kubeconfig:

gcloud container clusters get-credentials --internal-ip cluster-name

Como configurar um cluster padrão para comandos kubectl

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

gcloud container clusters get-credentials

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 comando a seguir:

gcloud container clusters get-credentials my-cluster

Como executar comandos kubectl individuais em um cluster específico

Execute comandos kubectl individuais em um cluster específico transmitindo o nome do cluster conforme ele aparece na kubeconfig como o argumento para a sinalização --cluster.

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 gcr.io/my-bucket/my-app:1.0 --cluster my-new-cluster

A seguir