Autentique-se nas APIs Google Cloud a partir de cargas de trabalho do GKE

Esta página mostra como aceder de forma mais segura às Google Cloud APIs a partir das suas cargas de trabalho executadas em clusters do Google Kubernetes Engine (GKE) através da Federação do Workload Identity para o GKE.

Esta página destina-se aos administradores de identidade e de contas, aos operadores e aos programadores que criam e gerem políticas relacionadas com as autorizações dos utilizadores. Para saber mais sobre as funções comuns e as tarefas de exemplo que referimos no Google Cloud conteúdo, consulte Funções e tarefas comuns do utilizador do GKE.

Antes de ler esta página, certifique-se de que conhece os conceitos da Workload Identity Federation para o GKE.

Antes de começar

Antes de começar, certifique-se de que realizou as seguintes tarefas:

  • Ative a API Google Kubernetes Engine.
    • Ative a API Google Kubernetes Engine
  • Se quiser usar a CLI gcloud para esta tarefa, instale-a e, em seguida, inicialize-a. Se instalou anteriormente a CLI gcloud, execute gcloud components update para obter a versão mais recente.

Ative a federação de identidades de cargas de trabalho para o GKE em clusters e node pools

No Autopilot, a federação de identidade da carga de trabalho para o GKE está sempre ativada. Aceda à secção Configure as aplicações para usar a Workload Identity Federation para o GKE.

No Standard, ativa a Workload Identity Federation para o GKE em clusters e pools de nós através da Google Cloud CLI ou da Google Cloud consola. A Workload Identity Federation para o GKE tem de ser ativada ao nível do cluster antes de poder ativar a Workload Identity Federation para o GKE em conjuntos de nós.

Pode ativar a federação de identidades da carga de trabalho para o GKE num cluster padrão existente através da CLI gcloud ou da Google Cloud consola. Os conjuntos de nós existentes não são afetados, mas todos os novos conjuntos de nós no cluster usam a Workload Identity Federation para o GKE.

gcloud

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. Para ativar a federação de identidade da carga de trabalho para o GKE num cluster existente, execute o seguinte comando:

    gcloud container clusters update CLUSTER_NAME \
    --location=LOCATION \
    --workload-pool=PROJECT_ID.svc.id.goog

    Substitua o seguinte:

    3. Consola

    Para ativar a federação de identidade de cargas de trabalho para o GKE num cluster existente, faça o seguinte:

    1. Aceda à página do Google Kubernetes Engine na Google Cloud consola.

      Aceda ao Google Kubernetes Engine

    2. Na lista de clusters, clique no nome do cluster que quer modificar.

    3. Na página de detalhes do cluster, na secção Segurança, clique em Editar identidade da carga de trabalho.

    4. Na caixa de diálogo Editar Workload Identity, selecione a caixa de verificação Ativar Workload Identity.

    5. Clique em Guardar alterações.

Migre cargas de trabalho existentes para a federação de identidades de cargas de trabalho para o GKE

Depois de ativar a federação de identidade da força de trabalho para o GKE num cluster existente, pode querer migrar as suas cargas de trabalho em execução para usar a federação de identidade da força de trabalho para o GKE. Selecione a estratégia de migração ideal para o seu ambiente. Pode criar novos conjuntos de nós com a federação de identidade da carga de trabalho para o GKE ativada ou atualizar os conjuntos de nós existentes para ativar a federação de identidade da carga de trabalho para o GKE.

Só pode ativar a federação de identidades da força de trabalho para o GKE num conjunto de nós se a federação de identidades da força de trabalho para o GKE estiver ativada no cluster.

Prática recomendada:

Crie novos node pools se também precisar de modificar as suas aplicações para serem compatíveis com a Workload Identity Federation para o GKE.

Todos os novos conjuntos de nós que criar usam por predefinição a Workload Identity Federation para GKE se o cluster tiver a Workload Identity Federation para GKE ativada. Para criar um novo conjunto de nós com a Workload Identity Federation para o GKE ativada, execute o seguinte comando:

gcloud container node-pools create NODEPOOL_NAME \
    --cluster=CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --workload-metadata=GKE_METADATA

Substitua o seguinte:

  • NODEPOOL_NAME: o nome do novo node pool.
  • CLUSTER_NAME: o nome do cluster existente que tem a Workload Identity Federation para o GKE ativada.
  • CONTROL_PLANE_LOCATION: a localização do Compute Engine do plano de controlo do seu cluster. Indique uma região para clusters regionais ou uma zona para clusters zonais.

A flag --workload-metadata=GKE_METADATA configura o conjunto de nós para usar o servidor de metadados do GKE.

Prática recomendada:

Inclua a flag para que a criação do pool de nós falhe se a federação de identidades da força de trabalho para o GKE não estiver ativada no cluster.

Atualize um node pool existente

Pode ativar manualmente a federação de identidades da força de trabalho para o GKE em pools de nós existentes depois de ativar a federação de identidades da força de trabalho para o GKE no cluster.

gcloud

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. Para modificar um conjunto de nós existente para usar a Workload Identity Federation para o GKE, execute o seguinte comando:

    gcloud container node-pools update NODEPOOL_NAME \
    --cluster=CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --workload-metadata=GKE_METADATA

    Se um cluster tiver a federação de identidade da força de trabalho para o GKE ativada, pode desativá-la seletivamente num conjunto de nós específico especificando explicitamente --workload-metadata=GCE_METADATA. Consulte o artigo Proteger os metadados do cluster para mais informações.

    3. Consola

    Para modificar um conjunto de nós existente para usar a Workload Identity Federation para o GKE, siga os passos seguintes:

    1. Aceda à página do Google Kubernetes Engine na Google Cloud consola.

      Aceda ao Google Kubernetes Engine

    2. Na lista de clusters, clique no nome do cluster que quer modificar.

    3. Clique no separador Nós.

    4. Na secção Conjuntos de nós, clique no nome do conjunto de nós que quer modificar.

    5. Na página Detalhes do conjunto de nós, clique em Editar.

    6. Na página Editar conjunto de nós, na secção Segurança, selecione a caixa de verificação Ativar servidor de metadados do GKE.

    7. Clique em Guardar.

Configure aplicações para usar a federação de identidades de cargas de trabalho para o GKE

Para permitir que as suas aplicações do GKE se autentiquem em Google Cloud APIs através da Workload Identity Federation para GKE, crie políticas do IAM para as APIs específicas. O principal nestas políticas é um identificador principal do IAM que corresponde aos cargas de trabalho, aos espaços de nomes ou às contas de serviço do Kubernetes. Este processo devolve um token de acesso federado que a sua carga de trabalho pode usar em chamadas de API.

Em alternativa, pode configurar contas de serviço do Kubernetes para se fazerem passar por contas de serviço do IAM, o que configura o GKE para trocar o token de acesso federado por um token de acesso da API Google Cloud IAM Service Account Credentials. Para ver detalhes, consulte a secção Alternativa: associe contas de serviço do Kubernetes ao IAM.

Configure a autorização e os responsáveis

  1. Obtenha credenciais para o seu cluster:

    gcloud container clusters get-credentials CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION

    Substitua o seguinte:

    • CLUSTER_NAME: o nome do cluster que tem a Workload Identity Federation para o GKE ativada.
    • CONTROL_PLANE_LOCATION: a localização do Compute Engine do plano de controlo do seu cluster. Indique uma região para clusters regionais ou uma zona para clusters zonais.

  2. Crie um espaço de nomes para usar na conta de serviço do Kubernetes. Também pode usar o espaço de nomes default ou qualquer espaço de nomes existente.

    kubectl create namespace NAMESPACE

  3. Crie uma ServiceAccount do Kubernetes para a sua aplicação usar. Também pode usar qualquer ServiceAccount do Kubernetes existente em qualquer espaço de nomes. Se não atribuir uma ServiceAccount à sua carga de trabalho, o Kubernetes atribui a ServiceAccount default no espaço de nomes.

    kubectl create serviceaccount KSA_NAME \
    --namespace NAMESPACE

    Substitua o seguinte:

    • KSA_NAME: o nome da sua nova conta de serviço do Kubernetes.
    • NAMESPACE: o nome do namespace do Kubernetes para a ServiceAccount.

  4. Crie uma política de autorização do IAM que faça referência à conta de serviço do Kubernetes. Como prática recomendada, conceda autorizações a Google Cloud recursos específicos aos quais a sua aplicação precisa de aceder. Tem de ter autorizações de IAM relevantes para criar políticas de autorização no seu projeto.

    Por exemplo, o comando seguinte concede a função Kubernetes Engine Cluster Viewer (roles/container.clusterViewer) à ServiceAccount que criou:

    gcloud projects add-iam-policy-binding projects/PROJECT_ID \
    --role=roles/container.clusterViewer \
    --member=principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME \
    --condition=None

    Substitua o seguinte:

    • PROJECT_ID: o ID do seu Google Cloud projeto.
    • PROJECT_NUMBER: o número Google Cloud do projeto.

    Pode conceder funções em qualquer Google 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.

Opcional: configure as opções da malha de serviços

Se usar o Istio ou o Cloud Service Mesh para gerir o seu ambiente, adicione a seguinte anotação ao campo metadata.annotations na especificação do pod:

metadata:
  annotations:
    proxy.istio.io/config: '{ "holdApplicationUntilProxyStarts": true }'

Esta anotação impede que os seus contentores sejam iniciados até que o proxy da malha de serviços esteja pronto para redirecionar o tráfego das suas aplicações.

Valide a federação de identidades de cargas de trabalho para a configuração do GKE

Nesta secção, cria um contentor do Cloud Storage e concede acesso de visualização ao contentor à conta de serviço do Kubernetes que criou na secção anterior. Em seguida, implementa uma carga de trabalho e testa se o contentor consegue listar clusters no projeto.

  1. Crie um contentor do Cloud Storage vazio:

    gcloud storage buckets create gs://BUCKET

    Substitua BUCKET por um nome para o novo contentor.

  2. Conceda a função Storage Object Viewer (roles/storage.objectViewer) à conta de serviço que criou:

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

    Substitua o seguinte:

    • PROJECT_ID: o ID do seu Google Cloud projeto.
    • PROJECT_NUMBER: o número Google Cloud do projeto.
    • NAMESPACE: o namespace do Kubernetes que contém o ServiceAccount.
    • KSA_NAME: o nome da ServiceAccount.

  3. Guarde o seguinte manifesto como test-app.yaml:

    apiVersion: v1
kind: Pod
metadata:
  name: test-pod
  namespace: NAMESPACE
spec:
  serviceAccountName: KSA_NAME
  containers:
  - name: test-pod
    image: google/cloud-sdk:slim
    command: ["sleep","infinity"]
    resources:
      requests:
        cpu: 500m
        memory: 512Mi
        ephemeral-storage: 10Mi

  4. Apenas em clusters padrão, adicione o seguinte ao campo template.spec para colocar os pods em pools de nós que usam a Workload Identity Federation para o GKE.

    Ignore este passo nos clusters do Autopilot, que rejeitam este nodeSelector, porque todos os nós usam a Workload Identity Federation para o GKE.

    spec:
  nodeSelector:
    iam.gke.io/gke-metadata-server-enabled: "true"

  5. Aplique a configuração ao cluster:

    kubectl apply -f test-app.yaml

  6. Aguarde até o Pod ficar pronto. Para verificar o estado do pod, execute o seguinte comando:

    kubectl get pods --namespace=NAMESPACE

    Quando o pod estiver pronto, o resultado é semelhante ao seguinte:

    NAME       READY   STATUS    RESTARTS   AGE
test-pod   1/1     Running   0          5m27s

  7. Abra uma sessão de shell no pod:

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

  8. Obter uma lista de objetos no contentor:

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

    O resultado é o seguinte:

    {
  "kind": "storage#objects"
}

    Este resultado mostra que o seu pod pode aceder a objetos no contentor.

Alternativa: associe contas de serviço do Kubernetes ao IAM

Prática recomendada:

Use identificadores de principal da IAM para configurar a federação de identidade da força de trabalho para o GKE. No entanto, esta identidade federada tem limitações específicas para cada API Google Cloud suportada. Se estas limitações se aplicarem a si, siga os passos seguintes para configurar o acesso a essas APIs a partir das suas cargas de trabalho do GKE.

  1. Crie um namespace do Kubernetes:

    kubectl create namespace NAMESPACE

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

    kubectl create serviceaccount KSA_NAME \
    --namespace=NAMESPACE

  3. Crie uma conta de serviço do IAM. Também pode usar qualquer conta de serviço do IAM existente em qualquer projeto na sua organização.

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

    Substitua o seguinte:

    • IAM_SA_NAME: um nome para a sua nova conta de serviço do IAM.
    • IAM_SA_PROJECT_ID: o ID do projeto da sua conta de serviço do IAM.

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

  4. Conceda à sua conta de serviço do IAM as funções de que precisa nas APIs Google Cloud específicas:

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

    Substitua ROLE_NAME pelo nome da função, como roles/spanner.viewer.

  5. Crie uma política de permissão do IAM que conceda à conta de serviço do Kubernetes acesso à representação da conta de serviço do IAM:

    gcloud iam service-accounts add-iam-policy-binding IAM_SA_NAME@IAM_SA_PROJECT_ID.iam.gserviceaccount.com \
    --role roles/iam.workloadIdentityUser \
    --member "serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE/KSA_NAME]"

    O nome do membro tem de incluir o espaço de nomes e o nome da conta de serviço do Kubernetes. Por exemplo, serviceAccount:example-project.svc.id.goog[example-namespace/example-serviceaccount].

  6. Anote a ServiceAccount do Kubernetes para que o GKE veja a associação entre as contas de serviço:

    kubectl annotate serviceaccount KSA_NAME \
    --namespace NAMESPACE \
    iam.gke.io/gcp-service-account=IAM_SA_NAME@IAM_SA_PROJECT_ID.iam.gserviceaccount.com

    A política de autorização do IAM e a anotação são necessárias quando usa este método.

Use a federação de identidade da carga de trabalho para o GKE a partir do seu código

A autenticação nos Google Cloud serviços a partir do seu código é o mesmo processo que a autenticação através do servidor de metadados do Compute Engine. Quando usa a Workload Identity Federation para o GKE, os seus pedidos ao servidor de metadados da instância são encaminhados para o servidor de metadados do GKE. O código existente que faz a autenticação através do servidor de metadados da instância (como o código que usa as Google Cloud bibliotecas de cliente) deve funcionar sem modificações.

Use a quota de um projeto diferente com a Workload Identity Federation para o GKE

Em clusters que executam a versão 1.24 ou posterior do GKE, pode configurar opcionalmente a sua conta de serviço do Kubernetes para usar a quota de um Google Cloud projeto diferente Google Cloud quando fizer chamadas para os métodos GenerateAccessToken e GenerateIdToken na API IAM Service Account Credentials. Isto permite-lhe evitar usar toda a quota no seu projeto principal e, em alternativa, usar a quota de outros projetos para estes serviços no seu cluster.

Para configurar um projeto de quota com a federação de identidades da carga de trabalho para o GKE, faça o seguinte:

  1. Conceda a autorização serviceusage.services.use no projeto de quota à conta de serviço do Kubernetes.

    gcloud projects add-iam-policy-binding QUOTA_PROJECT_ID \
    --role=roles/serviceusage.serviceUsageConsumer \
    --member='principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME' \

    Substitua QUOTA_PROJECT_ID pelo ID do projeto do projeto de quota.

  2. Anote a conta de serviço do Kubernetes com o projeto de quota:

    kubectl annotate serviceaccount KSA_NAME \
    --namespace NAMESPACE \
    iam.gke.io/credential-quota-project=QUOTA_PROJECT_ID

Para verificar se a configuração funciona corretamente, faça o seguinte:

  1. Crie um pod e inicie uma sessão de shell. Consulte a documentação do Kubernetes para obter um shell para um contentor em execução.

  2. Faça um pedido ao servidor de metadados:

    curl -H "Metadata-Flavor: Google" http://169.254.169.254/computeMetadata/v1/instance/service-accounts/default/token

  3. Aceda à página API IAM Service Accounts Credentials na Google Cloud consola do seu projeto de quotas:

    Aceder às APIs

  4. Verifique se existem alterações no tráfego.

Limpar

Para deixar de usar a federação de identidades da carga de trabalho para o GKE, revogue o acesso à conta de serviço do IAM e desative a federação de identidades da carga de trabalho para o GKE no cluster.

Revogar acesso

Para revogar o acesso ao principal, remova a política de autorização do IAM que criou na secção Configure aplicações para usar a Workload Identity Federation para o GKE.

Por exemplo, para revogar o acesso a um repositório do Artifact Registry, execute o seguinte comando:

gcloud artifacts repositories remove-iam-policy-binding REPOSITORY_NAME \
    --location=REPOSITORY_LOCATION \
    --member='principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME' \
    --role='roles/artifactregistry.reader' \
    --all

Desative a federação de identidades de cargas de trabalho para o GKE

Só pode desativar a federação de identidade da força de trabalho para clusters do GKE no modo Standard.

gcloud

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. Desative a federação de identidades da carga de trabalho para o GKE em cada conjunto de nós:

    gcloud container node-pools update NODEPOOL_NAME \
    --cluster=CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --workload-metadata=GCE_METADATA

    Repita este comando para cada conjunto de nós no cluster.

  3. Desative a federação de identidades da força de trabalho para o GKE no cluster:

    gcloud container clusters update CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --disable-workload-identity

    4. Consola

    1. Aceda à página do Google Kubernetes Engine na Google Cloud consola.

      Aceda ao Google Kubernetes Engine

    2. Na lista de clusters, clique no nome do cluster que quer modificar.

    3. Clique no separador Nós.

    4. Para desativar a Workload Identity Federation para o GKE em cada conjunto de nós, faça o seguinte para cada conjunto de nós na secção Node Pools (Conjuntos de nós):

      1. Clique no nome do conjunto de nós que quer modificar.
      2. Na página Detalhes do conjunto de nós, clique em Editar.
      3. Na página Editar conjunto de nós, na secção Segurança, desmarque a caixa de verificação Ativar servidor de metadados do GKE.
      4. Clique em Guardar.

    5. Para desativar a federação de identidade da carga de trabalho para o GKE para o cluster, faça o seguinte:

      1. Clique no separador Detalhes.
      2. Na secção Segurança, junto a Identidade da carga de trabalho, clique em Editar.
      3. Na caixa de diálogo Editar Workload Identity, desmarque a caixa de verificação Ativar Workload Identity.
      4. Clique em Guardar alterações.

Desative a federação de identidade da carga de trabalho para o GKE na sua organização

Do ponto de vista da segurança, a federação de identidades da carga de trabalho para o GKE permite que o GKE afirme identidades de contas de serviço do Kubernetes que podem ser autenticadas e autorizadas para Google Cloud recursos. Se for um administrador que tomou medidas para isolar cargas de trabalho de Google Cloud recursos, como desativar a criação de contas de serviço ou desativar a criação de chaves de contas de serviço, também pode querer desativar a federação de identidades da carga de trabalho para o GKE na sua organização.

Consulte estas instruções para desativar a Workload Identity Federation para o GKE para a sua organização.

Resolução de problemas

Para obter informações de resolução de problemas, consulte o artigo Resolução de problemas da Workload Identity Federation para o GKE.

O que se segue?