Autenticar as APIs do Google Cloud nas cargas de trabalho do GKE

Neste documento, mostramos como acessar com mais segurança as APIs do Google Cloud das cargas de trabalho em execução nos clusters do Google Kubernetes Engine (GKE) usando a federação de identidade da carga de trabalho para GKE. Para saber mais, consulte Federação de identidade da carga de trabalho para o GKE.

Antes de começar

Antes de começar, verifique se você realizou as tarefas a seguir:

  • Ativar a API Google Kubernetes Engine.
    • Ativar a API Google Kubernetes Engine
  • Se você quiser usar a Google Cloud CLI para essa tarefa, instale e, em seguida, inicialize a CLI gcloud. Se você instalou a CLI gcloud anteriormente, instale a versão mais recente executando gcloud components update.

Ativar a federação de identidade da carga de trabalho para o GKE em clusters e pools de nós

No Autopilot, a federação de identidade da carga de trabalho para o GKE está sempre ativada. Pule para a seção Configurar aplicativos para usar a federação de identidade da carga de trabalho para o GKE.

No Standard, você ativa a federação de identidade da carga de trabalho para o GKE em clusters e pools de nós usando a CLI do Google Cloud ou o console do Google Cloud. A federação de identidade da carga de trabalho do GKE precisa estar ativada no nível do cluster antes de ser ativada para o GKE em pools de nós.

Criar um novo cluster

É possível ativar a federação de identidade da carga de trabalho para o GKE em um novo cluster padrão usando a gcloud CLI ou o console do Google Cloud.

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 em um novo cluster, execute o seguinte comando:

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

    Substitua:

    • CLUSTER_NAME: o nome do novo cluster;
    • LOCATION: a região do Compute Engine para o cluster.
    • PROJECT_ID: é seu ID do projeto no Google Cloud.

Console

Para ativar a federação de identidade da carga de trabalho para o GKE em um novo cluster, faça o seguinte:

  1. Acesse a página Google Kubernetes Engine no console do Google Cloud.

    Acessar o Google Kubernetes Engine

  2. Clique em Criar.

  3. Na caixa de diálogo Criar cluster do GKE Standard, clique em Configurar.

  4. No menu de navegação, na seção Cluster, clique em Segurança.

  5. Marque a caixa de seleção Ativar identidade de carga de trabalho.

  6. Continue configurando o cluster e clique em Criar.

Atualizar um cluster atual

É possível ativar a federação de identidade da carga de trabalho para o GKE em um cluster padrão atual usando a gcloud CLI ou o console do Google Cloud. Os pools de nós atuais não são afetados, mas todos os novos pools de nós no cluster usam a federação de identidade da carga de trabalho 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 em um cluster, execute o seguinte comando:

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

    Substitua:

    • CLUSTER_NAME: o nome do cluster atual.
    • LOCATION: o local do Compute Engine do cluster.
    • PROJECT_ID: é seu ID do projeto no Google Cloud.

Console

Para ativar a federação de identidade da carga de trabalho para o GKE em um cluster atual, faça o seguinte:

  1. Acesse a página do Google Kubernetes Engine no console do Google Cloud.

    Acessar o Google Kubernetes Engine

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

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

  4. Na caixa de diálogo Editar Identidade da carga de trabalho, marque a caixa de seleção Ativar Identidade da carga de trabalho.

  5. Clique em Salvar.

Migrar as cargas de trabalho atuais para a federação de identidade da carga de trabalho do GKE

Depois de ativar a federação de identidade da carga de trabalho para o GKE em um cluster atual, migre as cargas de trabalho em execução para usar a federação de identidade da carga de trabalho para o GKE. Selecione a estratégia de migração ideal para seu ambiente. É possível criar novos pools de nós com a federação de identidade da carga de trabalho para o GKE ativada ou atualizar os pools de nós atuais para ativar a federação de identidade da carga de trabalho para o GKE.

.

Recomendamos a criação de novos pools de nós se você também precisar modificar seus aplicativos para que sejam compatíveis com a federação de identidade da carga de trabalho do GKE.

Todos os novos pools de nós criados por padrão para usar a federação de identidade da carga de trabalho do GKE, se o cluster estiver com esse recurso ativado. Para criar um novo pool de nós com a federação de identidade da carga de trabalho para GKE ativada, execute o seguinte comando:

gcloud container node-pools create NODEPOOL_NAME \
    --cluster=CLUSTER_NAME \
    --region=COMPUTE_REGION \
    --workload-metadata=GKE_METADATA

Substitua:

  • NODEPOOL_NAME: o nome do novo pool de nós.
  • CLUSTER_NAME: o nome do cluster atual que tem a federação de identidade da carga de trabalho para o GKE ativada.

A sinalização --workload-metadata=GKE_METADATA configura o pool de nós para usar o servidor de metadados do GKE. Recomendamos que você inclua a flag para que a criação do pool de nós falhe se a federação de identidade da carga de trabalho para o GKE não estiver ativada no cluster.

Atualizar um pool de nós

É possível ativar manualmente a federação de identidade da carga de trabalho para o GKE em pools de nós atuais depois de ativar a federação de identidade da carga 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 pool de nós atual e usar a federação de identidade da carga de trabalho para o GKE, execute o seguinte comando:

    gcloud container node-pools update NODEPOOL_NAME \
    --cluster=CLUSTER_NAME \
    --region=COMPUTE_REGION \
    --workload-metadata=GKE_METADATA

    Se um cluster tiver a federação de identidade da carga de trabalho para GKE ativada, será possível desativá-la seletivamente em um pool de nós específico especificando explicitamente --workload-metadata=GCE_METADATA. Consulte Como proteger os metadados do cluster para mais informações.

Console

Para modificar um pool de nós atual e usar a federação de identidade da carga de trabalho para o GKE, siga estas etapas:

  1. Acesse a página do Google Kubernetes Engine no console do Google Cloud.

    Acessar o Google Kubernetes Engine

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

  3. Clique na guia Nós.

  4. Na seção Pool de nós, clique no nome do pool de nós que você quer redimensionar.

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

  6. Na página Editar pool de nós, na seção Segurança, marque a caixa de seleção Ativar servidor de metadados do GKE.

  7. Clique em Salvar.

Configurar aplicativos para usar a federação de identidade da carga de trabalho para o GKE

Para permitir que seus aplicativos do GKE sejam autenticados nas APIs do Google Cloud usando a federação de identidade da carga de trabalho para GKE, crie políticas do IAM para as APIs específicas. O principal nessas políticas é um identificador principal do IAM que corresponde a cargas de trabalho, namespaces ou ServiceAccounts.

Configurar autorização e principais

  1. Receba as credenciais do cluster:

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

    Substitua:

    • CLUSTER_NAME: o nome do cluster com a federação de identidade da carga de trabalho para o GKE ativada.
    • LOCATION: o local do cluster.

  2. Crie o namespace que será usado para a conta de serviço do Kubernetes. Também é possível usar o namespace default ou qualquer namespace existente.

    kubectl create namespace NAMESPACE

  3. Crie uma conta de serviço do Kubernetes para o aplicativo usar. Também é possível usar qualquer Kubernetes ServiceAccount atual em qualquer namespace. Se você não atribuir uma ServiceAccount à carga de trabalho, o Kubernetes atribuirá a default ServiceAccount no namespace.

    kubectl create serviceaccount KSA_NAME \
    --namespace NAMESPACE

    Substitua:

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

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

    Por exemplo, o comando a seguir concede o papel de leitor de cluster do Kubernetes Engine (roles/container.clusterViewer) à conta de serviço que você 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:

    • PROJECT_ID: é seu ID do projeto no Google Cloud.
    • PROJECT_NUMBER: o número numérico do projeto do Google Cloud.

    É possível conceder papéis em qualquer recurso do Google Cloud compatível com políticas de permissão do IAM. A sintaxe do identificador principal depende do recurso do Kubernetes. Para uma lista de identificadores compatíveis, consulte Identificadores principais da federação de identidade da carga de trabalho do GKE.

Verificar a federação de identidade da carga de trabalho para a configuração do GKE

Nesta seção, você cria um bucket do Cloud Storage e concede acesso de visualização nele à conta de serviço do Kubernetes criada na seção anterior. Em seguida, implante uma carga de trabalho e teste se o contêiner pode listar clusters no projeto.

  1. Crie um bucket vazio do Cloud Storage:

    gcloud storage buckets create gs://BUCKET

    Substitua BUCKET por um nome para o novo bucket.

  2. Conceda o papel Leitor de objetos do Storage (roles/storage.objectViewer) à conta de serviço que você 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:

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

  3. Salve 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. Somente em clusters padrão, adicione o seguinte ao campo template.spec para colocar os pods em pools de nós que usam a federação de identidade da carga de trabalho para o GKE.

    Pule esta etapa nos clusters do Autopilot, que rejeitam esse nodeSeletor porque todos os nós usam a federação de identidade da carga de trabalho para o GKE.

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

  5. Aplique a configuração ao seu cluster:

    kubectl apply -f test-app.yaml

  6. Aguarde até que o pod esteja pronto. Para verificar o status do pod, execute o comando abaixo:

    kubectl get pods --namespace=NAMESPACE

    Quando o Pod estiver pronto, a saída será semelhante a esta:

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

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

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

  8. Receba uma lista de objetos do bucket:

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

    A saída é esta:

    {
  "kind": "storage#objects"
}

    Essa saída mostra que o pod pode acessar objetos no bucket.

Alternativa: vincular as contas de serviço do Kubernetes ao IAM

Recomendamos que você use os identificadores principais do IAM para configurar a federação de identidade da carga de trabalho para o GKE. No entanto, essa identidade federada tem limitações específicas para cada API do Google Cloud compatível. Para ver uma lista de limitações, consulte Produtos com suporte e limitações.

Se essas limitações se aplicarem a você, use as etapas a seguir para configurar o acesso a essas APIs a partir das cargas de trabalho do GKE:

  1. Crie um namespace do Kubernetes:

    kubectl create namespace NAMESPACE

  2. Crie uma ServiceAccount do Kubernetes:

    kubectl create serviceaccount KSA_NAME \
    --namespace=NAMESPACE

  3. Criar uma conta de serviço do IAM Também é possível usar qualquer conta de serviço do IAM atual em qualquer projeto da organização.

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

    Substitua:

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

    Para ver informações sobre como autorizar contas de serviço do Google a acessar as APIs do Google Cloud, consulte Como entender as contas de serviço.

  4. Conceda à sua conta de serviço do IAM os papéis necessários em APIs específicas do Google Cloud:

    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 do papel, como roles/spanner.viewer.

  5. Crie uma política do IAM que conceda à ServiceAccount do Kubernetes acesso para personificar 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 \
    --role roles/iam.workloadIdentityUser \
    --member "serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE/KSA_NAME]"

    O nome do membro precisa incluir o namespace e a conta de serviço do Kubernetes do usuário. Por exemplo, serviceAccount:example-project.svc.id.goog[example-namespace/example-serviceaccount]

  6. Anote a ServiceAccount do Kubernetes para que o GKE veja o link 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

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

A autenticação nos serviços do Google Cloud usando o código segue o mesmo processo que a autenticação usando o servidor de metadados do Compute Engine. Quando você usa a federação de identidade da carga de trabalho para o GKE, suas solicitações para o servidor de metadados da instância são roteadas para o servidor de metadados do GKE. O código atual que autentica usando o servidor de metadados da instância (como o código que usa as bibliotecas de cliente do Google Cloud) funcionará sem precisar de modificações.

Usar cota de um projeto diferente com a federação de identidade da carga de trabalho para o GKE

Em clusters que executam o GKE na versão 1.24 ou posterior, é possível configurar a conta de serviço do Kubernetes para usar a cota de um projeto diferente do Google Cloud ao fazer chamadas para os métodos GenerateAccessToken e GenerateIdToken na API Service Account Credentials do IAM. Isso permite evitar o uso de toda a cota no projeto principal e, em vez disso, usar cota de outros projetos para os serviços no cluster.

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

  1. Conceda a permissão serviceusage.services.use no projeto de cota à 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 da cota.

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

    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. Criar um pod e iniciar uma sessão de shell. Consulte a documentação do Kubernetes para Obter um shell para um contêiner em execução.

  2. Faça uma solicitação ao servidor de metadados:

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

  3. Acesse a página API IAM Service Accounts Credentials no console do Google Cloud do seu projeto de cota:

    Acesse APIs

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

Limpar

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

Revogação do acesso

Para revogar o acesso ao principal, remova a política de permissão do IAM que você criou na seção Configurar aplicativos para usar a federação de identidade da carga de trabalho 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

Desativar a federação de identidade da carga de trabalho para o GKE

Só é possível desativar a federação de identidade da carga de trabalho para clusters do GKE 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 identidade da carga de trabalho para o GKE em cada pool de nós:

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

    Repita esse comando em cada pool de nós no cluster.

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

    gcloud container clusters update CLUSTER_NAME \
    --disable-workload-identity

Console

  1. Acesse a página do Google Kubernetes Engine no console do Google Cloud.

    Acessar o Google Kubernetes Engine

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

  3. Clique na guia Nós.

  4. Para desativar a federação de identidade da carga de trabalho do GKE em cada pool de nós, faça o seguinte para cada pool de nós na seção Pools de nós:

    1. Clique no nome do pool de nós que você quer modificar.
    2. Na página Detalhes do pool de nós, clique em Editar.
    3. Na página Editar pool de nós, na seção Segurança, desmarque a caixa de seleção Ativar servidor de metadados do GKE.
    4. Clique em Salvar.

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

    1. Clique na guia Detalhes.
    2. Na seção Segurança, ao lado de Identidade da carga de trabalho, clique em Editar.
    3. Na caixa de diálogo Editar Identidade da carga de trabalho, desmarque a caixa de seleção Ativar Identidade da carga de trabalho.
    4. Clique em Salvar.

Desativar 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 identidade da carga de trabalho para GKE permite que o GKE declare identidades de conta de serviço do Kubernetes que podem ser autenticadas e autorizadas nos recursos do Google Cloud. Se você é um administrador que realizou ações para isolar cargas de trabalho de recursos do Google Cloud, como desativar a criação de contas de serviço ou desativar a criação de chave de contas de serviço, talvez também queira desativar a federação de identidade da carga de trabalho para sua organização.

Consulte estas instruções para desativar a federação de identidade da carga de trabalho do GKE na sua organização.

Solução de problemas

Para informações sobre solução de problemas, consulte Solução de problemas da federação de identidade da carga de trabalho para o GKE.

A seguir