Google utiliza tecnología de IA para traducir contenido a tu idioma preferido. Las traducciones realizadas con IA pueden contener errores.

Solicita la identidad de un agente para un agente de GKE

Autopilot Standard

Las cargas de trabajo de los agentes que implementas en clústeres de Google Kubernetes Engine (GKE) a menudo necesitan acceder a herramientas y servicios externos, ya sea como la propia identidad del agente o en nombre de los usuarios finales. Los administradores de seguridad y los administradores de la plataforma también quieren saber qué hacen los agentes implementados en los servicios de Google Cloud. En este documento, se muestra cómo configurar la autenticación para las cargas de trabajo del agente solicitando una identidad del agente para tus Pods. Esta identidad del agente te permite configurar la autenticación sin tener que administrar manualmente las credenciales para diferentes flujos de trabajo y, además, integra tus agentes de GKE con Gemini Enterprise Agent Platform. Este documento está dirigido a los desarrolladores de aplicaciones que compilan y ejecutan cargas de trabajo de agentes en clústeres de GKE.

Debes tener conocimientos generales sobre los siguientes temas:

Precios

La identidad del agente se proporciona sin costo adicional en GKE.

Limitaciones

Solo puedes registrar automáticamente las implementaciones en Agent Registry. Otros controladores de cargas de trabajo y Pods estáticos no admiten el registro automático. Aunque puedes solicitar identidades de agentes para todos los tipos de cargas de trabajo, el registro en Agent Registry te permite integrar esas identidades con Agent Platform.
Los tokens de acceso de identidad del agente vinculados solo usan el permiso de OAuth https://www.googleapis.com/auth/cloud-platform. No puedes especificar un alcance diferente para los tokens de acceso vinculados.

Antes de comenzar

Antes de comenzar, asegúrate de haber realizado las siguientes tareas:

Habilita la API de Google Kubernetes Engine.

Habilitar la API de Google Kubernetes Engine

Si deseas usar Google Cloud CLI para esta tarea, instala y, luego, inicializa gcloud CLI. Si ya instalaste la gcloud CLI, ejecuta el comando gcloud components update para obtener la versión más reciente. Es posible que las versiones anteriores de gcloud CLI no admitan la ejecución de los comandos que se indican en este documento.
Nota: Para las instalaciones de gcloud CLI existentes, asegúrate de configurar la propiedad compute/region. Si usas principalmente clústeres zonales, configura compute/zone en su lugar. Cuando configuras una ubicación predeterminada, puedes evitar errores en gcloud CLI como el siguiente: One of [--zone, --region] must be supplied: Please specify location. Es posible que debas especificar la ubicación en ciertos comandos si la ubicación de tu clúster difiere de la predeterminada que estableciste.

Habilita la API de Agent Registry si aún no está habilitada:
Roles necesarios para habilitar las APIs
Para habilitar APIs, necesitas el permiso serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol de propietario (roles/owner). De lo contrario, puedes obtener este permiso a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén más información para otorgar roles.
```
gcloud services enable agentregistry.googleapis.com
```
Verifica que tengas un clúster de Autopilot existente o un clúster de Standard que tenga habilitada la Workload Identity Federation for GKE y que ejecute la versión 1.37.0-gke.3503000 o posterior de GKE.
Verifica que tengas suficiente cuota para las operaciones de intercambio de tokens. Esta cuota se llama Exchange Workload Identity Token Requests per minute per region. Para obtener más información, consulta Cuotas y límites.

Roles obligatorios

Para obtener los permisos que necesitas para solicitar una identidad de agente y, luego, implementar cargas de trabajo, pídele a tu administrador que te otorgue el rol de IAM de Desarrollador de Kubernetes Engine (roles/container.developer) en tu proyecto Google Cloud . Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Solicita una identidad de agente para una carga de trabajo

Para obtener una identidad de agente para los Pods, agrega anotaciones a la especificación del Pod para solicitar un ID de SPIFFE para la carga de trabajo y para insertar el paquete de certificados X.509 en cada Pod. En el caso de los Pods administrados por implementaciones, también debes agregar una anotación y una etiqueta para registrar el agente en Agent Registry. Si bien el registro es opcional, solo los agentes registrados pueden usar los servicios de la Plataforma de agentes, como Agent Gateway. Para obtener más información sobre las anotaciones y etiquetas específicas, consulta Configuración a nivel de la carga de trabajo.

En los siguientes pasos, se muestra cómo crear un ejemplo de Deployment que solicita identidades de agentes:

Busca el ID de tu organización. Si tu proyecto no pertenece a una organización, omite este paso y busca el número de tu proyecto.
```
gcloud projects get-ancestors PROJECT_ID
```
Reemplaza PROJECT_ID por el ID del proyecto del clúster.

El resultado es similar a lo siguiente:
```
ID: my-project
TYPE: project
ID: 811159889184
TYPE: folder
ID: 301928500920
TYPE: organization
```
Anota el valor del campo ID para el recurso organization.
Conéctate a tu clúster:
```
gcloud container clusters get-credentials CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION
```
Reemplaza lo siguiente:
- CLUSTER_NAME: El nombre de tu clúster.
- CONTROL_PLANE_LOCATION: Es la región o zona del plano de control de tu clúster.
Crea un espacio de nombres para ejecutar la Deployment de ejemplo:
```
kubectl create namespace NAMESPACE_NAME
```
Reemplaza NAMESPACE_NAME por un nombre para el espacio de nombres.
Crea una ServiceAccount de Kubernetes para la Deployment:
```
kubectl create serviceaccount SERVICEACCOUNT_NAME \
    --namespace=NAMESPACE_NAME
```
Reemplaza SERVICEACCOUNT_NAME por un nombre para la ServiceAccount.

Guarda el siguiente manifiesto de Deployment 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"]

Reemplaza TRUST_DOMAIN por el dominio de confianza que emite identidades para los agentes de tu proyecto. Este valor debe usar una de las siguientes sintaxis, según si tu proyecto pertenece a una organización:

Proyectos que pertenecen a una organización: agents.global.org-ORGANIZATION_ID.system.id.goog, donde ORGANIZATION_ID es el ID de la organización.
Proyectos que no pertenecen a una organización: agents.global.proj-PROJECT_NUMBER.system.id.goog, donde PROJECT_NUMBER es el número del proyecto del clúster.

Esta implementación solicita una identidad de agente para la carga de trabajo, agrega los certificados X.509 por Pod a los Pods y registra el agente en el registro de agentes.

Crea el Deployment:

kubectl apply -f agent-identity-deployment.yaml

Verifique que los pods se estén ejecutando:

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

Verifica la identidad del agente asignado

Después de implementar una carga de trabajo que solicita una identidad de agente, puedes verificar la identidad consultando los certificados X.509. Si inhabilitas la inserción de certificados, puedes obtener un token de identidad no vinculado del servidor de metadatos de GKE para verificar el campo del asunto, como se describe en Autenticación en las APIs de Google Cloud .

Para leer el certificado X.509 en un Pod, sigue estos pasos:

Comprueba si un Pod tiene acceso al certificado X.509 y a la clave privada:
```
kubectl get pod POD_NAME -n NAMESPACE_NAME \
    -o=jsonpath='{range .spec.volumes[*]}{.name}{"\n"}{end}'
```
Reemplaza POD_NAME por el nombre de un Pod que usa la identidad del agente.

El resultado es similar a lo siguiente:
```
kube-api-access-bx86g
gke-workload-spiffe-credentials
```
En este resultado, el volumen gke-workload-spiffe-credentials es la ubicación de los certificados insertados. Si no ves este volumen, verifica que la anotación iam.gke.io/inject-podcertificates esté establecida en un valor de true en la especificación del Pod.

Crea una sesión de shell interactiva en el Pod:

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

En la sesión de shell, enumera las credenciales en el volumen gke-workload-spiffe-credentials:
```
ls -1 /var/run/secrets/workload-spiffe-credentials/
```
El resultado es similar a lo siguiente:
```
x509.credential-bundle.private-key.pem
TRUST_DOMAIN.spiffe-trust-bundle.pem
```
El resultado muestra los siguientes archivos:
- x509.credential-bundle.private-key.pem: Es el paquete de credenciales de identidad del agente, que incluye la cadena de certificados X.509 y una clave privada que es única para el Pod. Este paquete de credenciales se usa para solicitar tokens de acceso y tokens de ID, y para autenticarse en las APIs de Google Cloudcon mTLS.
- TRUST_DOMAIN.spiffe-trust-bundle.pem: Es el paquete de confianza de la AC raíz, que contiene los certificados autofirmados que forman el ancla de confianza para las credenciales de identidad del agente. Este paquete de confianza se usa principalmente para validar certificados TLS de otras cargas de trabajo durante los protocolos de enlace mTLS.

Para obtener el ID de SPIFFE asociado con el Pod, lee el certificado X.509:

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

El resultado es similar a lo siguiente:

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

En este resultado, el valor que se encuentra en el campo URI para el campo X509v3 Subject Alternative Name es el ID de SPIFFE del agente.

Si tu Pod de agente tiene un ID de SPIFFE asignado, tu solicitud de identidad de agente se realizó correctamente. Puedes usar la identidad asignada para autenticarte en varias herramientas y servicios.