Configura Agent Gateway para multinube

En esta guía, se explica cómo implementar Agent Gateway para multinube en clústeres de Kubernetes estándar para extender la administración de Gemini Enterprise Agent Platform a tu entorno. Para obtener una descripción general de la arquitectura de tres planos, consulta la descripción general de Agent Gateway para multinube.

Antes de comenzar

Antes de comenzar, asegúrate de tener lo siguiente:

  • Un clúster de Kubernetes que cumple con la Cloud Native Computing Foundation (CNCF)
  • Una malla de servicios o una pila de red existentes configuradas en tu clúster.
  • Conectividad de red saliente desde tu clúster a las APIs de Google Cloud a través de HTTPS (puerto TCP 443).
  • La versión 591.0.0 o posterior de Google Cloud CLI instalada. Para actualizar a la versión más reciente, ejecuta gcloud components update.
  • Los roles de Identity and Access Management (IAM) en tu proyecto de Google Cloud que necesitas para habilitar las APIs, crear un grupo de identidades para cargas de trabajo y un proveedor, y otorgar roles de IAM.

Habilita las APIs y registra el clúster

Habilita las APIs de Google Cloud necesarias y, luego, registra tu clúster externo.

Habilite las API necesarias

Para habilitar las APIs que requiere Agent Gateway para multinube, ejecuta el siguiente comando:

gcloud services enable \
    agentregistry.googleapis.com \
    apphubendpoint.googleapis.com \
    cloudresourcemanager.googleapis.com \
    cloudtrace.googleapis.com \
    iam.googleapis.com \
    iamcredentials.googleapis.com \
    iap.googleapis.com \
    logging.googleapis.com \
    modelarmor.googleapis.com \
    monitoring.googleapis.com \
    networkservices.googleapis.com \
    serviceextensions.googleapis.com \
    sts.googleapis.com \
    telemetry.googleapis.com \
    trafficdirector.googleapis.com \
    --project=PROJECT_ID

Reemplaza PROJECT_ID por el ID de tu proyecto deGoogle Cloud .

Extrae la clave pública del servidor de la API de Kubernetes

Para registrar tu clúster, necesitas la clave pública que usa el clúster para firmar los tokens de la cuenta de servicio. Para extraer la clave pública, haz lo siguiente:

  1. Establece el contexto actual de kubectl en el clúster que deseas registrar.

  2. Recupera el conjunto de claves web JSON (JWKS) de tu clúster y, luego, convierte la primera clave RSA en un archivo de clave pública llamado pubkey.pem:

    kubectl get --raw /openid/v1/jwks > cluster-jwks.json
    
    N_HEX=$(jq -r '[.keys[] | select((.kty // "" | ascii_upcase) == "RSA" and (.n // "") != "" and (.e // "") != "")][0].n | gsub("-";"+") | gsub("_";"/") | . + ("==="[:(4 - length % 4) % 4])' cluster-jwks.json | base64 -d | od -An -tx1 | tr -d ' \n')
    E_HEX=$(jq -r '[.keys[] | select((.kty // "" | ascii_upcase) == "RSA" and (.n // "") != "" and (.e // "") != "")][0].e | gsub("-";"+") | gsub("_";"/") | . + ("==="[:(4 - length % 4) % 4])' cluster-jwks.json | base64 -d | od -An -tx1 | tr -d ' \n')
    
    openssl asn1parse -genconf <(printf "asn1=SEQUENCE:rsa_key\n[rsa_key]\nmodulus=INTEGER:0x%s\nexponent=INTEGER:0x%s\n" "$N_HEX" "$E_HEX") -noout -out /dev/stdout \
      | openssl rsa -RSAPublicKey_in -inform DER -pubout -out pubkey.pem
    

    Estos comandos requieren una shell de Bash y las utilidades jq y openssl.

Registre el clúster

Para registrar tu clúster, haz lo siguiente:

  1. Recupera la URL de la entidad emisora de OpenID Connect (OIDC) de tu clúster:

    kubectl get --raw /.well-known/openid-configuration | jq -r '.issuer'
    

    El resultado es el valor de la marca --service-account-issuer del servidor de la API de Kubernetes de tu clúster. Este valor puede diferir de la URL externa del servidor de la API de Kubernetes. Copia el resultado exactamente. No agregues ni quites una barra final.

  2. Registra el clúster:

    gcloud alpha network-services registered-clusters create CLUSTER_NAME \
        --project=PROJECT_ID \
        --location=LOCATION \
        --oidc-issuer-url=OIDC_ISSUER_URL \
        --api-server-public-key="$(cat pubkey.pem)"
    

    Reemplaza lo siguiente:

    • CLUSTER_NAME: Es un nombre para el clúster registrado.
    • PROJECT_ID: Es el ID de tu proyecto de Google Cloud.
    • LOCATION: Es la región de Google Cloud para el clúster registrado, por ejemplo, us-central1.
    • OIDC_ISSUER_URL: Es la URL exacta de la entidad emisora que recuperaste en el paso anterior. La URL debe comenzar con https://.

Evita la eliminación accidental de recursos

Borrar tu proyecto de Google Cloud o cancelar el registro de un clúster registrado mientras las cargas de trabajo multinube están activas desconecta los controladores en el clúster y interrumpe la aplicación de políticas. Para proteger tus recursos de Google Cloud de la eliminación accidental, aplica las siguientes protecciones:

  • Protege el proyecto de Google Cloud con retenciones: Aplica una retención de proyecto al proyecto deGoogle Cloud que aloja tu clúster registrado, Agent Registry y los grupos de identidades federadas para bloquear la eliminación accidental del proyecto hasta que se den de baja todos los clústeres de varias nubes.
  • Restringe los permisos de IAM destructivos: Limita los permisos que pueden borrar clústeres registrados o recursos de puerta de enlace (como networkservices.registeredClusters.delete y networkservices.agentGateways.delete) a roles de administrador de plataforma dedicados.
  • Conserva los finalizadores de recursos de Kubernetes: No quites los finalizadores de los recursos personalizados en el clúster que administra el controlador agent-governance-cross-cloud-controller. Los finalizadores garantizan que los registros del plano de control de Google Cloud correspondientes se desaprovisionen de forma limpia antes de que se quiten los recursos del clúster local.
  • Borra los recursos personalizados antes de quitar el controlador: Antes de desinstalar el gráfico de Helm de agent-governance-cross-cloud o borrar tu clúster de Kubernetes, borra todos los recursos personalizados GCPExtensionBinding y GCPAgentGateway, y espera a que se complete la eliminación. Si quitas primero el controlador, el recurso de Agent Gateway correspondiente permanecerá huérfano en Network Services. La puerta de enlace huérfana bloquea la eliminación de la plantilla de conectividad del agente y del clúster registrado.

Configura la federación de identidades para cargas de trabajo

Los componentes en el clúster de Agent Gateway para multinube (el controlador de agent-governance-cross-cloud-controller, el recopilador de telemetría y el proxy) usan la federación de identidades para cargas de trabajo para autenticarse en las APIs deGoogle Cloud . Cada componente intercambia su token de cuenta de servicio de Kubernetes (KSA) por un token de acceso federado. Otorgas roles de IAM directamente a estas identidades federadas, por lo que no necesitas crear cuentas de servicio deGoogle Cloud ni almacenar claves de cuentas de servicio en tu clúster.

El archivo adicional de Agent Identity Runtime (AIR) que se ejecuta con cada proxy usa el grupo de identidades para cargas de trabajo para proporcionar identidades de SPIFFE a tus cargas de trabajo de agentes. Estas identidades son las identidades de agente de tus agentes. Las políticas de Model Armor y de IAP identifican a los agentes por su identidad de agente, no por las identidades federadas de los componentes del clúster. Para conocer el formato de la principal, consulta Identifica la principal del agente.

Crea un proveedor y un grupo de identidades para cargas de trabajo

Para crear un grupo de identidades para cargas de trabajo y un proveedor de OIDC para tu clúster, haz lo siguiente:

  1. Si no se puede acceder públicamente a la URL del emisor de OIDC de tu clúster, guarda el conjunto de claves web JSON (JWKS) de tu clúster en un archivo:

    kubectl get --raw /openid/v1/jwks > cluster-jwks.json
    

    Cuando proporcionas el JWKS al proveedor, Google Cloud puede verificar los tokens de KSA sin conectarse al emisor de OIDC de tu clúster.

  2. Crea un grupo de identidades para cargas de trabajo:

    gcloud iam workload-identity-pools create POOL_ID \
        --project=PROJECT_ID \
        --location=global \
        --display-name="POOL_DISPLAY_NAME"
    
  3. Crea un proveedor de OIDC en el grupo:

    gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
        --project=PROJECT_ID \
        --location=global \
        --workload-identity-pool=POOL_ID \
        --issuer-uri=OIDC_ISSUER_URL \
        --jwk-json-path=cluster-jwks.json \
        --attribute-mapping="google.subject=assertion.sub,attribute.namespace=assertion['kubernetes.io']['namespace'],attribute.service_account=assertion['kubernetes.io']['serviceaccount']['name']"
    

    No especifiques la marca --allowed-audiences. Los componentes multinube solicitan tokens para el público predeterminado, que es el nombre de recurso completo del proveedor: //iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID.

Reemplaza lo siguiente:

  • POOL_ID: Es un ID para el grupo de identidades para cargas de trabajo.
  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • POOL_DISPLAY_NAME: Es un nombre visible para el grupo.
  • PROVIDER_ID: Es un ID para el proveedor de OIDC.
  • OIDC_ISSUER_URL: Es la URL exacta de la entidad emisora de OIDC que recuperaste cuando registraste el clúster. Este valor debe coincidir con el que pasaste a --oidc-issuer-url, incluso si termina con una barra diagonal.

Implementa el plano de control

Usa el gráfico de Helm proporcionado para implementar el controlador en el clúster, agent-governance-cross-cloud-controller y el recopilador de telemetría en el espacio de nombres geap-system.

Asegúrate de que el control tenga conectividad

Asegúrate de que el firewall, el proxy, las reglas de salida y las políticas de red del clúster permitan la siguiente conectividad:

  • APIs deGoogle Cloud : Los Pods del controlador de agent-governance-cross-cloud-controller y el recopilador de telemetría deben tener conectividad HTTPS y gRPC saliente en el puerto TCP 443 a *.googleapis.com.
  • Servidor de la API de Kubernetes: Los Pods del controlador deben poder acceder al servidor de la API de Kubernetes para supervisar los servicios, las cargas de trabajo y los recursos personalizados de Kubernetes.
  • Cargas de trabajo de agentes en todos los espacios de nombres: Los Pods del controlador deben poder llamar a los Pods de agentes y del servidor de MCP en cualquier espacio de nombres del clúster. El controlador recupera la tarjeta de agente de cada carga de trabajo del agente para registrarlo en Agent Registry.

Otorga roles de IAM al controlador y al recopilador de telemetría

Otorga roles de IAM a las identidades federadas del controlador de agent-governance-cross-cloud-controller y el recopilador de telemetría, que se ejecutan en el espacio de nombres geap-system:

  • Operador de satélite (roles/networkservices.satelliteOperator)
  • Escritor de telemetría de Cloud (roles/telemetry.writer)

Para otorgar los roles, ejecuta el siguiente comando:

for ROLE in \
    roles/networkservices.satelliteOperator \
    roles/telemetry.writer; do
  gcloud projects add-iam-policy-binding PROJECT_ID \
      --role="${ROLE}" \
      --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.namespace/geap-system"
done

Reemplaza lo siguiente:

Instala el gráfico de Helm del plano de control

Para instalar el plano de control, haz lo siguiente:

  1. Instala el gráfico de Helm de agent-governance-cross-cloud en el espacio de nombres geap-system:

    helm upgrade --install agent-governance-cross-cloud \
        oci://gcr.io/gke-release/agent-governance-cross-cloud \
        --version 0.1.1-preview \
        --namespace geap-system \
        --create-namespace \
        --set gcp.projectId=PROJECT_ID \
        --set-string gcp.projectNumber=PROJECT_NUMBER \
        --set-string gcp.orgId=ORGANIZATION_ID \
        --set gcp.location=LOCATION \
        --set gcp.registeredCluster=CLUSTER_NAME \
        --set gcp.workloadIdentityPool=POOL_ID \
        --set gcp.identityProvider=PROVIDER_ID
    

    Reemplaza lo siguiente:

    Si los nodos de tu clúster tienen taints, por ejemplo, nodos arm64 en la mayoría de los proveedores de servicios en la nube, incluidos Google Cloud, AWS y Azure, establece tolerancias de Pods en el valor de Helm k8s.tolerations. Las tolerancias se aplican al controlador, al recopilador de OpenTelemetry (OTel) y a las implementaciones de puerta de enlace que crea el controlador. Por ejemplo, guarda lo siguiente como tolerations-values.yaml y, luego, agrega --values tolerations-values.yaml al comando anterior:

    k8s:
      tolerations:
      - key: "kubernetes.io/arch"
        operator: "Equal"
        value: "arm64"
        effect: "NoSchedule"
    
  2. Espera a que la implementación del controlador esté lista:

    kubectl rollout status deployment/agent-governance-cross-cloud-controller \
        --namespace geap-system --timeout=180s
    

Implementa el plano de datos

Implementa Agent Gateway para el proxy multinube (proxy de Envoy) creando un recurso personalizado GCPAgentGateway. El proxy inspecciona el tráfico y aplica políticas para las cargas de trabajo del agente que rige. Cada proxy se ejecuta con un archivo adicional de Agent Identity Runtime (AIR) que intermedia las Workload Identity, los certificados del servicio de descubrimiento de secretos (SDS) y el intercambio de tokens local para el proxy.

Debes implementar Agent Gateway para multinube en un espacio de nombres dedicado (por ejemplo, agent-gateway-system) que no contenga cargas de trabajo de agentes, servidores de MCP ni otros Pods de aplicaciones. Una sola puerta de enlace en este espacio de nombres dedicado puede controlar el tráfico saliente de las cargas de trabajo de los agentes en todo el clúster.

Otorga roles de IAM a la puerta de enlace

Otorga roles de IAM a las identidades federadas de Agent Gateway para el proxy multinube. La vinculación se aplica a todas las KSA en el espacio de nombres de la puerta de enlace, por lo que debes otorgar estos roles para cada espacio de nombres de la puerta de enlace:

  • Cliente de Traffic Director (roles/trafficdirector.client)
  • Visualizador de extremos de App Hub (roles/apphubendpoint.viewer)
  • Visualizador de Agent Registry (roles/agentregistry.viewer)
  • Editor de Service Extensions (roles/serviceextensions.editor), que permite que el proxy llame a los textos destacados de la política de Service Extensions

Para otorgar los roles, ejecuta el siguiente comando:

for ROLE in \
    roles/trafficdirector.client \
    roles/apphubendpoint.viewer \
    roles/agentregistry.viewer \
    roles/serviceextensions.editor; do
  gcloud projects add-iam-policy-binding PROJECT_ID \
      --role="${ROLE}" \
      --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.namespace/GATEWAY_NAMESPACE"
done

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • PROJECT_NUMBER: Es el número del proyecto de Google Cloud .
  • POOL_ID: Es el ID del grupo de identidades para cargas de trabajo.
  • GATEWAY_NAMESPACE: Es un espacio de nombres dedicado para la puerta de enlace. Este espacio de nombres no debe contener cargas de trabajo de agentes.

Crea una plantilla de conectividad de agentes

Cada puerta de enlace hace referencia a una plantilla de conectividad de agente, que es un recurso deGoogle Cloud que hace referencia a tu clúster registrado. No es necesario que crees una plantilla independiente para cada puerta de enlace, ya que puedes asignar varias puertas de enlace a una sola plantilla. También puedes crear varias plantillas para el mismo clúster.

Si ya tienes una plantilla de conectividad de agentes para tu clúster que deseas usar, ve a Crea la puerta de enlace.

Para crear una plantilla de conectividad de agentes, haz lo siguiente:

  1. Guarda la siguiente definición de plantilla como act.yaml:

    description: "Agent connectivity template for CLUSTER_NAME"
    agentCompute: K8S
    registeredCluster: "projects/PROJECT_ID/locations/LOCATION/registeredClusters/CLUSTER_NAME"
    
  2. Importa la plantilla:

    gcloud alpha network-services agent-connectivity-templates import ACT_NAME \
        --project=PROJECT_ID \
        --location=LOCATION \
        --source=act.yaml
    

Reemplaza lo siguiente:

  • CLUSTER_NAME: Es el nombre del clúster registrado.
  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • LOCATION: Es la región en la que registraste el clúster.
  • ACT_NAME: Es un nombre para la plantilla de conectividad del agente.

Crea la puerta de enlace

Para crear la puerta de enlace, haz lo siguiente:

  1. Si el espacio de nombres de la puerta de enlace aún no existe, créalo:

    kubectl create namespace GATEWAY_NAMESPACE
    

    Reemplaza GATEWAY_NAMESPACE por el espacio de nombres dedicado para la puerta de enlace que usaste cuando otorgaste roles a la puerta de enlace.

  2. Guarda el siguiente manifiesto como agent-gateway.yaml:

    apiVersion: networkservices.googleapis.com/v1alpha1
    kind: GCPAgentGateway
    metadata:
      name: GATEWAY_NAME
      namespace: GATEWAY_NAMESPACE
    spec:
      agentConnectivityTemplateUri: "projects/PROJECT_ID/locations/LOCATION/agentConnectivityTemplates/ACT_NAME"
    

    Reemplaza lo siguiente:

  3. Aplica el manifiesto

    kubectl apply -f agent-gateway.yaml
    
  4. Espera a que la puerta de enlace se implemente y esté lista:

    kubectl wait --for=condition=Reconciled=True \
        gcpagentgateway/GATEWAY_NAME \
        -n GATEWAY_NAMESPACE \
        --timeout=300s
    

    Cuando la puerta de enlace esté lista, el comando devolverá gcpagentgateway.networkservices.googleapis.com/GATEWAY_NAME condition met.

  5. Configura tu malla de servicios para reenviar el tráfico saliente del agente, como las solicitudes de modelos de lenguaje grandes (LLM), del Protocolo de contexto del modelo (MCP) y de agente a agente (A2A), a través de la puerta de enlace.

Agrega tolerancias a las puertas de enlace existentes

Si agregas el valor de Helm k8s.tolerations después de crear un recurso GCPAgentGateway, haz lo siguiente para que el controlador vuelva a crear la implementación de la puerta de enlace con las tolerancias nuevas:

  1. Ejecuta el comando helm upgrade --install de Instala el gráfico de Helm del plano de control con --values tolerations-values.yaml.

  2. Borra la implementación de la puerta de enlace existente:

    kubectl delete deployment GATEWAY_NAME \
        --namespace GATEWAY_NAMESPACE
    

    Repite este paso para cada puerta de enlace de tu clúster.

  3. Reinicia el controlador para que vuelva a crear la implementación de la puerta de enlace:

    kubectl rollout restart deployment/agent-governance-cross-cloud-controller \
        --namespace geap-system
    

Este procedimiento no afecta al recurso Google Cloud AgentGateway ni a ningún recurso GCPExtensionBinding adjunto. El tráfico saliente a través de la puerta de enlace se interrumpe hasta que el controlador vuelve a crear la implementación de la puerta de enlace.

Permite la conectividad saliente a las APIs de Google

Asegúrate de que los pods de proxy de Agent Gateway para multinube tengan conectividad HTTPS y gRPC saliente a *.googleapis.com en el puerto TCP 443.

Configurar la inspección de TLS

Configura la inspección de seguridad de la capa de transporte (TLS) para asegurarte de que Agent Gateway para multinube pueda inspeccionar y controlar el tráfico saliente.

Protege el secreto de la CA de inspección de TLS

Agent Gateway para multinube usa una autoridad de certificación raíz (AC) para emitir los certificados que presenta cuando inspecciona el tráfico TLS saliente. El controlador crea esta AC cuando se inicia. La AC, incluida su clave privada, se almacena en recursos Secret de Kubernetes en dos espacios de nombres: el espacio de nombres del controlador (geap-system) y el espacio de nombres de la puerta de enlace, donde se implementan el Agent Gateway para el proxy multinube y el archivo adicional de AIR. Cualquier persona que pueda leer estos recursos Secret puede actuar en nombre de extremos externos en tus cargas de trabajo de agentes. Para proteger la CA, aplica las siguientes medidas de seguridad:

  • Restringe el acceso de RBAC al Secret: Limita los permisos get, list y watch en los recursos Secret en los espacios de nombres geap-system y de puerta de enlace a la Agent Gateway para las cuentas de servicio multinube y los administradores de plataformas dedicados. Los permisos list y watch también exponen el contenido de Secret.
  • Aísla los espacios de nombres del controlador y de la puerta de enlace: Los usuarios que pueden crear Pods en un espacio de nombres pueden activar cualquier Secret en ese espacio de nombres. Ejecuta solo Agent Gateway para los componentes multinube en el espacio de nombres geap-system y el espacio de nombres de la puerta de enlace. No implementes cargas de trabajo de agentes ni otros Pods en estos espacios de nombres. Limita los permisos para crear o modificar Pods, implementaciones y otros recursos de carga de trabajo en estos espacios de nombres a los administradores de confianza.
  • Encripta los datos de Secret en reposo: Habilita la encriptación en reposo para los recursos de Secret en el almacén de datos etcd de tu clúster. Cuando sea posible, usa un proveedor de KMS para administrar las claves de encriptación.
  • Audita el acceso al Secret: Habilita el registro de auditoría de Kubernetes y supervisa el acceso de lectura al Secret de la AC.

¿Qué sigue?