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

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 mais informações sobre como autenticar cargas de trabalho do Kubernetes nas APIs do Google Cloud, consulte Identidade da carga de trabalho.

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:

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 para clusters zonais ou uma região para clusters regionais ou de Autopilot.

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 de Autopilot ou 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

Como autenticar usuários

O GKE gerencia a autenticação do usuário final para você por meio da ferramenta de linha de comando gcloud. A ferramenta gcloud 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. É possível controlar o acesso ao cluster usando o gerenciamento de identidade e acesso (IAM) ou ao Controle de acesso baseado em papéis (RBAC, na sigla em inglês) do Kubernetes.

Antes da integração do GKE com o OAuth, o certificado x509 pré-provisionado ou a senha estática eram os únicos métodos de autenticação disponíveis. Contudo, esses métodos não são recomendados e estão desativados por padrão nos novos clusters das versões 1.12 e posteriores. Se você estiver usando métodos de autenticação legados, recomendamos migrar esses métodos.

Como autenticar com o OAuth

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

  1. Faça login na ferramenta gcloud com suas credenciais. Isso abrirá um navegador da Web para concluir o processo de autenticação no Google Cloud:

    gcloud auth login
    
  2. Recupere as credenciais do Kubernetes para um cluster específico:

    gcloud container clusters get-credentials CLUSTER_NAME \
        --zone=COMPUTE_ZONE
    
  3. Agora você está autenticado. Verifique os resultados usando o seguinte comando kubectl:

    kubectl cluster-info
    

Serviços de autenticação

Às vezes, pode ser necessário estar autenticado no servidor de API de um cluster do GKE a partir de um serviço sem interação do usuário, como um script de pipeline de CI/CD. A maneira como você faz isso depende do ambiente em que o serviço está sendo executado.

Serviço no mesmo cluster do GKE

Se o serviço estiver em execução em um pod dentro do cluster do GKE ao qual você quer se conectar, use uma conta de serviço do Kubernetes para fazer a autenticação.

  1. 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, pule esta etapa.

    Em nosso exemplo, usamos uma conta de serviço do Kubernetes chamada cicd no namespace cicd-ns.

  2. Conceda as permissões corretas à conta de serviço do Kubernetes usando o RBAC do Kubernetes.

    Em nosso exemplo, concedemos o papel edit em um namespace prod. No entanto, na prática, conceda um papel que atenda às suas necessidades.

    kubectl create rolebinding cicd \
        --clusterrole=edit \
        --serviceaccount=cicd-ns:cicd \
        --namespace=prod
    
  3. No momento da execução, quando o serviço invoca kubectl, ele recebe automaticamente as credenciais configuradas.

Serviço no Google Cloud

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

  1. Atribua uma conta de serviço do Google ao seu ambiente do Compute Engine. Se o serviço estiver em execução dentro de uma VM do Compute Engine, atribua uma conta de serviço do Google à instância. Se o serviço estiver sendo executado em um cluster do GKE, use a Identidade da carga de trabalho a fim e configurar o pod para ser executado como uma conta de serviço do Google.

    Em nosso exemplo, usamos ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com como a conta de serviço do Google.

  2. Conceda ao cluster desejado o acesso à conta de serviço do Google.

    Em nosso exemplo, concedemos 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
    
  3. Recupere as credenciais do cluster:

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

    Seu serviço será autenticado automaticamente usando a conta de serviço do Google definida no ambiente.

Serviço em outros ambientes

Se o serviço estiver sendo autenticado em um ambiente fora do Google Cloud, ele não terá acesso às credenciais da conta de serviço do Google 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 ferramenta gcloud.

  1. Crie uma conta de serviço do Google para seu serviço. Se você já tiver uma conta de serviço do Google, poderá pular esta etapa.

    Em nosso exemplo, criamos uma conta de serviço chamada ci-cd-pipeline:

    gcloud iam service-accounts create ci-cd-pipeline
    
  2. Conceda à conta de serviço do Google o acesso ao cluster.

    Em nosso exemplo, usamos ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com como a conta de serviço do Google e concedemos 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
    

    Concedemos acesso usando o IAM. Também é possível conceder esse acesso por meio do RBAC do Kubernetes para ter um controle mais preciso.

  3. Crie e faça o download de uma chave para sua conta de serviço do Google. Disponibilize a chave para o serviço no ambiente de execução:

    gcloud iam service-accounts keys create gsa-key.json \
        --iam-account=ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com
    
  4. No ambiente de execução do serviço, autentique-se na ferramenta gcloud 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
    

    Isso exige que a ferramenta gcloud seja instalada no seu ambiente. Para saber como instalar a ferramenta gcloud, consulte Como instalar o SDK do Cloud. Se não for possível instalar a ferramenta gcloud no seu ambiente, consulte a seção Ambientes sem gcloud.

  5. Use a ferramenta gcloud 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 ferramenta gcloud 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 ferramenta gcloud no ambiente, ainda será possível criar um arquivo kubeconfig estático para a autenticação no cluster:

  1. Crie uma conta de serviço do Google para seu serviço. Se você já tiver uma conta de serviço do Google, poderá pular esta etapa.

    Em nosso exemplo, criamos uma conta de serviço chamada ci-cd-pipeline:

    gcloud iam service-accounts create ci-cd-pipeline
    
  2. Conceda à conta de serviço do Google o acesso ao cluster.

    Em nosso exemplo, usamos ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com como a conta de serviço do Google e concedemos 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
    

    Concedemos acesso usando o IAM. Também é possível conceder esse acesso por meio do RBAC do Kubernetes para ter um controle mais preciso.

  3. Crie e faça o download de uma chave para sua conta de serviço do Google.

    Em nosso exemplo, 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
    
  4. 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)"
    
  5. 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:
        auth-provider:
          name: gcp
    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.
  6. 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
    
  7. Seu serviço agora pode invocar kubectl e será autenticado como a conta de serviço do Google.

Métodos de autenticação legados

Antes da integração do GKE com o OAuth, um certificado x509 exclusivamente gerado ou uma senha estática eram os únicos métodos de autenticação disponíveis, mas agora não são recomendados e devem ser desativados. Esses métodos apresentam uma superfície mais ampla de ataque para comprometimento de cluster e foram desativados por padrão desde a versão 1.12 do GKE. Se você estiver usando métodos de autenticação legados, recomendamos desativá-los. A autenticação com uma senha estática está obsoleta e foi removida desde a versão 1.19 do GKE.

Se ativados, o certificado do cliente e a senha estática podem ser recuperados por um usuário com a permissão container.clusters.getCredentials. 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, os certificados do cliente são assinados pela autoridade de certificação (CA, na sigla em inglês) raiz do cluster.

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