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:
Establece el contexto actual de
kubectlen el clúster que deseas registrar.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.pemEstos comandos requieren una shell de Bash y las utilidades
jqyopenssl.
Registre el clúster
Para registrar tu clúster, haz lo siguiente:
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-issuerdel 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.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 conhttps://.
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.deleteynetworkservices.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-cloudo borrar tu clúster de Kubernetes, borra todos los recursos personalizadosGCPExtensionBindingyGCPAgentGateway, 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:
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.
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"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-controllery el recopilador de telemetría deben tener conectividad HTTPS y gRPC saliente en el puerto TCP443a*.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:
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.
Instala el gráfico de Helm del plano de control
Para instalar el plano de control, haz lo siguiente:
Instala el gráfico de Helm de
agent-governance-cross-clouden el espacio de nombresgeap-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_IDReemplaza lo siguiente:
PROJECT_ID: Es el ID del proyecto de Google Cloud .PROJECT_NUMBER: Es el número del proyecto de Google Cloud .ORGANIZATION_ID: Es el ID de tu organización deGoogle Cloud . Si tu proyecto no está asociado con una organización, omite la marca--set-string gcp.orgId.LOCATION: Es la región en la que registraste el clúster, por ejemplo,us-central1.CLUSTER_NAME: Es el nombre del clúster registrado.POOL_ID: Es el ID del grupo de identidades para cargas de trabajo.PROVIDER_ID: Es el ID del proveedor de grupos de identidades para cargas de trabajo.
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 comotolerations-values.yamly, luego, agrega--values tolerations-values.yamlal comando anterior:k8s: tolerations: - key: "kubernetes.io/arch" operator: "Equal" value: "arm64" effect: "NoSchedule"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:
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"
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:
Si el espacio de nombres de la puerta de enlace aún no existe, créalo:
kubectl create namespace GATEWAY_NAMESPACE
Reemplaza
GATEWAY_NAMESPACEpor el espacio de nombres dedicado para la puerta de enlace que usaste cuando otorgaste roles a la puerta de enlace.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:
GATEWAY_NAME: un nombre para la puerta de enlace.GATEWAY_NAMESPACE: Es el espacio de nombres dedicado para la puerta de enlace que usaste cuando otorgaste roles a la puerta de enlace.PROJECT_ID: Es el ID del proyecto de Google Cloud .LOCATION: Es la región de la plantilla de conectividad del agente. Esta región debe coincidir con la región en la que registraste el clúster.ACT_NAME: Es el nombre de la plantilla de conectividad del agente.
Aplica el manifiesto
kubectl apply -f agent-gateway.yaml
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=300sCuando la puerta de enlace esté lista, el comando devolverá
gcpagentgateway.networkservices.googleapis.com/GATEWAY_NAME condition met.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:
Ejecuta el comando
helm upgrade --installde Instala el gráfico de Helm del plano de control con--values tolerations-values.yaml.Borra la implementación de la puerta de enlace existente:
kubectl delete deployment GATEWAY_NAME \ --namespace GATEWAY_NAMESPACERepite este paso para cada puerta de enlace de tu clúster.
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 permisosget,listywatchen los recursosSecreten los espacios de nombresgeap-systemy de puerta de enlace a la Agent Gateway para las cuentas de servicio multinube y los administradores de plataformas dedicados. Los permisoslistywatchtambién exponen el contenido deSecret. - 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
Secreten ese espacio de nombres. Ejecuta solo Agent Gateway para los componentes multinube en el espacio de nombresgeap-systemy 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
Secreten reposo: Habilita la encriptación en reposo para los recursos deSecreten 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 alSecretde la AC.
¿Qué sigue?
- Implementa y registra agentes multinube
- Aplica políticas de administración multinube.
- Configura la observabilidad del agente multinube