Configure a Workload Identity Federation com o Kubernetes

Este guia descreve como usar a federação de identidades da carga de trabalho para permitir que as cargas de trabalho executadas no Azure Kubernetes Service (AKS), no Amazon Elastic Kubernetes Service ou num cluster Kubernetes autoalojado se autentiquem no Trusted Cloud.

O Kubernetes permite-lhe configurar um cluster para que as cargas de trabalho possam obter tokens de ServiceAccount do Kubernetes a partir de um volume projetado. Ao configurar a federação de identidades da carga de trabalho, pode permitir que as cargas de trabalho usem estes tokens de conta de serviço do Kubernetes para autenticar no Trusted Cloud.

Se estiver a usar o GKE, use a federação de identidades de cargas de trabalho para o GKE em vez de configurar a federação de identidades de cargas de trabalho.

Antes de começar

Antes de configurar a Workload Identity Federation, certifique-se de que o cluster do Kubernetes cumpre os seguintes critérios:

Configure a Workload Identity Federation

Só tem de realizar estes passos uma vez para cada cluster do Kubernetes. Em seguida, pode usar o mesmo Workload Identity Pool e fornecedor para vários pods do Kubernetes e em vários Trusted Cloud projetos.

Para começar a configurar a Workload Identity Federation, faça o seguinte:

1. In the Trusted Cloud console, on the project selector page, select or create a Trusted Cloud project.

   Roles required to select or create a project

   • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
   • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

   Go to project selector

Recomendamos que use um projeto dedicado para gerir os Workload Identity Pools e os fornecedores.

2. Verify that billing is enabled for your Trusted Cloud project.

Enable the IAM, Resource Manager, Service Account Credentials, and Security Token Service APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

Defina um mapeamento de atributos e uma condição

Os tokens ServiceAccount do Kubernetes contêm várias reivindicações, incluindo as seguintes:

• sub: contém o espaço de nomes e o nome da ServiceAccount, por exemplo, system:serviceaccount:NAMESPACE:KSA_NAME, em que NAMESPACE é o espaço de nomes da ServiceAccount e KSA_NAME é o nome da ServiceAccount.
• "kubernetes.io".namespace: contém o espaço de nomes da ServiceAccount.
• "kubernetes.io".serviceaccount.name: contém o nome da conta de serviço.
• "kubernetes.io".pod.name: contém o nome do agrupamento.

Para usar sub como identificador do assunto (google.subject) em Trusted Cloud, use o seguinte mapeamento:

google.subject=assertion.sub

Opcionalmente, pode mapear atributos adicionais. Em seguida, pode consultar estes atributos quando conceder acesso a recursos. Por exemplo:

google.subject=assertion.sub,
attribute.namespace=assertion['kubernetes.io']['namespace'],
attribute.service_account_name=assertion['kubernetes.io']['serviceaccount']['name'],
attribute.pod=assertion['kubernetes.io']['pod']['name']

Opcionalmente, defina uma condição de atributo. As condições de atributos são expressões CEL que podem verificar atributos de afirmação e atributos de destino. Se a condição do atributo for avaliada como true para uma determinada credencial, a credencial é aceite. Caso contrário, a credencial é rejeitada.

Pode usar uma condição de atributo para restringir as contas de serviço do Kubernetes que podem usar a federação de identidades da carga de trabalho para obter tokens Trusted Cloudde curta duração. Por exemplo, a seguinte condição restringe o acesso a Kubernetes ServiceAccounts dos espaços de nomes backend e monitoring:

assertion['kubernetes.io']['namespace'] in ['backend', 'monitoring']

Crie o Workload Identity Pool e o fornecedor

Para criar um Workload Identity Pool e um fornecedor, faça o seguinte:

Conceda acesso a uma carga de trabalho do Kubernetes

Esta secção descreve como configurar uma carga de trabalho do Kubernetes para aceder às Trusted Cloud APIs através do acesso direto aos recursos da federação de identidades da carga de trabalho ou da representação de contas de serviço.

Tem de realizar estes passos uma vez para cada carga de trabalho do Kubernetes que precise de acesso a Trusted Cloud.

Recomendamos que use a Workload Identity Federation. No entanto, quando usa a federação de identidades, determinados métodos de API podem ter limitações. Para ver uma lista de limitações, consulte o artigo Federação de identidades: produtos e limitações.

Se os métodos que a sua carga de trabalho usa tiverem essas limitações, pode, em alternativa, usar a representação do IAM.

Use a federação de identidades de cargas de trabalho para conceder acesso direto a recursos

Nesta secção, usa a Workload Identity Federation para conceder uma função do IAM a uma conta de serviço do Kubernetes para que possa aceder diretamente aos Trusted Cloud recursos.

Para criar uma ServiceAccount do Kubernetes e atribuir-lhe uma função, faça o seguinte:

1. Crie uma conta de serviço do Kubernetes:

   kubectl create serviceaccount KSA_NAME --namespace NAMESPACE
   

   Substitua o seguinte:

   • KSA_NAME: Um nome da ServiceAccount.
   • NAMESPACE: o espaço de nomes no qual criar o ServiceAccount.

2. Conceda acesso IAM à conta de serviço do Kubernetes para um recursoTrusted Cloud .

   Seguindo o princípio do menor privilégio, recomendamos que conceda apenas funções específicas dos recursos aos quais a sua aplicação tem de aceder.

   No exemplo seguinte, o comando concede a função Kubernetes Engine Cluster Viewer (roles/container.clusterViewer) à ServiceAccount que criou. O comando usa o assunto que mapeou anteriormente neste documento.

   gcloud projects add-iam-policy-binding projects/PROJECT_ID \
       --role=roles/container.clusterViewer \
       --member=principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/MAPPED_SUBJECT \
       --condition=None
   

   Substitua o seguinte:

   • PROJECT_NUMBER: o número Trusted Cloud numérico do projeto associado ao ID do projeto.

   • POOL_ID: o ID do Workload Identity Pool.

   • MAPPED_SUBJECT: a ServiceAccount do Kubernetes da reivindicação no seu token de ID que mapeou para google.subject. Por exemplo, se mapeou google.subject=assertions.sub e o seu token de ID contém "sub": "system:serviceaccount:default:my-kubernetes-serviceaccount", então MAPPED_SUBJECT é system:serviceaccount:default:my-kubernetes-serviceaccount.

   Pode conceder funções em qualquer Trusted Cloud recurso que suporte políticas de autorização de IAM. A sintaxe do identificador principal depende do recurso do Kubernetes. Para ver uma lista dos identificadores suportados, consulte o artigo Identificadores principais para a federação de identidades da carga de trabalho para o GKE.

Agora, pode implementar uma carga de trabalho que use a conta de serviço do Kubernetes para aceder aos Trusted Cloud recursos aos quais concedeu acesso.

Alternativa: use a simulação da conta de serviço do IAM para conceder acesso

Para configurar a sua ServiceAccount do Kubernetes para usar a representação de conta de serviço do IAM, faça o seguinte:

1. Crie uma conta de serviço do Kubernetes, se ainda não o tiver feito:

   kubectl create serviceaccount KSA_NAME --namespace NAMESPACE
   

   Substitua o seguinte:

   • KSA_NAME: um nome para a ServiceAccount
   • NAMESPACE: o espaço de nomes no qual criar o ServiceAccount

2. Crie uma conta de serviço do IAM que represente a carga de trabalho.

   A conta de serviço não tem de estar no mesmo projeto que o conjunto de identidades da carga de trabalho, mas tem de especificar o projeto que contém a conta de serviço quando se refere a ela.

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

   Substitua o seguinte:

   • IAM_SA_NAME: o nome da conta de serviço
   • IAM_SA_PROJECT_ID: o ID do projeto da conta de serviço

3. Conceda acesso à sua conta de serviço do IAM aos Trusted Cloud recursos específicos aos quais quer que a carga de trabalho do Kubernetes aceda.

   gcloud projects add-iam-policy-binding IAM_SA_PROJECT_ID \
       --member="serviceAccount:IAM_SA_NAME@IAM_SA_PROJECT_ID.s3ns.iam.gserviceaccount.com" \
       --role="ROLE"
   

   Substitua o seguinte:

   • IAM_SA_PROJECT_ID: o ID do projeto onde criou a sua conta de serviço
   • IAM_SA_NAME: o nome da conta de serviço
   • ROLE: com o nome da função, por exemplo, roles/container.clusterViewer

4. Conceda à conta de serviço do Kubernetes acesso para usar a identidade da conta de serviço do IAM:

   gcloud iam service-accounts add-iam-policy-binding \
     IAM_SA_NAME@IAM_SA_PROJECT_ID.s3ns.iam.gserviceaccount.com \
       --member="principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/MAPPED_SUBJECT" \
       --role=roles/iam.workloadIdentityUser
   
   

   Substitua o seguinte:

   • IAM_SA_NAME: o nome da conta de serviço
   • PROJECT_ID: o ID do projeto onde executa o Kubernetes
   • IAM_SA_PROJECT_NUMBER: o número do projeto do projeto onde criou a sua conta de serviço
   • POOL_ID: o ID do Workload Identity Pool.
   • MAPPED_SUBJECT: a ServiceAccount do Kubernetes da reivindicação no seu token de ID que mapeou para google.subject. Por exemplo, se mapeou google.subject=assertions.sub e o seu token de ID contém "sub": "system:serviceaccount:default:my-kubernetes-serviceaccount", então MAPPED_SUBJECT é system:serviceaccount:default:my-kubernetes-serviceaccount.

   Para obter informações sobre a autorização de contas de serviço IAM para aceder a Trusted Cloud by S3NS APIs, consulte o artigo Compreender as contas de serviço.

Já pode implementar uma carga de trabalho que usa a conta de serviço do Kubernetes e a conta de serviço do IAM para aceder aos Trusted Cloudrecursos aos quais concedeu acesso.

Implemente a carga de trabalho do Kubernetes

Para implementar uma carga de trabalho do Kubernetes que possa aceder a recursos Trusted Cloud , faça o seguinte:

1. Crie um ficheiro de configuração de credenciais:

   gcloud iam workload-identity-pools create-cred-config \
       projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/WORKLOAD_PROVIDER_ID \
       --service-account=SERVICE_ACCOUNT_EMAIL \
       --credential-source-file=/var/run/service-account/token \
       --credential-source-type=text \
       --output-file=credential-configuration.json

   Substitua o seguinte:

   • PROJECT_NUMBER: o número do projeto do projeto que contém o Workload Identity Pool
   • POOL_ID: o ID do Workload Identity Pool
   • WORKLOAD_PROVIDER_ID: o ID do fornecedor do Workload Identity Pool
   • SERVICE_ACCOUNT_EMAIL: endereço de email da conta de serviço, se configurou a sua conta de serviço do Kubernetes para usar a representação da conta de serviço do IAM. Omita esta flag se tiver configurado a sua conta de serviço do Kubernetes para usar o acesso direto aos recursos.

   O ficheiro de configuração de credenciais permite que as bibliotecas cliente da Google Cloud, a CLI gcloud e o Terraform determinem o seguinte:

   • Onde obter credenciais externas
   • Que Workload Identity Pool e fornecedor usar
   • Que conta de serviço usar como identidade

2. Importe o ficheiro de configuração de credenciais como um ConfigMap

   kubectl create configmap CONFIGMAP_NAME \
     --from-file credential-configuration.json \
     --namespace NAMESPACE
   

   Substitua o seguinte:

   • CONFIGMAP_NAME: o nome do ConfigMap.
   • NAMESPACE: o espaço de nomes no qual criar o ConfigMap.

3. Implemente uma carga de trabalho e permita que use a ServiceAccount e o ConfigMap do Kubernetes.

   Crie um manifesto e configure-o da seguinte forma:

   • Monte um volume de tokens projetado para que a carga de trabalho possa obter um token de conta de serviço do Kubernetes a partir de um ficheiro local. Configure o volume para que o token de conta de serviço do Kubernetes use o público-alvo esperado pelo fornecedor do conjunto de identidades da carga de trabalho.
   • Monte o ConfigMap que contém o ficheiro de configuração das credenciais para que a carga de trabalho possa aceder à configuração necessária para usar a Workload Identity Federation.
   • Adicione uma variável de ambiente GOOGLE_APPLICATION_CREDENTIALS que contenha o caminho do ficheiro de configuração das credenciais para que as cargas de trabalho possam encontrar o ficheiro.

   Segue-se um exemplo de um manifesto que usa a ServiceAccount do Kubernetes e o ConfigMap para permitir que a CLI Google Cloud se autentique em Trusted Cloud:

   apiVersion: v1
   kind: Pod
   metadata:
     name: example
     namespace: NAMESPACE
   spec:
     containers:
     - name: example
       image: google/cloud-sdk:alpine
       command: ["/bin/sh", "-c", "gcloud auth login --cred-file $GOOGLE_APPLICATION_CREDENTIALS && gcloud auth list && sleep 600"]
       volumeMounts:
       - name: token
         mountPath: "/var/run/service-account"
         readOnly: true
       - name: workload-identity-credential-configuration
         mountPath: "/etc/workload-identity"
         readOnly: true
       env:
       - name: GOOGLE_APPLICATION_CREDENTIALS
         value: "/etc/workload-identity/credential-configuration.json"
   
     serviceAccountName: KSA_NAME
     volumes:
     - name: token
       projected:
         sources:
         - serviceAccountToken:
             audience: https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/WORKLOAD_PROVIDER_ID
             expirationSeconds: 3600
             path: token
     - name: workload-identity-credential-configuration
       configMap:
         name: CONFIGMAP_NAME

   Pode seguir a mesma abordagem para permitir que as ferramentas e as cargas de trabalho que usam uma das seguintes bibliotecas de cliente encontrem credenciais automaticamente:

   C++

   As Trusted Cloud bibliotecas cliente para C++ suportam a federação de identidades da carga de trabalho desde a versão v2.6.0. Para usar a Workload Identity Federation, tem de criar as bibliotecas de cliente com a versão 1.36.0 ou posterior do gRPC.

   Go

   As bibliotecas cliente para Go suportam a federação de identidades da carga de trabalho se usarem a versão v0.0.0-20210218202405-ba52d332ba99 ou posterior do módulo golang.org/x/oauth2.

   Para verificar que versão deste módulo a 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 cliente para Java suportam a Workload Identity Federation se usarem a versão 0.24.0 ou posterior do artefacto com.google.auth:google-auth-library-oauth2-http.

   Para verificar que versão deste artefacto a sua biblioteca de cliente usa, execute o seguinte comando Maven no diretório da aplicação:

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

   Node.js

   As bibliotecas de cliente para Node.js suportam a Workload Identity Federation se usarem a versão 7.0.2 ou posterior do pacote google-auth-library.

   Para verificar que versão deste pacote a sua biblioteca de cliente usa, execute o seguinte comando no diretório da aplicação:

   npm list google-auth-library
   

   Quando cria um objeto GoogleAuth, pode especificar um ID do projeto ou permitir que a GoogleAuth encontre o ID do projeto automaticamente. Para encontrar o ID do projeto automaticamente, a conta de serviço no ficheiro de configuração tem de ter a função Navegador (roles/browser) ou uma função com autorizações equivalentes no seu projeto. Para obter detalhes, consulte o README para o pacote google-auth-library.

   Python

   As bibliotecas cliente para Python suportam a Federação de identidades de carga de trabalho se usarem a versão 1.27.0 ou posterior do pacote google-auth.

   Para verificar que versão deste pacote a sua biblioteca de cliente usa, execute o seguinte comando no ambiente onde o pacote está instalado:

   pip show google-auth
   

   Para especificar um ID do projeto para o cliente de autenticação, pode definir a variável de ambiente GOOGLE_CLOUD_PROJECT ou permitir que o cliente encontre o ID do projeto automaticamente. Para encontrar o ID do projeto automaticamente, a conta de serviço no ficheiro de configuração tem de ter a função de navegador (roles/browser) ou uma função com autorizações equivalentes no seu projeto. Para obter detalhes, consulte o manual do utilizador do pacote google-auth.

   gcloud

   Para autenticar com a Workload Identity Federation, use o comando gcloud auth login:

   gcloud auth login --cred-file=FILEPATH.json
   

   Substitua FILEPATH pelo caminho para o ficheiro de configuração das credenciais.

   O suporte para a Workload Identity Federation na CLI gcloud está disponível na versão 363.0.0 e versões posteriores da CLI gcloud.

   Terraform

   O Trusted Cloud fornecedor suporta a Workload Identity Federation se usar a versão 3.61.0 ou posterior:

   terraform {
     required_providers {
       google = {
         source  = "hashicorp/google"
         version = "~> 3.61.0"
       }
     }
   }
   

   bq

   Para autenticar através da Workload Identity Federation, use o comando gcloud auth login, da seguinte forma:

   gcloud auth login --cred-file=FILEPATH.json
   

   Substitua FILEPATH pelo caminho para o ficheiro de configuração das credenciais.

   O suporte para a Workload Identity Federation no bq está disponível na versão 390.0.0 e versões posteriores da CLI gcloud.

4. Opcionalmente, verifique se a autenticação funciona corretamente executando o seguinte comando:

   kubectl exec example --namespace NAMESPACE -- gcloud auth print-access-token

O que se segue?

• Leia mais sobre a federação de identidades da carga de trabalho.
• Saiba mais acerca das práticas recomendadas para usar a Workload Identity Federation.
• Veja como pode gerir Workload Identity Pools e fornecedores.