Déployer un agent et une passerelle d'agent avec VPC Service Controls

1. Introduction

Cet atelier de programmation vous guide dans la configuration d'un environnement Google Cloud pour configurer un agent et une passerelle d'agent avec des périmètres VPC Service Controls. Vous établissez un périmètre VPC Service Controls, configurez la mise en réseau et le DNS, déployez une passerelle d'agent avec l'autorisation de requête Identity-Aware Proxy (IAP), puis testez l'agent de manière sécurisée.

Objectifs de l'atelier

Dans cet atelier de programmation, vous allez créer une architecture Google Cloud sécurisée pour Gemini Enterprise Agent Platform et Agent Gateway qui effectue les opérations suivantes :

Points abordés

  • Découvrez comment activer les API Google Cloud requises pour Agent Platform et la sécurité.
  • Découvrez comment configurer un périmètre VPC Service Controls et des règles d'accès à l'entrée.
  • Configurer la connectivité au réseau privé et les enregistrements DNS privés
  • Créer des modèles de passerelle Agent Gateway et de connectivité des agents
  • Configurer les extensions et les règles d'autorisation des requêtes IAP
  • Découvrez comment déployer et tester un agent Agent Engine de manière sécurisée.

Prérequis

  • Google Cloud CLI est installé et mis à jour vers la dernière version.
  • Python 3 est installé sur votre poste de travail.
  • Git est installé sur votre poste de travail.
  • Un compte de facturation et une organisation Google Cloud actifs

2. Prérequis

Cette section décrit les exigences de base concernant l'outil de ligne de commande et la configuration de l'environnement nécessaires avant d'exécuter les scripts de configuration.

  1. Vérifiez que la Google Cloud CLI est installée et mise à jour vers la dernière version, puis authentifiez-vous avec votre compte Google. Mettez à jour vos composants Google Cloud CLI pour vous assurer de bénéficier des dernières fonctionnalités pour les services réseau et VPC Service Controls.
gcloud components update
gcloud auth login
gcloud config set account USER_EMAIL
  1. Vérifiez que Python 3 est installé pour configurer et déployer le framework d'agent personnalisé. Pour obtenir des instructions, consultez Installer des modules Python :
python3 --version
  1. Assurez-vous que Git est installé pour cloner l'exemple de dépôt contenant le code d'installation et les modèles de configuration. Pour obtenir des instructions, consultez Installation de Git.

3. Configurer un projet Google Cloud

La création d'un projet isolé au sein de votre organisation garantit que toutes les ressources, tous les réseaux et toutes les autorisations utilisés dans cet atelier de programmation restent encapsulés et gérables. Pour en savoir plus, consultez Créer et gérer des projets.

Initialisez un projet Google Cloud dans votre organisation pour héberger les ressources de cette configuration. Vous pouvez également utiliser votre propre projet :

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

Obtenez les identifiants par défaut de l'application en vous connectant :

gcloud auth application-default login

Vérifiez votre configuration :

gcloud config list

Activer la facturation

Associez un compte de facturation actif au projet que vous venez de créer pour pouvoir utiliser les services.

L'activation de la facturation est une condition préalable à l'utilisation du quota d'API et au provisionnement de l'infrastructure Google Cloud, comme les passerelles d'agent, les clouds privés virtuels et les nœuds de calcul. Pour en savoir plus sur les configurations de facturation, consultez la documentation Google Cloud Billing.

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. Activer les services

Activez toutes les API Google Cloud requises pour les fonctionnalités d'agent, d'Agent Gateway, de mise en réseau, de sécurité et d'observabilité.

L'activation de l'API expose les services cloud de backend pour la gestion des ressources, l'observabilité et les capacités de mise en réseau requises pour une connectivité sécurisée des agents. Pour en savoir plus, consultez la documentation de l'API 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. Exporter des variables d'environnement

Définissez des variables d'environnement réutilisables pour la région, l'ID du projet, le numéro du projet, l'ID d'organisation et l'identité de l'utilisateur. La définition de variables shell standardise les commandes de configuration des ressources entre les étapes, ce qui minimise les erreurs de substitution manuelle lors de l'exécution du script.

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. Créer un périmètre VPC Service Controls

Créez un périmètre VPC Service Controls pour isoler les ressources de votre projet et empêcher l'exfiltration de données. Pour en savoir plus, consultez la présentation de VPC Service Controls.

Récupérer votre règle d'accès

Récupérez l'ID de la règle Access Context Manager associée à votre organisation. Les règles Access Context Manager définissent la limite organisationnelle à laquelle les périmètres VPC Service Controls sont associés et appliqués.

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

Exporter votre règle d'accès

Définissez la stratégie d'accès dans votre configuration gcloud CLI et collectez la liste des services restreints compatibles. La collecte de tous les services compatibles vous permet de créer un ensemble de règles de périmètre restreint qui empêche tout accès non autorisé aux points de terminaison de l'API 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, -)

Créer un périmètre

Définissez le nom du périmètre de service et appliquez des restrictions aux services Google Cloud compatibles du projet. Le périmètre sert de limite autour des ressources du projet, ce qui restreint le trafic entrant et sortant direct, sauf s'il est explicitement autorisé par des règles d'entrée/de sortie.

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}

Créer une règle d'entrée

Les règles d'entrée définissent des conditions explicites (comme des identités utilisateur ou des niveaux d'accès spécifiques) dans lesquelles le trafic provenant de l'extérieur du périmètre est autorisé à atteindre les ressources restreintes à l'intérieur.

Créez un fichier YAML qui autorise l'accès explicite pour votre identité utilisateur à tous les services :

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"

Cet atelier de programmation configure votre environnement pour éviter les refus d'accès VPC Service Controls par défaut. Toutefois, pour vous aider à résoudre les problèmes lors des tests, VPC Service Controls fournit des journaux de refus détaillés et des outils d'analyse des règles.

Résoudre les problèmes de refus VPC Service Controls

Tout au long de vos tests, consultez les conseils de dépannage suivants :

  1. Activez le tableau de bord des cas de non-respect pour suivre les derniers cas de non-respect dans votre environnement.
  2. Surveillez les journaux Cloud Audit Logs pour les journaux de refus d'accès (403) VPC Service Controls.
  3. Diagnostiquez les cas de non-respect à l'aide de l'ID ou du jeton unique du cas de non-respect dans l'Analyseur de cas de non-respect.
  4. Pour obtenir une procédure détaillée, regardez la vidéo Résoudre les problèmes liés à VPC Service Controls.

7. Configurer la mise en réseau

Configurez les paramètres du réseau VPC pour permettre une communication privée avec les API et services Google. Une configuration réseau appropriée garantit que le trafic réseau entre les agents, les passerelles et les API Google Cloud reste sur les réseaux internes privés. Pour en savoir plus sur les modèles de mise en réseau, consultez la documentation Google Cloud VPC.

Activer l'accès privé à Google

Activez l'accès privé à Google sur le sous-réseau par défaut afin que les instances de VM et les charges de travail internes puissent accéder aux Google APIs à l'aide d'adresses IP internes au lieu d'adresses IP publiques.

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

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

Créer un rattachement de réseau PSC

Créez un rattachement de réseau Private Service Connect (PSC) pour la connectivité Agent Gateway. Les pièces jointes réseau fournissent des interfaces Private Service Connect (PSC), ce qui facilite la communication sécurisée entre les VPC entre le service Agent Gateway et votre sous-réseau interne.

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

Valider

Récupérez et inspectez l'URI de la ressource self-link du rattachement de réseau que vous venez de créer. La validation de l'URI de la ressource permet de s'assurer que le rattachement de réseau a bien été instancié et qu'il peut être référencé dans les modèles de connectivité.

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

Créer une zone privée Cloud DNS

Configurez une zone privée Cloud DNS pour acheminer le trafic googleapis.com via des plages d'adresses IP privées. Les zones DNS privées remplacent les recherches de domaine public pour googleapis.com, en redirigeant tout le trafic sortant vers des adresses IP virtuelles (VIP) internes privées au sein de votre réseau VPC. Pour en savoir plus, consultez Zones privées Cloud DNS.

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}

Choisissez l'une des options de domaine suivantes pour le routage privé (n'exécutez que les commandes de l'option 1 ou de l'option 2 avant d'exécuter la transaction). Pour en savoir plus, consultez les options de configuration de l'accès privé à Google :

Option 1 : VIP privé [recommandé]

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

Option 2 : VIP restreint

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

Validez les transactions DNS :

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

8. Créer une passerelle d'agent

Provisionnez Agent Gateway et définissez ses modèles de connectivité et ses règles de routage. Agent Gateway sert de proxy centralisé pour gérer le trafic des agents, les règles de sortie, la gestion des protocoles et la découverte sécurisée des services. Pour obtenir des références architecturales, consultez la présentation d'Agent Gateway.

Diagramme de l'architecture montrant un agent qui achemine les requêtes via Agent Gateway, l'autorisation des requêtes IAP et un rattachement de réseau PSC à l'intérieur d'un périmètre VPC Service Controls.

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

Créer un modèle de connectivité de l'agent

Les modèles de connectivité spécifient la configuration réseau, les règles de routage de sortie, les paramètres d'appairage DNS et les URI de rattachement de réseau requis par la passerelle pour gérer les requêtes sortantes.

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}

Créer une passerelle d'agent

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}

Vérifier la création

Vérifiez que la ressource Agent Gateway a bien été déployée et configurée. La description de la passerelle d'agent déployée confirme que son état opérationnel est actif et vérifie que les modèles et les registres de connectivité associés sont correctement associés.

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

9. Créer une autorisation via IAP

Configurez des règles d'autorisation des requêtes Identity-Aware Proxy (IAP) et des extensions de service pour vérifier les identifiants des requêtes avant d'accorder l'accès à l'Agent Gateway. Pour en savoir plus, consultez la documentation IAP.

Diagramme de flux montrant comment Agent Gateway délègue l'autorisation des requêtes à Identity-Aware Proxy (IAP) à l'aide d'une extension de service d'autorisation et d'une règle d'autorisation de sécurité réseau.

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

Créer une extension AuthZ

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}

Créer une règle AuthZ et l'associer à la passerelle d'agent

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}

Cet atelier de programmation garantit que vous ne serez pas refusé à l'accès IAP par défaut. Toutefois, pour faciliter vos tests, Agent Gateway fournit une observabilité détaillée des refus d'accès.

Résoudre les problèmes de refus d'autorisation IAP et les surveiller

  1. Activez l'analyse de journaux dans le bucket de journaux _Default :
gcloud logging buckets update _Default --location=global --enable-analytics --async
  1. Ouvrez le tableau de bord d'observabilité Agent Gateway :
  2. Dans la console Google Cloud, accédez à la page Agent Gateway.
  3. Cliquez sur le nom de votre passerelle (par exemple, gateway-xyz).
  4. Cliquez sur l'onglet Observabilité.
  5. Consultez les tableaux de bord "Échec de l'autorisation" et "Refus 403".

10. Créer un agent Agent Engine

Créer un bucket intermédiaire

Créez un bucket Cloud Storage dans votre région cible pour stocker les artefacts de préproduction temporaires, les dépendances et les configurations de déploiement lors de l'initialisation de l'exécution.

#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}

Activer l'environnement virtuel Python

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

Télécharger le code de l'agent

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

Installer des dépendances

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

Attribuer des rôles IAM à l'agent de service 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"

Déployer l'agent

python3 deploy_gcp_agent.py create

Exportez l'identité de l'agent imprimée dans le résultat de la commande précédente en tant que variable d'environnement :

#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. Autoriser la sortie de l'agent via une passerelle

Autorisez l'agent nouvellement créé à envoyer du trafic de sortie vers googleapis.com.

Remarque : Vous pouvez ajouter des points de terminaison à la liste d'autorisation de manière sélective à l'aide de l'observabilité Agent Gateway. Par souci de simplicité, cet atelier de programmation autorise l'accès à toutes les API.

La configuration de règles de stratégie de sortie IAM explicites accorde à l'agent l'autorisation d'acheminer les appels d'API via l'Agent Gateway et le proxy IAP pour accéder aux services Google Cloud externes.

Créer une stratégie 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

Mettre à jour la règle d'accès

Vérifiez si vous disposez déjà d'une règle d'accès :

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

Définissez le nom de la règle d'accès :

export IAM_ACCESS_POLICY="agent-access-policy"

Pour créer des règles, procédez comme suit :

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

Vous pouvez également mettre à jour une règle existante :

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

12. Tester l'agent

La validation du fonctionnement de l'agent dans la console Google Cloud permet de vérifier que la communication de bout en bout, les règles IAM et les limites de VPC Service Controls fonctionnent correctement. Vous êtes maintenant prêt à tester l'agent :

  1. Dans la console Google Cloud, accédez à la page Déploiements d'agents.
  2. Sélectionnez l'agent déployé (gcp_agent_...).
  3. Ouvrez l'onglet Playground.
  4. Dans le champ de requête, saisissez : List storage buckets in the current project.
  5. Vérifiez que l'agent renvoie bien la liste des buckets via l'Agent Gateway privée.
  6. Vérifiez que l'agent ne peut pas récupérer de buckets d'un autre projet en raison d'un refus d'accès. Vous pouvez examiner le refus dans Cloud Audit Logs ou dans le tableau de bord des cas de non-respect de VPC Service Controls.

13. Effectuer un nettoyage

Pour éviter que les ressources utilisées dans cet atelier de programmation ne soient facturées sur votre compte Google Cloud, supprimez le projet que vous avez créé :

gcloud projects delete ${PROJ_ID}

14. Félicitations

Félicitations ! Vous avez correctement configuré un agent et une passerelle d'agent dans un périmètre VPC Service Controls sécurisé sur Google Cloud.

Et ensuite ?

  • Découvrez les règles d'entrée et de sortie précises dans VPC Service Controls.
  • Configurez des règles d'accès et sémantiques à l'aide de l'Agent Gateway.
  • Intégrez Model Armor pour un filtrage avancé de la sécurité.

Documents de référence