Implementa un agente y Agent Gateway con los Controles del servicio de VPC

1. Introducción

En este codelab, se te guía para configurar un entorno de Google Cloud y, luego, configurar un agente y un Agent Gateway con perímetros de Controles del servicio de VPC. Estableces un perímetro de los Controles del servicio de VPC, configuras la red y el DNS, implementas un Agent Gateway con autorización de solicitudes de Identity-Aware Proxy (IAP) y pruebas el agente de forma segura.

Qué compilarás

En este codelab, compilarás una arquitectura segura de Google Cloud para Gemini Enterprise Agent Platform y Agent Gateway que haga lo siguiente:

Qué aprenderás

  • Cómo habilitar las APIs de Google Cloud requeridas para la plataforma de agentes y la seguridad
  • Cómo configurar un perímetro de Controles del servicio de VPC y reglas de acceso de entrada
  • Cómo configurar la conectividad de red privada y los registros de DNS privados
  • Cómo crear un Agent Gateway y plantillas de conectividad del agente
  • Cómo configurar extensiones y políticas de autorización de solicitudes de IAP
  • Cómo implementar y probar un agente de Agent Engine de forma segura

Requisitos

  • Google Cloud CLI instalado y actualizado a la versión más reciente
  • Python 3 instalado en tu estación de trabajo
  • Git instalado en tu estación de trabajo
  • Una organización de Google Cloud activa y permisos de cuenta de facturación

2. Requisitos previos

En esta sección, se describen los requisitos básicos de la herramienta de línea de comandos y la configuración del entorno necesarios antes de ejecutar las secuencias de comandos de configuración.

  1. Verifica que Google Cloud CLI esté instalada y actualizada a la versión más reciente. Luego, autentícate con tu Cuenta de Google. Actualiza los componentes de la Google Cloud CLI para asegurarte de tener la compatibilidad con las funciones más recientes de los Servicios de redes y los Controles del servicio de VPC.
gcloud components update
gcloud auth login
gcloud config set account USER_EMAIL
  1. Verifica que Python 3 esté instalado para configurar e implementar el framework del agente personalizado. Para obtener instrucciones, consulta Cómo instalar módulos de Python:
python3 --version
  1. Asegúrate de que Git esté instalado para clonar el repositorio de muestra que contiene el código de configuración y las plantillas de configuración. Para obtener instrucciones, consulta Instalación de Git.

3. Configura un proyecto de Google Cloud

Crear un proyecto aislado dentro de tu organización garantiza que todos los recursos, las redes y los permisos que se usen en este codelab permanezcan encapsulados y sean fáciles de administrar. Obtén más información para crear y administrar proyectos.

Inicializa un nuevo proyecto de Google Cloud en tu organización para alojar los recursos de esta configuración. También puedes usar tu propio proyecto:

export PROJ_ID="YOUR_PROJECT_ID"
gcloud projects create ${PROJ_ID} --organization=YOUR_ORG_ID

gcloud config set project $PROJ_ID

gcloud auth application-default set-quota-project $PROJ_ID

Obtén credenciales predeterminadas de la aplicación accediendo:

gcloud auth application-default login

Verifica la configuración:

gcloud config list

Habilita la facturación

Vincula una cuenta de facturación activa al proyecto recién creado para habilitar el uso del servicio.

Habilitar la facturación es un requisito previo para consumir la cuota de la API y aprovisionar la infraestructura de nube de Google Cloud, como las puertas de enlace de agentes, las nubes privadas virtuales y los nodos de procesamiento. Para obtener detalles sobre la configuración de facturación, consulta la Documentación de facturación de Google Cloud.

gcloud billing accounts list
# Copy the billing account to assign to your GCP project
gcloud billing projects link $PROJ_ID --billing-account=BILLING_ACCOUNT_ID

4. Habilitar servicios

Habilita todas las APIs de Google Cloud necesarias para las funciones de Agent, Agent Gateway, redes, seguridad y observabilidad.

La activación de la API expone los servicios de backend de la nube para la administración de recursos, la observabilidad y las capacidades de redes necesarias para la conectividad segura del agente. Obtén más información en la documentación de la API de Service Usage.

gcloud services enable \
  agentregistry.googleapis.com \
  aiplatform.googleapis.com \
  apphub.googleapis.com \
  apptopology.googleapis.com \
  cloudapiregistry.googleapis.com \
  cloudtrace.googleapis.com \
  compute.googleapis.com \
  dataform.googleapis.com \
  iam.googleapis.com \
  iap.googleapis.com \
  logging.googleapis.com \
  modelarmor.googleapis.com \
  monitoring.googleapis.com \
  networksecurity.googleapis.com \
  networkservices.googleapis.com \
  notebooks.googleapis.com \
  observability.googleapis.com \
  securitycenter.googleapis.com

gcloud services enable \
  saasservicemgmt.googleapis.com \
  storage.googleapis.com \
  telemetry.googleapis.com \
  texttospeech.googleapis.com \
  run.googleapis.com \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com \
  dns.googleapis.com \
  accesscontextmanager.googleapis.com \
  discoveryengine.googleapis.com \
  agentidentity.googleapis.com \
  agentidentitycredentials.googleapis.com

5. Exporta variables de entorno

Define variables de entorno reutilizables para la región, el ID del proyecto, el número del proyecto, el ID de organización y la identidad del usuario. Establecer variables de shell estandariza los comandos de configuración de recursos en todos los pasos, lo que minimiza los errores de sustitución manual durante la ejecución de la secuencia de comandos.

export REGION="us-central1"
export PROJ_ID=$(gcloud config list --format="value(core.project)")
export PROJ_NO=$(gcloud projects describe ${PROJ_ID} --format="value(projectNumber)")
export ORG_ID=$(gcloud projects get-ancestors ${PROJ_ID} --format="value(id)" | tail -n 1)
export USER_IDENTITY=$(gcloud config get-value account)

6. Crea un perímetro de Controles del servicio de VPC

Crea un perímetro de Controles del servicio de VPC para aislar los recursos de tu proyecto y ayudar a evitar el robo de datos. Para obtener más información, consulta la Descripción general de los Controles del servicio de VPC.

Recupera tu política de acceso

Recupera el ID de la política de Access Context Manager asociado a tu organización. Las políticas de Access Context Manager definen el límite de la organización en el que se adjuntan y aplican los perímetros de los Controles del servicio de VPC.

gcloud access-context-manager policies list --organization=$ORG_ID

Cómo exportar tu política de acceso

Establece la política de acceso en tu configuración de gcloud CLI y recopila la lista de servicios restringidos admitidos. La recopilación de todos los servicios admitidos te permite compilar un conjunto de reglas de perímetro restringido que impide el acceso no autorizado a los extremos de la API de Google Cloud.

export ACCESS_POLICY=ACCESS_POLICY_ID

gcloud config set access_context_manager/policy $ACCESS_POLICY
SUPPORTED_SERVICES=$(gcloud access-context-manager supported-services list --format="value(name)" | paste -sd, -)

Crea un perímetro

Define el nombre del perímetro de servicio y aplica restricciones en todos los servicios de Google Cloud compatibles dentro del proyecto. El perímetro actúa como un límite que rodea los recursos del proyecto y restringe el tráfico entrante y saliente directo, a menos que las reglas de entrada y salida lo permitan de forma explícita.

export PERIMETER_NAME="perimeter_${PROJ_NO}"

gcloud access-context-manager perimeters create accessPolicies/${ACCESS_POLICY}/servicePerimeters/${PERIMETER_NAME} \
--title="${PERIMETER_NAME}" \
--perimeter-type=regular \
--resources=projects/${PROJ_NO} \
--restricted-services=${SUPPORTED_SERVICES}

Crea una política de entrada

Las políticas de entrada definen condiciones explícitas, como identidades de usuario o niveles de acceso específicos, en virtud de las cuales el tráfico se origina fuera del perímetro y se le permite llegar a los recursos restringidos dentro de él.

Crea un archivo YAML que permita el acceso explícito para la identidad del usuario en todos los servicios:

cat > ingress-policy.yaml << EOF
- ingressFrom:
    identities:
      - user:${USER_IDENTITY}
    sources:
      - accessLevel: '*'
  ingressTo:
    operations:
      - serviceName: '*'
    resources:
      - '*'
EOF

gcloud access-context-manager perimeters update $PERIMETER_NAME --set-ingress-policies="ingress-policy.yaml"

En este codelab, se configura tu entorno para evitar los rechazos de acceso de los Controles del servicio de VPC de forma predeterminada. Sin embargo, para ayudarte a solucionar problemas durante las pruebas, los Controles del servicio de VPC proporcionan registros de denegación detallados y herramientas de inteligencia de políticas.

Soluciona problemas relacionados con los rechazos de los Controles del servicio de VPC

Durante las pruebas, consulta las siguientes sugerencias para solucionar problemas:

  1. Habilita el panel de incumplimientos para hacer un seguimiento de los incumplimientos más recientes en tu entorno.
  2. Supervisa los Registros de auditoría de Cloud para detectar registros de rechazo de acceso (403) de los Controles del servicio de VPC.
  3. Diagnostica incumplimientos con el ID o el token únicos del incumplimiento en el Analizador de incumplimientos.
  4. Mira el video sobre cómo solucionar problemas de los Controles del servicio de VPC para obtener una guía detallada.

7. Configura las herramientas de redes

Configura la configuración de red de VPC para admitir la comunicación privada con los servicios y las APIs de Google. La configuración de red adecuada garantiza que el tráfico de red entre los agentes, las puertas de enlace y las APIs de Google Cloud permanezca en las redes internas privadas. Para obtener información detallada sobre los patrones de redes, consulta la documentación de la VPC de Google Cloud.

Habilite el Acceso privado a Google

Habilita el Acceso privado a Google en la subred predeterminada para que las instancias de VM y las cargas de trabajo internas puedan acceder a las APIs de Google con direcciones IP internas en lugar de direcciones IP públicas.

export NETWORK_NAME="default"
export SUBNET_NAME="default"

gcloud compute networks subnets update $SUBNET_NAME --region=$REGION --enable-private-ip-google-access

Crea un adjunto de red de PSC

Crea un adjunto de red de Private Service Connect (PSC) para la conectividad de Agent Gateway. Los adjuntos de red proporcionan interfaces de Private Service Connect (PSC), lo que facilita la comunicación segura entre VPC del servicio de Agent Gateway y tu subred interna.

gcloud compute network-attachments create psc-agw-${REGION} \
  --region=${REGION} \
  --subnets=${SUBNET_NAME} \
  --connection-preference=ACCEPT_AUTOMATIC

Verificar

Recupera e inspecciona el URI del recurso de vínculo propio del adjunto de red recién creado. La validación del URI del recurso garantiza que el adjunto de red se haya creado correctamente y que se pueda hacer referencia a él en las plantillas de conectividad.

export PSC_NA_URI=$(gcloud compute network-attachments describe psc-agw-${REGION} \
  --region=${REGION} \
  --format="value(selfLink.scope(v1))")
echo ${PSC_NA_URI}

Crea una zona privada de Cloud DNS

Configura una zona privada de Cloud DNS para enrutar el tráfico de googleapis.com a través de rangos de IP privadas. Las zonas de DNS privado anulan las búsquedas de dominio público para googleapis.com y dirigen todo el tráfico saliente a las direcciones IP virtuales (VIP) internas privadas dentro de tu red de VPC. Consulta Zonas privadas de Cloud DNS para obtener más detalles.

export ZONE_NAME="gapis"

gcloud dns managed-zones create ${ZONE_NAME} \
--visibility=private \
--networks=https://www.googleapis.com/compute/v1/projects/${PROJ_ID}/global/networks/${NETWORK_NAME} \
  --description="Privately reach Google APIs" \
  --dns-name=googleapis.com

gcloud dns record-sets transaction start --zone=${ZONE_NAME}

Elige una de las siguientes opciones de dominio para el enrutamiento privado (ejecuta solo los comandos de la opción 1 o la opción 2 antes de ejecutar la transacción). Obtén más información en las opciones de configuración del Acceso privado a Google:

Opción 1: VIP privado [recomendado]

gcloud dns record-sets transaction add --name="*.googleapis.com." \
    --type=CNAME private.googleapis.com. \
    --zone=${ZONE_NAME} \
    --ttl=300

gcloud dns record-sets transaction add --name=private.googleapis.com. \
    --type=A 199.36.153.8 199.36.153.9 199.36.153.10 199.36.153.11 \
    --zone=${ZONE_NAME} \
    --ttl=300

Opción 2: VIP restringido

gcloud dns record-sets transaction add --name="*.googleapis.com." \
    --type=CNAME restricted.googleapis.com. \
    --zone=${ZONE_NAME} \
    --ttl=300

gcloud dns record-sets transaction add --name=restricted.googleapis.com. \
    --type=A 199.36.153.4 199.36.153.5 199.36.153.6 199.36.153.7 \
    --zone=${ZONE_NAME} \
    --ttl=300

Confirma las transacciones de DNS:

gcloud dns record-sets transaction execute --zone=${ZONE_NAME}

8. Crea Agent Gateway

Aprovisiona Agent Gateway y define sus plantillas de conectividad y reglas de enrutamiento. Agent Gateway funciona como proxy centralizado para administrar el tráfico de agentes, las políticas de salida, el control de protocolos y el descubrimiento seguro de servicios. Para obtener referencias de arquitectura, consulta la Descripción general de Agent Gateway.

Diagrama de arquitectura que muestra un agente que enruta solicitudes a través de Agent Gateway, la autorización de solicitudes de IAP y un adjunto de red de PSC dentro de un perímetro de Controles del servicio de VPC.

export AGW_NAME="gateway-${USER_IDENTITY}"
export AGW_CONNECTIVITY_TEMPLATE="agw-connectivity-template-${USER_IDENTITY}"

Crea una plantilla de conectividad del agente

Las plantillas de conectividad especifican la configuración de red, las políticas de enrutamiento de salida, la configuración del intercambio de tráfico de DNS y los URIs de adjuntos de red que requiere la puerta de enlace para controlar las solicitudes salientes.

cat > ${AGW_CONNECTIVITY_TEMPLATE}.yaml << EOF
name: projects/${PROJ_NO}/locations/${REGION}/agentConnectivityTemplates/${AGW_CONNECTIVITY_TEMPLATE}
accessPath: AGENT_TO_ANYWHERE
deploymentModel: CENTRALIZED
egressNetworkConfig:
  networkAttachment: ${PSC_NA_URI}
  dnsPeeringConfig:
    domain: googleapis.com.
    targetNetwork: projects/${PROJ_ID}/global/networks/${NETWORK_NAME}
  vpcEgress: ALL_TRAFFIC
EOF

gcloud network-services agent-connectivity-templates import ${AGW_CONNECTIVITY_TEMPLATE} \
    --source="${AGW_CONNECTIVITY_TEMPLATE}.yaml" \
    --location=${REGION}

Crea Agent Gateway

cat > ${AGW_NAME}-config.yaml << EOF
name: ${AGW_NAME}
protocols:
  - MCP
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
agentConnectivityTemplate: projects/${PROJ_NO}/locations/${REGION}/agentConnectivityTemplates/${AGW_CONNECTIVITY_TEMPLATE}
registries:
  - //agentregistry.googleapis.com/projects/${PROJ_NO}/locations/global
EOF

gcloud network-services agent-gateways import ${AGW_NAME} \
    --source="${AGW_NAME}-config.yaml" \
    --location=${REGION}

Verifica la creación

Confirma que el recurso de Agent Gateway se haya implementado y configurado correctamente. La descripción de la puerta de enlace del agente implementado confirma que su estado operativo está activo y verifica que las plantillas y los registros de conectividad asociados estén adjuntos correctamente.

gcloud network-services agent-gateways describe ${AGW_NAME} \
  --location=${REGION}

9. Crea una autorización a través de IAP

Configura las políticas de autorización de solicitudes de Identity-Aware Proxy (IAP) y las extensiones de servicio para verificar las credenciales de las solicitudes antes de otorgar acceso a Agent Gateway. Para obtener más información, consulta la documentación de IAP.

Diagrama de flujo que muestra cómo Agent Gateway delega la autorización de solicitudes a Identity-Aware Proxy (IAP) con una política de autorización de seguridad de red y una extensión de servicio de autorización.

export AUTHZ_EXT="iap-authz-extension-${USER_IDENTITY}"
export AUTHZ_POLICY="iap-authz-policy-${USER_IDENTITY}"

Crear extensión de autorización

cat > ${AUTHZ_EXT}.yaml << EOF
name: ${AUTHZ_EXT}
service: iap.googleapis.com
failOpen: false
timeout: 1s
metadata:
  iapPolicyVersion: "V2"
EOF

gcloud service-extensions authz-extensions import ${AUTHZ_EXT} \
    --source=${AUTHZ_EXT}.yaml \
    --location=${REGION}

Crea una política de autorización y vincúlala a Agent Gateway

cat > ${AUTHZ_POLICY}.yaml << EOF
name: ${AUTHZ_POLICY}
target:
  resources:
    - "projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
policyProfile: REQUEST_AUTHZ
action: CUSTOM
customProvider:
  authzExtension:
    resources:
      - "projects/${PROJ_ID}/locations/${REGION}/authzExtensions/${AUTHZ_EXT}"
EOF

gcloud network-security authz-policies import ${AUTHZ_POLICY} \
    --source=${AUTHZ_POLICY}.yaml \
    --location=${REGION}

En este codelab, se garantiza que no se te negará el acceso a las IAP de forma predeterminada. Sin embargo, para ayudarte con las pruebas, Agent Gateway proporciona observabilidad detallada para los rechazos de acceso.

Soluciona problemas y supervisa los rechazos de autorización de IAP

  1. Habilita el Análisis de registros en el bucket de registros _predeterminado:
gcloud logging buckets update _Default --location=global --enable-analytics --async
  1. Abre el panel de observabilidad de Agent Gateway:
  2. En la consola de Google Cloud, ve a la página Agent Gateway.
  3. Haz clic en el nombre de tu puerta de enlace (por ejemplo, gateway-xyz).
  4. Haz clic en la pestaña Observabilidad.
  5. Revisa los paneles de Autorización fallida y Rechazos 403.

10. Crea un agente de Agent Engine

Crea un bucket de etapa de pruebas

Crea un bucket de Cloud Storage en tu región de destino para almacenar artefactos de etapa de pruebas, dependencias y configuraciones de implementación temporales durante la inicialización del tiempo de ejecución.

#Staging bucket name needs to be globally unique
export STAGING_BUCKET="agent-temp-bucket-${PROJ_NO}-${USER_IDENTITY}"
gcloud storage buckets create gs://${STAGING_BUCKET} --location=${REGION}

Activa el entorno virtual de Python

python3 -m venv .venv
source .venv/bin/activate

Descarga el código del agente

git clone https://github.com/gpratikab/gcp-vpcsc-agent.git
cd gcp-vpcsc-agent

Instala dependencias

python3 -m pip install --upgrade -r requirements.txt

Otorga roles de IAM al agente de servicio de Agent Platform

gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:service-${PROJ_NO}@gcp-sa-aiplatform.iam.gserviceaccount.com" \
  --role="roles/agentgateway.serviceAgent"
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:service-${PROJ_NO}@gcp-sa-aiplatform.iam.gserviceaccount.com" \
  --role="roles/ml.serviceAgent"
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:service-${PROJ_NO}@gcp-sa-aiplatform.iam.gserviceaccount.com" \
  --role="roles/networkservices.viewer"

Implementa el agente

python3 deploy_gcp_agent.py create

Exporta la identidad del agente que se imprimió en el resultado del comando anterior como una variable de entorno:

#Paste identity of your Agent, it will be printed as the output of the previous command
export AGENT_IDENTITY="principal://PRINCIPAL_ID"
echo $AGENT_IDENTITY

11. Permite la salida del agente a través de la puerta de enlace

Permite que el agente recién creado envíe tráfico de salida a googleapis.com.

Nota: Puedes incluir en la lista de entidades permitidas de forma selectiva los extremos con la observabilidad de Agent Gateway. Para mayor simplicidad, este codelab permite el acceso a todas las APIs.

Configurar reglas explícitas de política de salida de IAM otorga al agente permiso para enrutar llamadas a la API a través de Agent Gateway y el proxy de IAP para llegar a los servicios externos de Google Cloud.

Crear una política de IAM

cat > agent-access-rules.json << EOF
{
  "conditions": {
    "iap.googleapis.com": {
      "description": "Allow access to agent",
      "expression": "(destination.agent_registry.location == 'global') || (destination.unregistered.host.endsWith('googleapis.com'))",
      "title": "agenttogapis"
    }
  },
  "description": "agenttogapis",
  "effect": "ALLOW",
  "excludedPrincipals": [],
  "operation": {
    "excludedPermissions": [],
    "permissions": [
      "iap.googleapis.com/resources.egressViaIAP"
    ]
  },
  "principals": [
    "${AGENT_IDENTITY}"
  ]
}
EOF

Actualiza la política de acceso

Verifica si tienes una política de acceso existente:

gcloud iam access-policies list --project=${PROJ_ID} --location=global

Establece el nombre de la política de acceso:

export IAM_ACCESS_POLICY="agent-access-policy"

Para crear una política nueva:

gcloud iam access-policies create ${IAM_ACCESS_POLICY} \
  --details-rules=agent-access-rules.json \
  --project=${PROJ_ID} \
  --location=global

Como alternativa, actualiza una política existente:

gcloud iam access-policies update ${IAM_ACCESS_POLICY} \
  --add-details-rules=agent-access-rules.json \
  --project=${PROJ_ID} \
  --location=global

12. Prueba el agente

La validación del funcionamiento del agente en la consola de Google Cloud verifica que la comunicación de extremo a extremo, las políticas de IAM y los límites de los Controles del servicio de VPC funcionen correctamente. Ya puedes probar el agente:

  1. En la consola de Google Cloud, ve a la página Agent Deployments.
  2. Selecciona el agente implementado (gcp_agent_...).
  3. Abre la pestaña Playground.
  4. En el campo de instrucción, ingresa lo siguiente: List storage buckets in the current project.
  5. Verifica que el agente devuelva correctamente la lista de buckets a través de Agent Gateway privado.
  6. Verifica que el agente no pueda recuperar buckets de otro proyecto debido a una denegación de acceso. Puedes inspeccionar el rechazo en los Registros de auditoría de Cloud o en el panel de incumplimientos de los Controles del servicio de VPC.

13. Limpia

Para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos que usaste en este codelab, borra el proyecto que creaste:

gcloud projects delete ${PROJ_ID}

14. Felicitaciones

¡Felicitaciones! Configuraste correctamente un agente y un Agent Gateway dentro de un perímetro seguro de los Controles del servicio de VPC en Google Cloud.

¿Qué sigue?

  • Explora las reglas de entrada y salida detalladas en los Controles del servicio de VPC.
  • Configura políticas de acceso y semánticas con Agent Gateway.
  • Integra Model Armor para un filtrado avanzado de seguridad.

Documentos de referencia