O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Solicitar uma identidade de agente para um agente do GKE

Autopilot Standard

As cargas de trabalho do agente implantadas em clusters do Google Kubernetes Engine (GKE) geralmente precisam acessar ferramentas e serviços externos, seja como a própria identidade do agente ou em nome dos usuários finais. Os administradores de segurança e de plataforma também querem saber o que os agentes implantados fazem nos serviços do Google Cloud. Neste documento, mostramos como configurar a autenticação para cargas de trabalho de agente solicitando uma identidade do agente para seus pods. Essa identidade de agente permite configurar a autenticação sem precisar gerenciar manualmente as credenciais para diferentes fluxos de trabalho e integra seus agentes do GKE à Gemini Enterprise Agent Platform. Este documento é destinado a desenvolvedores de aplicativos que criam e executam cargas de trabalho de agentes em clusters do GKE.

Você já precisa conhecer os seguintes tópicos:

Preços

A identidade do agente é fornecida sem custo financeiro adicional no GKE.

Limitações

É possível registrar automaticamente apenas implantações no Agent Registry. Outros controladores de carga de trabalho e pods estáticos não oferecem suporte ao registro automático. Embora seja possível solicitar identidades de agente para todos os tipos de carga de trabalho, o registro no Agent Registry permite integrar essas identidades à Agent Platform.
Os tokens de acesso de identidade do agente vinculados usam apenas o escopo OAuth https://www.googleapis.com/auth/cloud-platform. Não é possível especificar um escopo diferente para os tokens de acesso vinculados.

Antes de começar

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

Ative a API Google Kubernetes Engine.

Ativar a API Google Kubernetes Engine

Se você quiser usar a Google Cloud CLI para essa tarefa, instale e inicialize a CLI gcloud. Se você instalou a CLI gcloud anteriormente, instale a versão mais recente executando o comando gcloud components update. Talvez as versões anteriores da CLI gcloud não sejam compatíveis com a execução dos comandos neste documento.
Observação:em instalações prévias da CLI gcloud, defina a propriedade compute/region. Se você usa principalmente clusters zonais, defina compute/zone. Ao definir um local padrão, é possível evitar erros na CLI gcloud como: One of [--zone, --region] must be supplied: Please specify location. Talvez seja necessário especificar o local em determinados comandos se o local do cluster for diferente do padrão definido.

Ative a API Agent Registry, se ela ainda não estiver ativada:
Funções necessárias para ativar APIs
Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de Proprietário (roles/owner). Caso contrário, é possível receber essa permissão pelo papel de Administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.
```
gcloud services enable agentregistry.googleapis.com
```
Verifique se você tem um cluster do Autopilot ou um cluster padrão com a Federação de Identidade da Carga de Trabalho para GKE ativada e que executa a versão 1.37.0-gke.3503000 ou mais recente do GKE.
Verifique se você tem cota suficiente para operações de troca de tokens. Essa cota tem o nome Solicitações de token de identidade da carga de trabalho do Exchange por minuto e região. Para mais informações, consulte Cotas e limites.

Funções exigidas

Para receber as permissões necessárias para solicitar uma identidade de agente e implantar cargas de trabalho, peça ao administrador para conceder a você o papel do IAM de Desenvolvedor do Kubernetes Engine (roles/container.developer) no seu projeto Google Cloud . Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Solicitar uma identidade de agente para uma carga de trabalho

Para receber uma identidade de agente para pods, adicione anotações à especificação do pod para solicitar um ID do SPIFFE para a carga de trabalho e injetar o pacote de certificados X.509 em cada pod. Para pods gerenciados por implantações, também é necessário adicionar uma anotação e um rótulo para registrar o agente no Agent Registry. Embora o registro seja opcional, apenas agentes registrados podem usar serviços da Agent Platform, como o Gateway de Agente. Para mais informações sobre as anotações e rótulos específicos, consulte Configuração no nível da carga de trabalho.

As etapas a seguir mostram como criar uma implantação de exemplo que solicita identidades de agente:

Encontre o ID da sua organização. Se o projeto não estiver em uma organização, pule esta etapa e encontre o número do projeto.
```
gcloud projects get-ancestors PROJECT_ID
```
Substitua PROJECT_ID pelo ID do projeto de cluster.

O resultado será o seguinte:
```
ID: my-project
TYPE: project
ID: 811159889184
TYPE: folder
ID: 301928500920
TYPE: organization
```
Anote o valor no campo ID do recurso organization.
Conecte-se ao cluster:
```
gcloud container clusters get-credentials CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION
```
Substitua:
- CLUSTER_NAME: o nome do cluster.
- CONTROL_PLANE_LOCATION: a região ou zona do plano de controle do cluster.
Crie um namespace para executar a implantação de exemplo:
```
kubectl create namespace NAMESPACE_NAME
```
Substitua NAMESPACE_NAME por um nome para o namespace.
Crie uma conta de serviço do Kubernetes para a implantação:
```
kubectl create serviceaccount SERVICEACCOUNT_NAME \
    --namespace=NAMESPACE_NAME
```
Substitua SERVICEACCOUNT_NAME por um nome para a conta de serviço.

Salve o seguinte manifesto de implantação como agent-identity-deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: agent-identity-deployment
  namespace: NAMESPACE_NAME
  # Add the agent to Agent Registry
  labels:
    registry.gke.io/functional-type: "AGENT"
  annotations:
    # A2A protocol metadata annotation for automated Agent Card discovery
    a2a-protocol.org/agent-card: |
      card:
        endpoint: /.well-known/agent-card.json
        protocol: HTTP
        port: 8080
spec:
  replicas: 2
  selector:
    matchLabels:
      workload-type: agent
  template:
    metadata:
      name: agent-identity-pod
      annotations:
        iam.gke.io/identity: "spiffe://TRUST_DOMAIN/*" # The trust domain from which to assign SPIFFE IDs.
        iam.gke.io/inject-podcertificates: "true" # Inject X.509 certificates and per-Pod private key into each Pod.
        iam.gke.io/spiffe-identity-type: "agent-identity" # Required for Agent Registry registration.
      labels:
        workload-type: agent
    spec:
      serviceAccountName: SERVICEACCOUNT_NAME
      containers:
      - name: agent
        image: python:3.11-slim
        command: ["sleep","infinity"]

Substitua TRUST_DOMAIN pelo domínio de confiança que emite identidades para agentes no seu projeto. Esse valor precisa usar uma das seguintes sintaxes, dependendo se o projeto está em uma organização:

Projetos em uma organização: agents.global.org-ORGANIZATION_ID.system.id.goog, em que ORGANIZATION_ID é o ID da organização.
Projetos que não estão em uma organização: agents.global.proj-PROJECT_NUMBER.system.id.goog, em que PROJECT_NUMBER é o número do projeto do projeto do cluster.

Essa implantação solicita uma identidade de agente para a carga de trabalho, adiciona os certificados X.509 por pod aos pods e registra o agente no Registro de agentes.

Crie a implantação:

kubectl apply -f agent-identity-deployment.yaml

Verifique se os pods estão em execução:

kubectl get pods -l workload-type=agent -n NAMESPACE_NAME

Verificar a identidade do agente atribuído

Depois de implantar uma carga de trabalho que solicita uma identidade de agente, é possível verificar a identidade conferindo os certificados X.509. Se você desativar a injeção de certificado, poderá receber um token de identidade não vinculado do servidor de metadados do GKE para verificar o campo de assunto, conforme descrito em Autenticar em APIs do Google Cloud .

Para ler o certificado X.509 em um pod, siga estas etapas:

Verifique se um pod tem acesso ao certificado X.509 e à chave privada:
```
kubectl get pod POD_NAME -n NAMESPACE_NAME \
    -o=jsonpath='{range .spec.volumes[*]}{.name}{"\n"}{end}'
```
Substitua POD_NAME pelo nome de um pod que usa a identidade do agente.

O resultado será o seguinte:
```
kube-api-access-bx86g
gke-workload-spiffe-credentials
```
Nessa saída, o volume gke-workload-spiffe-credentials é o local dos certificados injetados. Se você não encontrar esse volume, verifique se a anotação iam.gke.io/inject-podcertificates está definida como true na especificação do pod.

Crie uma sessão interativa do shell no pod:

kubectl exec -n NAMESPACE_NAME -it POD_NAME -- /bin/bash

Na sessão do shell, liste as credenciais no volume gke-workload-spiffe-credentials:
```
ls -1 /var/run/secrets/workload-spiffe-credentials/
```
O resultado será o seguinte:
```
x509.credential-bundle.private-key.pem
TRUST_DOMAIN.spiffe-trust-bundle.pem
```
A saída mostra os seguintes arquivos:
- x509.credential-bundle.private-key.pem: o pacote de credenciais de identidade do agente, que inclui a cadeia de certificados X.509 e uma chave privada exclusiva do pod. Esse pacote de credenciais é usado para solicitar tokens de acesso e tokens de ID e para autenticar APIs do Google Cloud usando mTLS.
- TRUST_DOMAIN.spiffe-trust-bundle.pem: o pacote de confiança da CA raiz, que contém os certificados autoassinados que formam a âncora de confiança para as credenciais de identidade do agente. Esse pacote de confiança é usado principalmente para validar certificados TLS de outras cargas de trabalho durante handshakes de mTLS.

Para receber o ID do SPIFFE associado ao pod, leia o certificado X.509:

openssl x509 -in /var/run/secrets/workload-spiffe-credentials/x509.credential-bundle.private-key.pem -text -noout

O resultado será o seguinte:

Certificate:
    Data:
    # Multiple lines are omitted here
        X509v3 extensions:
            # Multiple lines are omitted here
            X509v3 Subject Alternative Name: critical
                URI:spiffe://agents.global.org-301928500920.system.id.goog/resources/container/projects/729788050015/locations/us-central1/clusters/cluster-2/ns/agent-identity-ns/sa/agent-identity-sa
    # Multiple lines are omitted here

Nessa saída, o valor no campo URI para o campo X509v3 Subject Alternative Name é o ID do SPIFFE do agente.

Se o pod do agente tiver um ID do SPIFFE atribuído, sua solicitação de uma identidade do agente será bem-sucedida. É possível usar a identidade atribuída para autenticar várias ferramentas e serviços.