Usar a Identidade da carga de trabalho da frota

Os aplicativos geralmente precisam se autenticar (fornecer uma identidade autêntica) ao se conectarem a outros serviços. Por exemplo, seus aplicativos precisam se autenticar para usar as APIs do Google Cloud, como as APIs do Compute Engine ou do AI Platform. Nesta página, explicamos como usar a Identidade da carga de trabalho da frota, a maneira recomendada e mais simples para as cargas de trabalho de aplicativos hospedadas em uma frota para serem autenticadas nas APIs e serviços do Google Cloud.

O que é a Identidade da carga de trabalho da frota?

A Identidade da carga de trabalho da frota estende a funcionalidade fornecida na Identidade da carga de trabalho do GKE, permitindo que as cargas de trabalho no cluster sejam autenticadas no Google sem que você precise fazer o download, alternar manualmente e gerenciar as chaves da conta de serviço do Google Cloud. Em vez disso, as cargas de trabalho são autenticadas usando tokens de curta duração gerados pelo cluster. Todos os clusters com a Identidade da carga de trabalho do GKE ativada usam o pool de identidades da carga de trabalho do projeto ao emitir IDs. Isso permite que o Identity and Access Management confie e entenda as credenciais da conta de serviço do Kubernetes. Saiba mais sobre a Identidade da carga de trabalho do GKE em Como usar a Identidade da carga de trabalho.

As frotas permitem que os clusters registrados aproveitem o benefício extra de usar a Identidade da carga de trabalho da frota. Os clusters registrados com a Identidade da carga de trabalho ativada na assinatura da frota podem usar o pool de identidades de carga de trabalho em toda a frota. Isso simplifica a configuração da autenticação nas APIs do Google e em outros serviços na frota e em vários projetos. O agente do Connect também pode usar a 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 Anthos Service Mesh.

Como funciona

As frotas usam a federação de identidade da carga de trabalho para fornecer a cada aplicativo uma identidade federada distinta que pode ser usada para autenticar no Google Cloud e em outros serviços que você desenvolve. Os aplicativos em execução em uma frota recebem uma identidade de carga de trabalho federada no seguinte formato:

serviceAccount:FLEET_PROJECT_ID.svc.id.goog[K8S_NAMESPACE/KSA_NAME]

Em que:

  • FLEET_PROJECT_ID.svc.id.goog é uma representação abreviada do pool de identidade da carga de trabalho para a frota. Há apenas um pool fixo de identidades de carga de trabalho por frota, e ele é criado automaticamente para você.
  • K8S_NAMESPACE é o namespace do Kubernetes em que a conta de serviço do Kubernetes está definida.
  • KSA_NAME é o nome da conta de serviço do Kubernetes anexada ao aplicativo.

Todos os aplicativos hospedados em uma frota compartilham o mesmo pool de identidade da carga de trabalho, fornecendo aos aplicativos uma identidade federada que se abstrai do local em que cada aplicativo está hospedado. Isso possibilita que um aplicativo dentro de uma frota acesse um recurso (como uma API Google Cloud) apenas uma vez, em vez de cluster por cluster, mesmo que o aplicativo seja implantado em projetos do Google Cloud ou em nuvens diferentes. Assim como outros recursos ativados para a frota, isso depende do princípio da frota de semelhança, em que objetos do Kubernetes com o mesmo nome 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, será fácil configurar o aplicativo para que todos os serviços em o namespace "backend" pode acessar essa API. 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, será fácil configurar o aplicativo para que todos os serviços em o namespace "backend" pode acessar essa API.

Os clusters fora do Google Cloud também podem usar a identidade da carga de trabalho da frota para fornecer uma identidade ao agente do Connect para autenticação no Google. Saiba quais tipos de cluster usam a identidade da carga de trabalho da frota na seção configuração do cluster abaixo.

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 ferramenta CLI gcloud para usar com seu projeto.

Configuração do cluster

Antes que os aplicativos da sua frota recebam uma identidade de carga de trabalho, os clusters em que eles são executados precisam ser registrados para sua frota e configurados corretamente para usar a identidade da carga de trabalho da frota. A maneira de fazer isso depende do tipo de cluster. A maior parte dos clusters do GKE fora do Google Cloud são registrados automaticamente na frota do projeto durante a criação deles. Os clusters do GKE no Google Cloud e os clusters anexados precisam ser registrados manualmente.

Consulte a documentação de cada tipo de cluster para mais informações sobre a configuração do cluster.

GKE;

  1. Ative a Identidade da carga de trabalho do GKE no cluster do Google Kubernetes Engine, se ela ainda não estiver ativada.
  2. Siga as instruções para registrar o cluster usando a Identidade da carga de trabalho.

Clusters do GKE fora do Google Cloud

O GKE no VMware, o GKE em Bare Metal e os clusters do GKE multicloud (tanto na AWS quanto no Azure) são registrados automaticamente na frota do projeto na data e hora da criação do cluster. A partir do GKE Enterprise 1.8, todos esses tipos de cluster ativam automaticamente a Identidade da carga de trabalho da frota quando registrados. Os clusters registrados que já existem são atualizados para usar a Identidade da carga de trabalho quando fazem upgrade para o GKE Enterprise 1.8 ou superior.

Clusters anexados

Os clusters anexados do EKS e do AKS registrados usando a GKE Multi-cloud são registrados com a Identidade da carga de trabalho da frota ativada por padrão. Os clusters anexados podem ser registrados com a 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 Identidade da carga de trabalho da frota

Depois de registrar o cluster, as cargas de trabalho implantadas no cluster poderão usar as identidades de carga de trabalho do pool de identidades da carga de trabalho da frota. Nesta seção, mostramos como usar a identidade da carga de trabalho para representar uma conta de serviço do Google Cloud e acessar suas APIs do Google Cloud. Agir como uma conta de serviço é um caso de uso comum para identidades federadas, porque permite que as cargas de trabalho sejam autenticadas em qualquer API do Google Cloud a que a conta de serviço tenha acesso, eliminando a carga de manutenção e segurança de ter que gerenciar chaves de contas de serviço para cada carga de trabalho.

Representar uma conta de serviço

Nesta seção, mostramos como configurar a identidade da carga de trabalho federada de um aplicativo para personificar uma conta de serviço. Para isso, ele fornece um arquivo de credenciais padrão do aplicativo em um ConfigMap, incluindo a criação e configuração da conta de serviço com as permissões relevantes.

O exemplo usa os seguintes valores de marcador:

  • WORKLOAD_IDENTITY_POOL é o pool de identidade da carga de trabalho associado à sua frota. Conforme mostrado acima, o valor de WORKLOAD_IDENTITY_POOL é FLEET_PROJECT_ID.svc.id.goog.
  • IDENTITY_PROVIDER é o nome do provedor de identidade associado ao cluster do Kubernetes;
  • K8S_NAMESPACE é o namespace do Kubernetes em que a conta de serviço do Kubernetes está definida.
  • KSA_NAME é o nome da conta de serviço do Kubernetes anexada ao aplicativo;
  • GSA_NAME é o nome da conta de serviço do Google que será usada pelo aplicativo.
  • GSA_PROJECT_ID é o ID do projeto em que a conta de serviço do Google está definida.

Para configurar uma identidade de carga de trabalho de frota para personificar uma conta de serviço:

  1. Verifique se o cluster está registrado na frota seguindo as etapas na seção Configuração do cluster acima.

  2. Receba os valores de WORKLOAD_IDENTITY_POOL e IDENTITY_PROVIDER do cluster registrado recuperando os detalhes da associação da frota do cluster usando o comando a seguir. Substitua MEMBERSHIP pelo nome de assinatura exclusivo do seu cluster na frota:

    gcloud container fleet memberships describe MEMBERSHIP

    O resultado de descrever a assinatura é semelhante a este (alguns campos foram omitidos para maior clareza):

    authority:
 identityProvider: IDENTITY_PROVIDER
 workloadIdentityPool: WORKLOAD_IDENTITY_POOL
name: projects/FLEET_PROJECT_ID/locations/global/memberships/MEMBERSHIP

  3. Crie uma conta de serviço do Google Cloud que seu aplicativo possa representar ao autenticar no Google, se você não tiver uma:

    gcloud iam service-accounts create GSA_NAME --project=GSA_PROJECT_ID

    A conta de serviço não precisa estar no projeto do host da frota. É possível usar qualquer conta de serviço do Google Cloud na sua organização. Saiba mais sobre contas de serviço e como elas funcionam em Contas de serviço.

  4. Verifique se você concedeu à conta de serviço as permissões necessárias para acessar as APIs do Google Cloud adicionando as vinculações de política do IAM necessárias. Para fazer isso, use gcloud iam service-accounts add-iam-policy-binding ou outro método, se preferir. 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.

  5. Crie uma vinculação de política do IAM para autorizar a identidade da carga de trabalho do seu aplicativo a personificar a conta de serviço. Essa vinculação permite que a identidade da carga de trabalho federada do aplicativo atue como a conta de serviço do Google Cloud.

    gcloud iam service-accounts add-iam-policy-binding \
  GSA_NAME@GSA_PROJECT_ID.iam.gserviceaccount.com \
  --role=roles/iam.workloadIdentityUser \
  --member="serviceAccount:WORKLOAD_IDENTITY_POOL[K8S_NAMESPACE/KSA_NAME]"

    O campo --member é a representação do IAM da identidade de carga de trabalho federada do aplicativo.

  6. Crie um ConfigMap que contenha o arquivo de credenciais padrão do aplicativo para sua carga de trabalho. Esse arquivo informa à biblioteca de cliente como compilada na sua carga de trabalho como autenticar no Google. O arquivo do Application Default Credentials contém as informações relevantes da conta de serviço e do pool de identidades da carga de trabalho, além do caminho do token projetado que será ativado no sistema de arquivos do contêiner na próxima etapa. GSA_NAME@GSA_PROJECT_ID.iam.gserviceaccount.com: o endereço de e-mail da conta de serviço a ser personificada.

    Essa configuração sozinha não concede acesso para personificar a conta de serviço. Se a vinculação do IAM também não existir, o pod não poderá usar a conta de serviço.

    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/GSA_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"
      }
    }

  7. Siga o exemplo abaixo para configurar sua carga de trabalho. O ConfigMap da etapa anterior é ativado no sistema de arquivos do contêiner como google-application-credentials.json, ao lado de um arquivo de token de conta de serviço projetado, em /var/run/secrets/tokens/gcp-ksa. Os tokens projetados são emitidos pelo Kubernetes e representam a identidade da carga de trabalho dentro do cluster. Esses tokens são trocados automaticamente com o Google pelas bibliotecas de cliente do Cloud para receber tokens que podem ser autenticados com as APIs do Google. O campo audience do token projetado precisa ser definido como o valor de WORKLOAD_IDENTITY_POOL.

    kind: Namespace
apiVersion: v1
metadata:
  name:  K8S_NAMESPACE
---
kind: ServiceAccount
apiVersion: v1
metadata:
  namespace:  K8S_NAMESPACE
  name: KSA_NAME
automountServiceAccountToken: false
---
apiVersion: v1
kind: Pod
metadata:
  name: my-pod
  namespace:  K8S_NAMESPACE
spec:
  serviceAccountName: KSA_NAME
  containers:
  - name: my-container
    image: my-image
    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"

Autenticar a partir do seu código

As bibliotecas de cliente do Cloud processam automaticamente a autenticação no Google Cloud quando você as usa para acessar os serviços do Google a partir do seu código. Para usar a configuração exibida acima nos seus aplicativos, use as bibliotecas de cliente do Cloud compatíveis com a Workload Identity Federation. 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.