Como fazer a autenticação no servidor da API Kubernetes

Autopilot Padrão

Nesta página, descrevemos os métodos de autenticação compatíveis ao se conectar ao servidor da API Kubernetes no Google Kubernetes Engine (GKE).

Para informações sobre como autenticar cargas de trabalho do Kubernetes nas APIs do Google Cloud, consulte a federação de identidade da carga de trabalho do GKE.

Visão geral

Há vários métodos de autenticação em um servidor da API Kubernetes. No GKE, a autenticação OAuth é recomendada para a autenticação de cluster e é configurada automaticamente para você.

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.
Observação: para instalações atuais da CLI gcloud, defina as propriedades compute/region e compute/zone. Quando você define os locais padrão, você evita erros como este na gcloud CLI: One of [--zone, --region] must be supplied: Please specify location.

Como autenticar usuários

O GKE gerencia a autenticação do usuário final para você por meio da Google Cloud CLI. A gcloud CLI autentica os usuários no Google Cloud, define a configuração do Kubernetes, concede ao cluster um token de acesso OAuth e mantém o token de acesso atualizado.

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 para essas contas precisam incluir o escopo do OAuth userinfo.email para realizar a autenticação.

Quando você usa a gcloud para configurar o seu ambiente kubeconfig para um cluster novo ou atual, gcloud concede a 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.

É possível autorizar ações no cluster usando o gerenciamento de identidade e acesso (IAM) ou o controle de acesso baseado em papéis (RBAC, na sigla em inglês) do Kubernetes.

Como autenticar com o OAuth

Para autenticar no cluster usando o método OAuth, faça o seguinte:

Faça login na gcloud CLI com suas credenciais. Isso abre um navegador da Web para concluir o processo de autenticação para o Google Cloud:
```
gcloud auth login
```
Cuidado: não faça isso em uma VM do Compute Engine. Use uma conta de serviço para autenticação. Para mais detalhes, consulte a seção Serviço no Google Cloud.

Recupere as credenciais do Kubernetes para um cluster específico:

gcloud container clusters get-credentials CLUSTER_NAME \
    --zone=COMPUTE_ZONE

Verifique se você está autenticado:
```
kubectl cluster-info
```

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 autenticar aplicativos

Também é possível autenticar no servidor de API de um aplicativo em um pod sem a interação do usuário, como de um script no seu pipeline de CI/CD. A maneira como você faz isso depende do ambiente em que o serviço está sendo executado.

Aplicativo no mesmo cluster

Se o aplicativo estiver em execução no mesmo cluster do GKE, use uma conta de serviço do Kubernetes para autenticar.

Crie uma conta de serviço do Kubernetes e anexe-a ao pod. Se o pod já tiver uma conta de serviço do Kubernetes ou se você quiser usar a conta de serviço padrão do namespace, pule esta etapa.
Use o RBAC do Kubernetes para conceder à conta de serviço do Kubernetes as permissões necessárias para seu aplicativo.

O exemplo a seguir concede permissões view a recursos no namespace prod para uma conta de serviço chamada cicd no namespace cicd-ns:
```
kubectl create rolebinding cicd-secret-viewer \
    --namespace=prod \
    --clusterrole=view \
    --serviceaccount=cicd-ns:cicd
```
No ambiente de execução, quando seu aplicativo envia uma solicitação da API Kubernetes, o servidor da API autentica as credenciais da conta de serviço.

Aplicativos no Google Cloud

Se o aplicativo for executado no Google Cloud, mas fora do cluster de destino, por exemplo, uma VM do Compute Engine ou outro cluster do GKE, faça a autenticação no servidor de API usando as credenciais da conta de serviço do IAM disponíveis em o meio ambiente.

Atribua uma conta de serviço do IAM ao ambiente. Se o aplicativo estiver em execução em uma VM do Compute Engine, atribua uma conta de serviço do IAM à instância. Se o aplicativo estiver em execução em um cluster diferente do GKE, use a federação de identidade da carga de trabalho do GKE para configurar a execução do pod como uma conta de serviço do IAM.

Os exemplos a seguir usam ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com como a conta de serviço do IAM.
Conceda ao cluster acesso à conta de serviço do Google.

O exemplo a seguir concede o papel roles/container.developer do IAM, que fornece acesso a objetos da API Kubernetes dentro de clusters:
```
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/container.developer
```
Se preferir, use o RBAC para conceder à conta de serviço do IAM acesso ao cluster. Execute o comando kubectl create rolebinding em Aplicativos no mesmo cluster e use --user=ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com em vez da sinalização --service-account.
Recupere as credenciais do cluster:
```
gcloud container clusters get-credentials CLUSTER_NAME \
    --zone=COMPUTE_ZONE
```
Seu aplicativo é autenticado automaticamente usando a conta de serviço do IAM definida no ambiente.

Aplicativos em outros ambientes

Se o aplicativo estiver fazendo a autenticação de um ambiente fora do Google Cloud, não será possível acessar as credenciais da conta de serviço do IAM gerenciada. Para recuperar credenciais de cluster, você precisará criar uma conta de serviço do Google e fazer o download da chave. Na sequência, use a chave no ambiente de execução do serviço para recuperar credenciais de cluster com a gcloud CLI.

Crie uma conta de serviço do IAM para seu aplicativo. Se você já tem uma conta de serviço do IAM, pule esta etapa.

O comando a seguir cria uma conta de serviço do IAM chamada ci-cd-pipeline:
```
gcloud iam service-accounts create ci-cd-pipeline
```
Conceda à conta de serviço do Google o acesso ao cluster.

O comando a seguir concede o papel do IAM roles/container.developer à conta de serviço do IAM ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com:
```
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/container.developer
```
Também é possível usar o RBAC para conceder à conta de serviço do IAM acesso ao cluster. Execute o comando kubectl create rolebinding em Aplicativos no mesmo cluster e use --user=ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com em vez da sinalização --service-account.
Crie e faça o download de uma chave para sua conta de serviço do Google. Disponibilize-a para seu aplicativo no momento da execução:
```
gcloud iam service-accounts keys create gsa-key.json \
    --iam-account=ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com
```

No ambiente de execução do serviço, autentique-se na gcloud CLI usando a chave de conta de serviço do Google:

gcloud auth activate-service-account ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com \
    --key-file=gsa-key.json

Use a gcloud CLI para recuperar as credenciais do cluster:

gcloud config set project PROJECT_ID
gcloud container clusters get-credentials CLUSTER_NAME \
    --zone=COMPUTE_ZONE

Ambientes sem gcloud

É recomendável usar a gcloud CLI para recuperar credenciais de cluster. Esse é um método resiliente a eventos de cluster, como um plano de controle de rotação de IP ou de rotação de credenciais. No entanto, se não for possível instalar a gcloud CLI no ambiente, ainda será possível criar um arquivo kubeconfig estático para a autenticação no cluster:

Crie uma conta de serviço do IAM para seu aplicativo. Se você já tem uma conta de serviço do IAM, pule esta etapa.

O comando a seguir cria uma conta de serviço do IAM chamada ci-cd-pipeline:
```
gcloud iam service-accounts create ci-cd-pipeline
```
Conceda à conta de serviço do Google o acesso ao cluster.

O comando a seguir concede o papel do IAM roles/container.developer à conta de serviço do IAM ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com:
```
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/container.developer
```
Também é possível criar um papel de IAM personalizado para um controle refinado sobre as permissões que você concede.
Crie e faça o download de uma chave para sua conta de serviço do Google.

No exemplo a seguir, o arquivo de chave é denominado gsa-key.json:
```
gcloud iam service-accounts keys create gsa-key.json \
    --iam-account=ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com
```

Consiga os valores endpoint e clusterCaCertificate para seu cluster:

gcloud container clusters describe CLUSTER_NAME \
    --zone=COMPUTE_ZONE \
     --format="value(endpoint)"

gcloud container clusters describe CLUSTER_NAME \
    --zone=COMPUTE_ZONE \
    --format="value(masterAuth.clusterCaCertificate)"

Crie um arquivo kubeconfig.yaml contendo o seguinte:

apiVersion: v1
kind: Config
clusters:
- name: CLUSTER_NAME
  cluster:
    server: https://endpoint
    certificate-authority-data: masterAuth.clusterCaCertificate
users:
- name: ci-cd-pipeline-gsa
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1beta1
      args:
      - --use_application_default_credentials
      command: gke-gcloud-auth-plugin
      installHint: Install gke-gcloud-auth-plugin for kubectl by following
        https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl#install_plugin
      provideClusterInfo: true
contexts:
- context:
    cluster: CLUSTER_NAME
    user: ci-cd-pipeline-gsa
  name: CLUSTER_NAME-ci-cd
current-context: CLUSTER_NAME-ci-cd

Substitua:

CLUSTER_NAME: o nome do cluster.
endpoint: o valor que você recebeu para endpoint na etapa anterior.
masterAuth.clusterCaCertificate: o valor que você recebeu para clusterCaCertificate na etapa anterior. Não é necessário decodificar o certificado codificado em base64.

Implante kubeconfig.yaml e gsa-key.json junto com o serviço no ambiente. No ambiente de execução do serviço, defina estas variáveis de ambiente:
```
export KUBECONFIG=path/to/kubeconfig.yaml
export GOOGLE_APPLICATION_CREDENTIALS=path/to/gsa-key.json
```
Agora seu aplicativo pode enviar solicitações para a API Kubernetes e será autenticado como a conta de serviço do IAM.

Métodos de autenticação legados

Antes da integração OAuth com o GKE, o certificado X.509 pré-provisionado ou uma senha estática eram os únicos métodos de autenticação disponíveis, mas não são mais recomendados e devem ser desativados. Esses métodos apresentam uma superfície mais ampla de ataque para comprometimento de cluster e são desativados por padrão em clusters que executam o GKE versão 1.12 e posterior. Se você usa métodos de autenticação legados, recomendamos desativá-los.

Quando ativados, um usuário com a permissão container.clusters.getCredentials pode recuperar o certificado do cliente e a senha estática. Os papéis roles/container.admin, roles/owner e roles/editor têm essa permissão. Portanto, use-os com sabedoria. Leia mais sobre os papéis do IAM no GKE.

Como desativar a autenticação com uma senha estática

Uma senha estática é uma combinação de nome de usuário e senha que o servidor da API valida. No GKE, esse método de autenticação é chamado de autenticação básica.

Para atualizar um cluster atual e remover a senha estática:

gcloud container clusters update CLUSTER_NAME --no-enable-basic-auth

Como desativar a autenticação com um certificado do cliente

Com a autenticação de certificado, um cliente apresenta um certificado que o servidor de API verifica com a autoridade de certificação especificada. No GKE, a autoridade de certificação (CA) raiz do cluster assina os certificados do cliente.

A autenticação de certificado do cliente tem implicações na autorização para o servidor da API Kubernetes. Se a autorização legada do Controle de acesso baseado em atributos (ABAC, na sigla em inglês) estiver ativada no cluster, por padrão, os certificados do cliente poderão autenticar e executar qualquer ação no servidor da API. Por outro lado, com o controle de acesso baseado em papéis (RBAC, na sigla em inglês) ativado, os certificados do cliente precisam receber autorização específica para os recursos do Kubernetes.

Para criar um cluster sem gerar um certificado de cliente, use a sinalização --no-issue-client-certificate:

gcloud container clusters create CLUSTER_NAME \
    --no-issue-client-certificate

Atualmente, não há como remover um certificado de cliente de um cluster existente. Para parar de usar a autenticação de certificado do cliente em um cluster atual, verifique se o RBAC está ativado no cluster e se o certificado do cliente não tem autorização no cluster.

A seguir

Saiba mais sobre a Autenticação do Google Cloud.
Saiba mais sobre Controle de acesso no GKE.
Saiba mais sobre as contas de serviço do Google.
Saiba mais sobre a federação de identidade da carga de trabalho do GKE.
Saiba mais sobre Como aumentar a proteção do seu cluster.