Autenticar em APIs e serviços de cargas de trabalho da frota

Nesta página, mostramos como configurar seus aplicativos para autenticação nas APIs do Google Cloud, como a API Compute Engine ou a API AI Platform, usando a Federação de Identidade da Carga de Trabalho da frota.

O que é a federação de identidade da carga de trabalho da frota?

A Federação de identidade da carga de trabalho permite que as cargas de trabalho nos clusters sejam autenticadas no Google Cloud sem que você precise fazer o download, alternar manualmente e gerenciar credenciais. Em vez disso, as cargas de trabalho são autenticadas usando tokens de curta duração gerados pelo Google Cloud.

A federação de identidade da carga de trabalho para o GKE fornece um pool de identidade da carga de trabalho em todo o projeto, do qual os aplicativos em execução nos clusters do GKE recebem identidades. A federação de identidade da carga de trabalho da frota estende a federação de identidade da carga de trabalho para o GKE a todos os clusters de membros da frota, independentemente de estarem em projetos diferentes ou fora do Google Cloud. Os clusters registrados com a federação de identidade da carga de trabalho ativada na assinatura da frota recebem identidades usando um pool de identidades de carga de trabalho em toda a frota, que permite configurar a autenticação nas APIs do Google Cloud e em outros serviços em toda a frota, até mesmo em vários projetos.

O agente do Connect também pode usar a Federação de identidade da carga de trabalho da frota em alguns tipos de cluster para autenticação no Google como parte da associação da frota. Ela também é necessária para usar alguns recursos do GKE Enterprise que funcionam em vários projetos, como o Cloud Service Mesh.

Pools de federação de identidade da carga de trabalho e identidade idêntica

Com a federação de identidade da carga de trabalho da frota, cada aplicativo na frota recebe uma identidade federada distinta que pode ser usada para autenticação no Google Cloud e em outros serviços que você desenvolve. Os aplicativos recebem um identificador principal que o IAM pode reconhecer. Esse identificador usa a seguinte sintaxe:

PREFIX://iam.googleapis.com/projects/FLEET_PROJECT_NUMBER/locations/global/workloadIdentityPools/FLEET_PROJECT_ID.svc.id.goog/SELECTOR

Essa sintaxe tem os seguintes campos:

  • PREFIX: o principal ou principalSet do IAM, dependendo do recurso selecionado.
  • FLEET_PROJECT_ID.svc.id.goog: o pool de identidade da carga de trabalho da frota. Cada frota tem um único pool de identidade de carga de trabalho fixo criado para você.
  • FLEET_PROJECT_NUMBER: o número do projeto host da frota.
  • SELECTOR: o seletor de recursos. Para uma lista de seletores compatíveis, consulte Identificadores principais compatíveis.

A frota inteira compartilha um pool de identidade da carga de trabalho da frota. Assim, você pode conceder a aplicativos em qualquer lugar da frota, incluindo em outros projetos ou nuvens, acesso aos mesmos recursos sem precisar gerenciar esse acesso para cada cluster. Assim como outros recursos ativados para a frota, a Federação de identidade de carga de trabalho da frota depende do princípio da semelhança, em que objetos do Kubernetes com o mesmo nome e namespace em clusters diferentes são tratados como a mesma coisa.

Por exemplo, se você tiver um aplicativo com um back-end implantado em vários clusters na mesma frota e que precisa ser autenticado em uma API do Google Cloud, será fácil configurá-lo para que todas as cargas de trabalho no namespace backend possam acessar essa API. Para mais informações sobre como as frotas usam a semelhança, incluindo a identidade, consulte Como as frotas funcionam.

Depois de ativar a federação de identidade da carga de trabalho da frota, é possível fazer referência a principais na frota em políticas de permissão do IAM especificando o identificador principal correspondente. Por exemplo, você pode fazer referência a um ServiceAccount específico em um namespace específico do Kubernetes na sua política de permissão. Todos os aplicativos que usam essa conta de serviço podem acessar o recurso do Google Cloud a que a política de permissão do IAM se aplica.

Fluxo de credenciais

Para permitir que aplicativos em um namespace específico se autentiquem usando a federação de identidade da carga de trabalho da frota, faça o seguinte:

  1. Implante um ConfigMap nesse namespace com as seguintes informações:

    • O pool de identidade da carga de trabalho e o provedor de identidade do cluster.
    • O caminho em cada pod em que o Kubernetes monta um token da conta de serviço. Esse token é um JSON Web Token (JWT) assinado.

    Esse ConfigMap funciona como o arquivo de credenciais padrão do aplicativo (ADC) para cargas de trabalho.

  2. Crie uma política de permissão do IAM que conceda acesso a recursos específicos do Google Cloud ao identificador principal nos clusters, como uma conta de serviço no namespace.

  3. Verifique se a carga de trabalho no namespace tem as seguintes configurações na especificação do pod:

    • A variável de ambiente GOOGLE_APPLICATION_CREDENTIALS definida como o caminho de montagem do ConfigMap no pod.
    • Um volume projetado que contém o token da conta de serviço e o ConfigMap que você criou, montado no mesmo caminho especificado na variável de ambiente GOOGLE_APPLICATION_CREDENTIALS.
    • Uma montagem de volume no contêiner que faz referência ao volume projetado.

Quando a carga de trabalho faz uma chamada para a API do Google Cloud, as seguintes etapas acontecem:

  1. As bibliotecas de autenticação do Google Cloud usam credenciais padrão do aplicativo (ADC) para encontrar credenciais. O ADC verifica o caminho que você especificou na variável de ambiente GOOGLE_APPLICATION_CREDENTIALS para procurar um token de autenticação.
  2. A biblioteca de autenticação ADC usa os dados no ConfigMap para trocar o JWT da conta de serviço que você montou no pod por um token federado de curta duração do Serviço de token de segurança que faz referência ao identificador principal da carga de trabalho.
  3. O ADC inclui o token federado com a solicitação da API.
  4. A política de permissão do IAM autoriza o identificador principal a realizar a operação solicitada no recurso do Google Cloud.

Identificadores principais com suporte para a federação de identidade da carga de trabalho da frota

A tabela a seguir descreve os seletores que podem ser usados em políticas de permissão do IAM para referenciar principais em frotas:

Tipo de identificador principal Sintaxe
Todos os pods que usam uma conta de serviço específica do Kubernetes Selecione a conta de serviço pelo nome: 
principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/SERVICEACCOUNT

Substitua:

  • PROJECT_NUMBER: o número numérico do projeto. Para conseguir o número do projeto, consulte Identificar projetos.
  • PROJECT_ID: é seu ID do projeto no Google Cloud.
  • NAMESPACE: o namespace do Kubernetes.
  • SERVICEACCOUNT: nome da conta de serviço do Kubernetes.
Selecionar a ServiceAccount pelo UID: 
principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/kubernetes.serviceaccount.uid/SERVICEACCOUNT_UID

Substitua:

  • PROJECT_NUMBER: o número numérico do projeto. Para conseguir o número do projeto, consulte Identificar projetos.
  • PROJECT_ID: o ID do projeto da Flotta.
  • SERVICEACCOUNT_UID: o UID do objeto ServiceAccount no servidor da API.

Antes de começar

  • Verifique se você tem as seguintes ferramentas de linha de comando instaladas:

    • A versão mais recente da Google Cloud CLI, que inclui gcloud, a ferramenta de linha de comando para interagir com o Google Cloud.
    • kubectl

    Se você estiver usando o Cloud Shell como ambiente shell para interagir com o Google Cloud, essas ferramentas estarão instaladas.

  • Verifique se você inicializou a CLI gcloud para usar com seu projeto.

Prepare seus clusters

Antes que os aplicativos da sua frota recebam uma identidade federada, os clusters em que eles são executados precisam ser registrados para sua frota e configurados corretamente para usar a federação de identidade da carga de trabalho da frota. As seções a seguir descrevem como configurar a federação de identidade da carga de trabalho da frota para diferentes tipos de clusters.

GKE

Para clusters do GKE, faça o seguinte:

  1. Ative a federação de identidade da carga de trabalho do GKE no cluster do Google Kubernetes Engine, se ela ainda não estiver ativada.
  2. Registre o cluster na frota.

Também é possível ativar a federação de identidade da carga de trabalho para o GKE durante o processo de criação de cluster e registro de frota.

Clusters fora do Google Cloud

Os seguintes tipos de cluster ativam automaticamente a Federação de identidade da carga de trabalho da frota e são registrados na frota durante a criação do cluster:

  • Google Distributed Cloud (somente software) no VMware
  • Google Distributed Cloud (somente software) em bare metal
  • GKE na AWS
  • GKE no Azure

Clusters anexados

Os clusters anexados do EKS e do AKS registrados usando a GKE Multi-cloud são registrados com a federação de identidade da carga de trabalho da frota ativada por padrão. Os clusters anexados podem ser registrados com a federação de identidade da carga de trabalho da frota ativada se atenderem aos requisitos necessários. Siga as instruções para o tipo de cluster em Como registrar um cluster.

Usar a federação de identidade da carga de trabalho da frota em aplicativos

As etapas a seguir mostram como configurar uma carga de trabalho em um cluster registrado para usar a federação de identidade da carga de trabalho da frota:

  1. Encontre o nome do pool de identidades e do provedor de identidade da carga de trabalho do cluster:

    gcloud container fleet memberships describe MEMBERSHIP_ID \
    --project=FLEET_PROJECT_ID \
    --format="table(authority.identityProvider,authority.workloadIdentityPool,name)"

    Substitua:

    • MEMBERSHIP_ID: o nome da assinatura do cluster. Geralmente é o nome do cluster.
    • FLEET_PROJECT_ID: o ID do projeto host da frota.

    O resultado será assim:

    IDENTITY_PROVIDER: IDENTITY_PROVIDER
WORKLOAD_IDENTITY_POOL: WORKLOAD_IDENTITY_POOL
NAME: projects/FLEET_PROJECT_ID/locations/MEMBERSHIP_LOCATION/memberships/MEMBERSHIP_ID

    Essa saída contém as seguintes informações:

    • IDENTITY_PROVIDER: o provedor de identidade do cluster.
    • MEMBERSHIP_LOCATION: o local da assinatura da frota. Geralmente, é igual ao local do cluster.
    • WORKLOAD_IDENTITY_POOL: o nome do pool de identidade da carga de trabalho associado à sua frota. Esse valor tem a sintaxe FLEET_PROJECT_ID.svc.id.goog.

  2. Crie um namespace do Kubernetes. Também é possível usar qualquer namespace existente, incluindo o namespace default.

    kubectl create namespace NAMESPACE

    Substitua NAMESPACE pelo nome do namespace.

  3. Crie uma nova conta de serviço do Kubernetes no namespace: Também é possível usar qualquer ServiceAccount atual, incluindo a default no namespace.

    kubectl create serviceaccount KSA_NAME \
    --namespace=NAMESPACE

    Substitua KSA_NAME pelo nome da conta de serviço.

  4. Salve o seguinte manifesto adc-config-map.yaml como : Esse ConfigMap contém a configuração do ADC para cargas de trabalho.

    kind: ConfigMap
apiVersion: v1
metadata:
  namespace: NAMESPACE
  name: my-cloudsdk-config
data:
  config: |
    {
      "type": "external_account",
      "audience": "identitynamespace:WORKLOAD_IDENTITY_POOL:IDENTITY_PROVIDER",
      "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
      "token_url": "https://sts.googleapis.com/v1/token",
      "credential_source": {
        "file": "/var/run/secrets/tokens/gcp-ksa/token"
      }
    }

  5. Implante o ConfigMap:

    kubectl create -f adc-config-map.yaml

  6. Salve o seguinte manifesto como workload-config.yaml:

    apiVersion: v1
kind: Pod
metadata:
  name: my-pod
  namespace:  NAMESPACE
spec:
  serviceAccountName: KSA_NAME
  containers:
  - name: sample-container
    image: google/cloud-sdk:slim
    command: ["sleep","infinity"]
    env:
    - name: GOOGLE_APPLICATION_CREDENTIALS
      value: /var/run/secrets/tokens/gcp-ksa/google-application-credentials.json
    volumeMounts:
    - name: gcp-ksa
      mountPath: /var/run/secrets/tokens/gcp-ksa
      readOnly: true
  volumes:
  - name: gcp-ksa
    projected:
      defaultMode: 420
      sources:
      - serviceAccountToken:
          path: token
          audience: WORKLOAD_IDENTITY_POOL
          expirationSeconds: 172800
      - configMap:
          name: my-cloudsdk-config
          optional: false
          items:
          - key: "config"
            path: "google-application-credentials.json"

    Quando você implanta essa carga de trabalho, o volume gcp-ksa no pod contém os seguintes dados:

    O contêiner no pod monta o volume gcp-ksa no caminho /var/run/secrets/tokens/gcp-ksa e configura o ADC para procurar o arquivo JSON de configuração de credenciais nesse caminho.

  7. Implantar a carga de trabalho:

    kubectl apply -f workload-config.yaml

Alternativa: representar uma conta de serviço do IAM

Como alternativa, é possível configurar as contas de serviço do Kubernetes nos clusters para imitar as contas de serviço do IAM e realizar todas as ações autorizadas que elas podem realizar. Essa abordagem pode aumentar a sobrecarga de manutenção, porque você precisa gerenciar os pares de contas de serviço no IAM e no Kubernetes.

Na maioria dos casos, recomendamos que você faça referência direta aos principais do Kubernetes nas políticas de permissão do IAM para conceder acesso aos recursos do Google Cloud seguindo as instruções em Usar a federação de identidade da carga de trabalho da frota em aplicativos.

  1. Encontre o nome do pool de identidades e do provedor de identidade da carga de trabalho do cluster:

    gcloud container fleet memberships describe MEMBERSHIP_ID \
    --project=FLEET_PROJECT_ID \
    --format="table(authority.identityProvider,authority.workloadIdentityPool,name)"

    Substitua:

    • MEMBERSHIP_ID: o nome da assinatura do cluster. Geralmente é o nome do cluster.
    • FLEET_PROJECT_ID: o ID do projeto host da frota.

    O resultado será assim:

    IDENTITY_PROVIDER: IDENTITY_PROVIDER
WORKLOAD_IDENTITY_POOL: WORKLOAD_IDENTITY_POOL
NAME: projects/FLEET_PROJECT_ID/locations/MEMBERSHIP_LOCATION/memberships/MEMBERSHIP_ID

    Essa saída contém as seguintes informações:

    • IDENTITY_PROVIDER: o provedor de identidade do cluster.
    • MEMBERSHIP_LOCATION: o local da assinatura. Geralmente, é igual ao local do cluster.
    • WORKLOAD_IDENTITY_POOL: o nome do pool de identidade da carga de trabalho associado à sua frota. Esse valor tem a sintaxe FLEET_PROJECT_ID.svc.id.goog.

  2. Crie uma conta de serviço do IAM que seu aplicativo possa imitar. Também é possível usar qualquer conta de serviço do IAM.

    gcloud iam service-accounts create IAM_SA_NAME \
    --project=IAM_SA_PROJECT_ID

    Substitua:

    • IAM_SA_NAME: o nome da sua conta de serviço do IAM.
    • IAM_SA_PROJECT_ID: o ID do projeto que contém sua conta de serviço do IAM. Ele pode ser diferente do seu projeto host da frota.

  3. Conceda à conta de serviço do IAM todas as permissões necessárias para acessar as APIs do Google Cloud adicionando as políticas de permissão do IAM necessárias. Para isso, use gcloud iam service-accounts add-iam-policy-binding ou outro método. Descubra quais permissões são necessárias para usar as APIs do Google Cloud na documentação de cada serviço e consulte uma lista completa de papéis predefinidos com as permissões necessárias em Noções básicas sobre papéis.

  4. Crie uma conta de serviço do Kubernetes em um namespace. Também é possível usar uma Kubernetes ServiceAccount e qualquer namespace, incluindo a default ServiceAccount e o namespace default.

    kubectl create serviceaccount KSA_NAME \
    --namespace=NAMESPACE

    Substitua:

    • KSA_NAME: o nome da ServiceAccount.
    • NAMESPACE: o nome do namespace.

  5. Crie uma política de permissão do IAM que permita que uma ServiceAccount do Kubernetes em um namespace específico no cluster personifique a conta de serviço do IAM:

    gcloud iam service-accounts add-iam-policy-binding IAM_SA_NAME@IAM_SA_PROJECT_ID.iam.gserviceaccount.com \
    --project=IAM_SA_PROJECT_ID \
    --role=roles/iam.workloadIdentityUser \
    --member="serviceAccount:WORKLOAD_IDENTITY_POOL[NAMESPACE/KSA_NAME]"

    Substitua WORKLOAD_IDENTITY_POOL pelo nome do pool de identidade da carga de trabalho.

  6. Salve o seguinte manifesto adc-config-map.yaml como : Esse ConfigMap contém a configuração do ADC para cargas de trabalho.

    kind: ConfigMap
apiVersion: v1
metadata:
  namespace: K8S_NAMESPACE
  name: my-cloudsdk-config
data:
  config: |
    {
      "type": "external_account",
      "audience": "identitynamespace:WORKLOAD_IDENTITY_POOL:IDENTITY_PROVIDER",
      "service_account_impersonation_url": "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/IAM_SA_NAME@GSA_PROJECT_ID.iam.gserviceaccount.com:generateAccessToken",
      "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
      "token_url": "https://sts.googleapis.com/v1/token",
      "credential_source": {
        "file": "/var/run/secrets/tokens/gcp-ksa/token"
      }
    }

    Substitua:

    • IAM_SA_NAME: o nome da conta de serviço do IAM a ser imitada.
    • IAM_SA_PROJECT_ID, o ID do projeto da conta de serviço do IAM.

  7. Salve o seguinte manifesto como workload-config.yaml:

    apiVersion: v1
kind: Pod
metadata:
  name: my-pod
  namespace:  K8S_NAMESPACE
spec:
  serviceAccountName: KSA_NAME
  containers:
  - name: my-container
    image: my-image
    command: ["sleep","infinity"]
    env:
      - name: GOOGLE_APPLICATION_CREDENTIALS
        value: /var/run/secrets/tokens/gcp-ksa/google-application-credentials.json
    volumeMounts:
    - name: gcp-ksa
      mountPath: /var/run/secrets/tokens/gcp-ksa
      readOnly: true
  volumes:
  - name: gcp-ksa
    projected:
      defaultMode: 420
      sources:
      - serviceAccountToken:
          path: token
          audience: WORKLOAD_IDENTITY_POOL
          expirationSeconds: 172800
      - configMap:
          name: my-cloudsdk-config
          optional: false
          items:
            - key: "config"
              path: "google-application-credentials.json"

    Quando você implanta essa carga de trabalho, o volume gcp-ksa no pod contém os seguintes dados:

    O contêiner no pod monta o volume gcp-ksa no caminho /var/run/secrets/tokens/gcp-ksa e configura o ADC para procurar o arquivo JSON de configuração de credenciais nesse caminho.

  8. Implantar a carga de trabalho:

    kubectl apply -f workload-config.yaml

Verificar a configuração da federação de identidade da carga de trabalho da frota

Nesta seção, você vai criar um bucket do Cloud Storage e acessá-lo em um pod que usa a federação de identidade da carga de trabalho da frota. Antes de realizar essas etapas, verifique se você configurou a federação de identidade da carga de trabalho seguindo as instruções na seção Usar a federação de identidade da carga de trabalho da frota em aplicativos.

Esta seção não mostra como verificar a federação de identidade da carga de trabalho usando o método de personificação da conta de serviço do IAM.

  1. Encontre o número do projeto:

    gcloud projects describe FLEET_PROJECT_ID \
    --format="value(projectNumber)"

    O resultado será assim:

    1234567890

  2. Crie um bucket do Cloud Storage:

    gcloud storage buckets create gs://FLEET_PROJECT_ID-test-bucket \
    --location=LOCATION

    Substitua LOCATION por um local do Google Cloud.

  3. Crie uma política de permissão do IAM que conceda acesso ao bucket à conta de serviço criada:

    gcloud storage buckets add-iam-policy-binding gs://FLEET_PROJECT_ID-test-bucket \
    --condition=None \
    --role=roles/storage.objectViewer \
    --member=principal://iam.googleapis.com/projects/FLEET_PROJECT_NUMBER/locations/global/workloadIdentityPools/FLEET_PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME

    Substitua:

    • FLEET_PROJECT_NUMBER: o número numérico do projeto.
    • FLEET_PROJECT_ID: o ID do projeto.
    • NAMESPACE: o nome do namespace do Kubernetes que executa seu pod da seção anterior.
    • KSA_NAME: o nome da ServiceAccount do Kubernetes que o pod da seção anterior usa.

  4. Abra uma sessão do shell no pod:

    kubectl exec -it pods/my-pod --namespace=NAMESPACE -- /bin/bash

  5. Tente listar os objetos no bucket:

    curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://storage.googleapis.com/storage/v1/b/test-bucket/o"

    A saída é esta:

    {
  "kind": "storage#objects"
}

Autenticar a partir do seu código

Quando você usa as bibliotecas de cliente do Cloud, as bibliotecas de autenticação usam automaticamente o ADC para procurar credenciais para autenticar nos serviços do Google Cloud. Use as bibliotecas de cliente do Cloud compatíveis com a federação de identidade da carga de trabalho. Veja a seguir o mínimo necessário de versões das bibliotecas de cliente do Cloud, além de instruções sobre como verificar a versão atual:

C++

A maioria das bibliotecas de cliente do Google Cloud para C++ é compatível com a federação de identidade usando um objeto ChannelCredentials, que é criado chamando grpc::GoogleDefaultCredentials(). Para inicializar essa credencial, crie as bibliotecas de cliente com a versão 1.36.0 ou posteriores do gRPC.

A biblioteca de cliente do Cloud Storage para C++ usa a API REST, não a gRPC. Portanto, ela não é compatível com a federação de identidade.

Go

As bibliotecas de cliente do Go são compatíveis com a federação de identidade se usarem a versão v0.0.0-20210218202405-ba52d332ba99 ou posteriores do módulo golang.org/x/oauth2.

Para verificar qual versão deste módulo sua biblioteca de cliente usa, execute os seguintes comandos:

cd $GOPATH/src/cloud.google.com/go
go list -m golang.org/x/oauth2

Java

As bibliotecas de cliente do Java aceitam federação de identidade se usarem a versão 0.24.0 ou posteriores do artefato com.google.auth:google-auth-library-oauth2-http.

Para verificar qual versão desse artefato a biblioteca de cliente usa, execute o seguinte comando do Maven no diretório do aplicativo:

mvn dependency:list -DincludeArtifactIds=google-auth-library-oauth2-http

Node.js

As bibliotecas de cliente do Node.js são compatíveis com a federação de identidade se usarem a versão 7.0.2 ou posteriores do pacote google-auth-library.

Para verificar qual versão desse pacote sua biblioteca de cliente usa, execute o seguinte comando no diretório do seu aplicativo:

npm list google-auth-library

Ao criar um objeto GoogleAuth, é possível especificar um ID de projeto ou permitir que GoogleAuth encontre o ID do projeto automaticamente. Para encontrar o ID do projeto automaticamente, a conta de serviço no arquivo de configuração precisa ter o papel de navegador (roles/browser), ou um papel com permissões equivalentes no projeto. Para ver detalhes, consulte o README do pacote google-auth-library.

Python

As bibliotecas de cliente do Python são compatíveis com a federação de identidade se usarem a versão 1.27.0 ou posteriores do pacote google-auth.

Para verificar qual versão desse pacote sua biblioteca de cliente usa, execute o seguinte comando no ambiente em que o pacote está instalado:

pip show google-auth

Para especificar um ID de projeto para o cliente de autenticação, defina a variável de ambiente GOOGLE_CLOUD_PROJECT ou permita que o cliente encontre o ID do projeto automaticamente. Para encontrar o ID do projeto automaticamente, a conta de serviço no arquivo de configuração precisa ter o papel de Navegador (roles/browser) ou um papel com permissões equivalentes no projeto. Para ver detalhes, consulte o guia do usuário do pacote google-auth.

A seguir

Conheça as práticas recomendadas para organizar suas frotas ao usar a federação de identidade da carga de trabalho da frota.