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

Prepare-se para a tarefa tomando as seguintes medidas:

  • Verifique se você ativou a API Google Kubernetes Engine.
  • Ativar a API Google Kubernetes Engine
  • Verifique se o SDK do Cloud está instalado.
  • 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 concede à kubectl as mesmas credenciais usadas pela própria . 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.

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

gcloud container clusters get-credentials [CLUSTER_NAME]

em que [CLUSTER_NAME] é o nome do cluster.

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

  1. Suas credenciais, como mostrado em gcloud auth list.
  2. Suas credenciais padrão do aplicativo, se configuradas.

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ê já 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 mudar o contexto atual para my-cluster, você teria que executar o seguinte comando:

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 é . Você quer implantar um aplicativo em my-new-cluster, mas não quer alterar o contexto atual

Para implantar o aplicativo em my-new-cluster, você teria que executar o seguinte comando:

kubectl run my-app --image gcr.io/my-bucket/my-app:1.0 --cluster my-new-cluster

A seguir