Accéder à Apigee de manière privée depuis Gemini Enterprise Agent Platform

Cette page s'applique à Apigee, mais pas à Apigee hybrid.

Consultez la documentation d' Apigee Edge.

Ce document explique comment configurer une connectivité privée à partir d'un agent déployé sur Gemini Enterprise Agent Platform Agent Runtime vers les API et les outils Model Context Protocol (MCP) publiés sur Apigee, à l'aide de Private Service Connect. Avec ce modèle, le trafic de l'agent vers Apigee reste entièrement privé et ne transite pas par l'Internet public.

Présentation

L'environnement d'exécution de l'agent déploie votre agent dans un réseau sécurisé géré par Google, sans accès à votre réseau de cloud privé virtuel (VPC). De même, Apigee s'exécute dans un réseau sécurisé géré par Google. Lorsque vous souhaitez que les appels d'un agent à un grand modèle de langage (LLM) ou à des outils MCP exposés via Apigee transitent de manière privée, vous avez besoin d'un moyen de relier ces deux réseaux gérés par Google via un réseau VPC que vous contrôlez.

Ce document décrit le modèle suivant pour ce pont :

Avec cette configuration, lorsque votre agent appelle https://APIGEE_HOSTNAME/..., la requête est résolue en adresse IP du point de terminaison Private Service Connect dans votre VPC, est transmise via le rattachement de service à votre instance Apigee et est traitée par le proxy d'API qui correspond au chemin d'accès de la requête.

Avant de commencer

Ce document utilise les espaces réservés suivants dans les commandes. Remplacez-les par des valeurs de votre environnement.

  • APIGEE_PROJECT_ID : ID du projet Google Cloud contenant votre organisation Apigee.
  • SERVICE_PROJECT_ID : ID du projet Google Cloud dans lequel vous déployez votre agent sur Agent Runtime. Il peut s'agir du même projet que APIGEE_PROJECT_ID ou d'un autre projet, selon la façon dont vous organisez vos ressources Google Cloud.
  • SERVICE_PROJECT_NUMBER : numéro de projet numérique pour SERVICE_PROJECT_ID. Vous pouvez le récupérer avec gcloud projects describe SERVICE_PROJECT_ID --format="value(projectNumber)".
  • HOST_PROJECT_ID : ID du projet Google Cloud qui contient le réseau VPC, le sous-réseau et la zone privée Cloud DNS du consommateur. C'est la même chose que SERVICE_PROJECT_ID, sauf si vous utilisez un VPC partagé. Dans ce cas, il s'agit du projet hôte auquel le projet de service est associé.
  • REGION : région de votre instance Apigee (par exemple, us-west1).
  • VPC_NAME : nom du réseau VPC du consommateur dans HOST_PROJECT_ID.
  • SUBNET_NAME : nom d'un sous-réseau dans VPC_NAME situé dans REGION.
  • APIGEE_HOSTNAME : nom d'hôte que vous avez configuré sur le groupe d'environnements Apigee (par exemple, api.internal.example.com).
  • BASE_PATH : chemin de base du proxy d'API déployé sur Apigee (par exemple, /mcp ou /orders).
  • PARENT_DNS_NAME : domaine DNS parent de APIGEE_HOSTNAME que vous souhaitez diffuser à partir de la zone privée (par exemple, internal.example.com.). La valeur doit se terminer par un point.
  • APIGEE_INSTANCE_NAME : nom de votre instance Apigee dans REGION.

Vous devez disposer des éléments suivants :

  • Un ou plusieurs projets Google Cloud (comme décrit dans la note précédente) avec la facturation activée.
  • Une organisation Apigee existante dans APIGEE_PROJECT_ID avec au moins une instance. Ce document crée toutes les ressources réseau du consommateur (rattachement de réseau, point de terminaison Private Service Connect, déploiement Agent Runtime) dans la même région que votre instance Apigee, ce qui constitue la configuration la plus simple.
  • Un groupe d'environnements dont les environnements sont déployés sur cette instance Apigee et qui inclut le nom d'hôte que vous souhaitez que votre agent appelle. Dans ce document, ce nom d'hôte est appelé APIGEE_HOSTNAME.
  • Au moins un proxy d'API déployé dans un environnement de ce groupe d'environnements. Tous les proxys que l'agent doit appeler doivent être accessibles à l'adresse https://APIGEE_HOSTNAME/BASE_PATH.
  • Un réseau et un sous-réseau VPC dans HOST_PROJECT_ID, dans la même région que l'instance Apigee. Ce document les désigne par VPC_NAME et SUBNET_NAME. Agent Runtime nécessite un sous-réseau de /28 minimum et impose des restrictions de plage supplémentaires. Pour en savoir plus, consultez Exigences concernant la plage d'adresses IP du sous-réseau dans la documentation Agent Platform.
  • Les API suivantes sont activées dans le projet approprié :
    • Apigee (apigee.googleapis.com) dans APIGEE_PROJECT_ID.
    • Compute Engine (compute.googleapis.com) et Cloud DNS (dns.googleapis.com) dans HOST_PROJECT_ID.
    • Agent Platform (aiplatform.googleapis.com) dans SERVICE_PROJECT_ID.
  • Autorisations IAM suffisantes pour créer des zones et des enregistrements Cloud DNS, des adresses Compute Engine, des associations réseau et des règles de transfert Private Service Connect dans HOST_PROJECT_ID, et pour mettre à jour la configuration de l'instance et du groupe d'environnement Apigee dans APIGEE_PROJECT_ID. Pour en savoir plus sur les rôles requis, consultez Rôles Apigee, Contrôle des accès Cloud DNS et Rôles IAM Compute Engine.

Architecture

Les étapes suivantes décrivent le flux de trafic entre un agent déployé sur Agent Runtime et un proxy d'API hébergé sur Apigee, à l'aide d'un point de terminaison Private Service Connect dans un VPC consommateur comme pont.

  1. L'agent, qui s'exécute sur Agent Runtime, envoie une requête HTTPS à APIGEE_HOSTNAME.
  2. L'appairage DNS configuré sur l'interface PSC Agent Runtime transfère la recherche vers la zone privée Cloud DNS de votre VPC consommateur, qui renvoie l'adresse IP du point de terminaison Private Service Connect.
  3. La requête de l'agent sort via l'interface PSC vers votre VPC consommateur et atteint le point de terminaison Private Service Connect à cette adresse IP.
  4. Le point de terminaison Private Service Connect transmet la requête via la connexion de service au rattachement de service de l'instance Apigee.
  5. L'instance Apigee met fin à TLS, fait correspondre le nom d'hôte de la requête au groupe d'environnements et l'achemine vers le proxy d'API approprié.

Étape 1 : Configurer la mise en réseau dans le VPC consommateur

Cette section configure les ressources de deux projets. Chaque commande inclut un indicateur --project explicite. Vous pouvez ainsi exécuter les commandes à partir de n'importe quelle configuration gcloud active :

  • Les ressources Cloud DNS (zone privée et enregistrement) sont créées dans HOST_PROJECT_ID, car la zone privée est associée au réseau VPC du consommateur.
  • Les ressources de point de terminaison Private Service Connect (adresse IP interne statique et règle de transfert) et le rattachement de réseau sont créés dans SERVICE_PROJECT_ID. Chacune de ces commandes utilise une référence inter-projet au sous-réseau ou au réseau VPC partagé dans HOST_PROJECT_ID. Dans un déploiement à un seul projet, SERVICE_PROJECT_ID et HOST_PROJECT_ID sont identiques. Il n'y a donc pas de changement de propriété entre les étapes. Pour en savoir plus sur le modèle VPC partagé pour les points de terminaison Private Service Connect, consultez Créer un point de terminaison dans un projet de service VPC partagé.

Créer une zone privée Cloud DNS

Créez une zone privée Cloud DNS qui n'est visible que par votre VPC consommateur. L'agent utilise cette zone (via l'appairage DNS) pour résoudre APIGEE_HOSTNAME en adresse IP privée. 

gcloud dns managed-zones create apigee-private \
  --project=HOST_PROJECT_ID \
  --dns-name="PARENT_DNS_NAME" \
  --description="Private zone for Apigee PSC access" \
  --visibility=private \
  --networks=VPC_NAME

Pour en savoir plus sur les zones privées Cloud DNS, consultez Zones privées.

Créer un rattachement de réseau

Créez un rattachement de réseau dans la même région et le même sous-réseau que ceux où vous souhaitez que l'interface PSC Agent Runtime s'affiche. Agent Runtime lie son interface PSC à ce rattachement lorsque l'agent est déployé.

Dans un déploiement à un seul projet, créez le rattachement de réseau dans SERVICE_PROJECT_ID (qui est également HOST_PROJECT_ID). Dans un déploiement de VPC partagé, vous pouvez créer le rattachement de réseau dans le projet de service ou le projet hôte. Agent Platform recommande le projet de service pour simplifier les autorisations. Pour obtenir des conseils sur le choix des rôles IAM correspondants, consultez Utiliser l'interface Private Service Connect avec un VPC partagé.

La commande suivante crée le rattachement de réseau dans SERVICE_PROJECT_ID. Dans un déploiement de VPC partagé, la référence de sous-réseau doit inclure l'ID du projet hôte. 

gcloud compute network-attachments create agent-network-attachment \
  --project=SERVICE_PROJECT_ID \
  --region=REGION \
  --subnets=projects/HOST_PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME \
  --connection-preference=ACCEPT_AUTOMATIC

Réserver une adresse IP statique interne

Réservez une adresse IP interne à utiliser comme adresse IP du point de terminaison Private Service Connect auquel l'agent se connecte. Créez la ressource d'adresse dans SERVICE_PROJECT_ID et faites référence au sous-réseau partagé dans HOST_PROJECT_ID afin que la valeur de l'adresse soit allouée à partir de la plage de ce sous-réseau. Cela correspond aux conseils sur le VPC partagé dans Utiliser une adresse IP interne statique avec un VPC partagé. 

gcloud compute addresses create apigee-psc-endpoint-ip \
  --project=SERVICE_PROJECT_ID \
  --region=REGION \
  --subnet=projects/HOST_PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME

Récupérez l'adresse réservée, que vous utiliserez lors des étapes suivantes : 

gcloud compute addresses describe apigee-psc-endpoint-ip \
  --project=SERVICE_PROJECT_ID \
  --region=REGION \
  --format="value(address)"

Dans ce document, cette adresse est appelée PSC_ENDPOINT_IP.

Obtenir le rattachement de service pour l'instance Apigee

Récupérez l'URI du rattachement de service pour votre instance Apigee à l'aide de la méthode organizations.instances.get de l'API Apigee. Vous utilisez cet URI comme cible pour le point de terminaison Private Service Connect. 

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://apigee.googleapis.com/v1/organizations/APIGEE_PROJECT_ID/instances/APIGEE_INSTANCE_NAME"

La réponse inclut un champ serviceAttachment. Dans ce document, cette valeur est appelée APIGEE_SERVICE_ATTACHMENT. Pour en savoir plus sur la façon dont Apigee expose un rattachement de service sur chaque instance, consultez Gérer les instances.

Créer le point de terminaison Private Service Connect

Créez une règle de transfert qui sert de point de terminaison Private Service Connect. Il cible le rattachement de service Apigee et utilise l'adresse IP statique que vous avez réservée. Créez la règle de transfert dans SERVICE_PROJECT_ID et référencez le réseau VPC partagé dans HOST_PROJECT_ID et l'adresse dans SERVICE_PROJECT_ID. 

gcloud compute forwarding-rules create apigee-psc-endpoint \
  --project=SERVICE_PROJECT_ID \
  --region=REGION \
  --network=projects/HOST_PROJECT_ID/global/networks/VPC_NAME \
  --address=projects/SERVICE_PROJECT_ID/regions/REGION/addresses/apigee-psc-endpoint-ip \
  --target-service-attachment=APIGEE_SERVICE_ATTACHMENT

Vérifiez que le service Apigee a accepté la connexion : 

gcloud compute forwarding-rules describe apigee-psc-endpoint \
  --project=SERVICE_PROJECT_ID \
  --region=REGION \
  --format="value(pscConnectionStatus)"

L'état doit être ACCEPTED pour que le point de terminaison puisse transférer le trafic. Pour en savoir plus sur les points de terminaison Private Service Connect, consultez À propos de l'accès aux services publiés via des points de terminaison.

Ajouter un enregistrement DNS pour le nom d'hôte

Dans la zone privée, créez un enregistrement A qui résout APIGEE_HOSTNAME en PSC_ENDPOINT_IP. Cet enregistrement n'est visible qu'à l'intérieur de VPC_NAME. Les clients externes continuent donc de résoudre le nom d'hôte via le DNS public. 

gcloud dns record-sets create APIGEE_HOSTNAME. \
  --project=HOST_PROJECT_ID \
  --zone=apigee-private \
  --type=A \
  --ttl=60 \
  --rrdatas=PSC_ENDPOINT_IP

Étape 2 : Configurer Apigee

Ajouter le projet de service à la liste d'acceptation des clients de l'instance

L'instance Apigee n'accepte que les connexions Private Service Connect provenant de projets consommateurs qui figurent dans son consumerAcceptList. Le côté consommateur de la connexion est associé à SERVICE_PROJECT_ID, car il s'agit du projet dans lequel l'agent est déployé.

Par défaut, le projet associé à l'organisation Apigee (APIGEE_PROJECT_ID) figure déjà dans la liste. Si SERVICE_PROJECT_ID est identique à APIGEE_PROJECT_ID, aucune modification n'est nécessaire et vous pouvez ignorer cette section. Sinon, ajoutez SERVICE_PROJECT_ID à la liste.

Commencez par vérifier la valeur actuelle de consumerAcceptList à l'aide de la méthode organizations.instances.get : 

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://apigee.googleapis.com/v1/organizations/APIGEE_PROJECT_ID/instances/APIGEE_INSTANCE_NAME"

Recherchez le champ consumerAcceptList dans la réponse.

Mettez ensuite à jour la liste en appelant la méthode organizations.instances.patch avec un masque de mise à jour sur consumerAcceptList. Étant donné que le champ remplace la liste existante, incluez tous les ID de projet qui doivent conserver l'accès, y compris APIGEE_PROJECT_ID et tous les projets de service supplémentaires qui déploient des agents : 

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{"consumerAcceptList": ["APIGEE_PROJECT_ID", "SERVICE_PROJECT_ID"]}' \
  "https://apigee.googleapis.com/v1/organizations/APIGEE_PROJECT_ID/instances/APIGEE_INSTANCE_NAME?updateMask=consumerAcceptList"

Confirmez la mise à jour en exécutant à nouveau la commande get et en vérifiant que SERVICE_PROJECT_ID est désormais inclus dans consumerAcceptList.

Vérifier le nom d'hôte du groupe d'environnements

Vérifiez que APIGEE_HOSTNAME figure dans le groupe d'environnements qui héberge vos proxys d'API. Si ce n'est pas le cas, ajoutez-le.

Pour obtenir des instructions, consultez Utiliser des groupes d'environnements.

Étape 3 : Déployez votre agent avec une interface PSC et un appairage DNS

Lorsque vous déployez votre agent sur Agent Runtime, configurez-le avec une interface PSC qui fait référence au rattachement de réseau que vous avez créé, et configurez l'appairage DNS vers votre zone privée. Pour connaître la procédure de déploiement complète et les frameworks compatibles, consultez Utiliser l'interface Private Service Connect avec Agent Runtime et Déployer des agents dans la documentation Agent Platform.

Configurez les deux champs suivants dans la configuration de l'interface PSC de l'agent (consultez la référence PscInterfaceConfig) :

  • networkAttachment : définissez ce paramètre sur le nom complet de la ressource du rattachement de réseau que vous avez créé à l'étape 1, au format projects/SERVICE_PROJECT_ID/regions/REGION/networkAttachments/agent-network-attachment. Si vous avez créé le rattachement de réseau dans le projet hôte, utilisez HOST_PROJECT_ID dans ce chemin d'accès.
  • dnsPeeringConfigs : ajoutez une entrée avec les champs suivants pour que Agent Runtime résolve APIGEE_HOSTNAME via votre zone privée :
    • domain : PARENT_DNS_NAME. La valeur doit se terminer par un point.
    • targetProject : HOST_PROJECT_ID. Il s'agit du projet contenant le VPC consommateur et la zone privée.
    • targetNetwork : VPC_NAME.

L'agent de service Agent Platform pour SERVICE_PROJECT_ID (service-SERVICE_PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com) doit être autorisé à configurer l'appairage DNS et à mettre à jour l'association de réseau. Attribuez les rôles requis, comme décrit dans Rôle requis pour l'agent de service Agent Platform. Dans un déploiement de VPC partagé, des rôles supplémentaires s'appliquent au projet hôte. Pour en savoir plus, consultez Utiliser l'interface Private Service Connect avec un VPC partagé.

À partir du code de l'agent, appelez le proxy d'API à l'adresse https://APIGEE_HOSTNAME/BASE_PATH. Dans l'environnement Agent Runtime, ce nom d'hôte est résolu via l'appairage DNS vers PSC_ENDPOINT_IP, et la requête traverse le point de terminaison Private Service Connect dans votre VPC et vers Apigee.

Vérifier le chemin d'accès privé

Après avoir déployé l'agent, vérifiez que les requêtes atteignent Apigee via le chemin privé :

  • Vérifiez que l'état de la règle de transfert est ACCEPTED à l'aide de la commande de la section Créer le point de terminaison Private Service Connect.
  • À partir d'une VM Compute Engine associée à VPC_NAME dans REGION (dans un déploiement de VPC partagé, cette VM peut se trouver dans le projet hôte ou dans un projet de service associé au VPC partagé), exécutez dig +short APIGEE_HOSTNAME. Le résultat doit être PSC_ENDPOINT_IP. Cela confirme que la zone privée résout correctement le nom d'hôte dans le VPC.
  • À partir de la même VM, envoyez une requête à un proxy d'API déployé sur https://APIGEE_HOSTNAME/BASE_PATH et vérifiez que vous recevez la réponse attendue.
  • Appelez l'agent déployé et vérifiez que la requête est traitée. Ensuite, utilisez Apigee Analytics ou Debug pour confirmer que la requête est arrivée au proxy d'API attendu sur le nom d'hôte du groupe d'environnements.

Étapes suivantes