Connecter le processeur d'extension Apigee à une passerelle d'agent

Cette page s'applique à Apigee et à Apigee hybrid.

Consultez la documentation d' Apigee Edge.

Cette page explique comment connecter le processeur d'extension Apigee à une passerelle d'agent afin que les règles Apigee soient appliquées aux appels qu'un agent d'IA effectue à son modèle, à ses outils et aux serveurs MCP (Model Context Protocol) qu'il utilise, sans modifier l'agent.

Une Agent Gateway est le point d'entrée et de sortie du trafic d'un agent sur le réseau. Il ne s'agit pas d'un équilibreur de charge, il n'utilise donc pas d'extension de trafic. Au lieu de cela, la passerelle délègue l'autorisation à une extension d'autorisation, et vous configurez le processeur d'extension comme cette extension. Une fois la connexion établie, la passerelle envoie chaque requête et réponse de l'agent à Apigee pour traitement, et Apigee renvoie un verdict.

La figure suivante montre les ressources que vous créez sur cette page, ainsi que le chemin qu'une requête d'agent unique emprunte à travers elles :

Figure 1. Composants et flux de requêtes lorsque le processeur d'extension Apigee est l'extension d'autorisation pour une passerelle Agent Gateway.

Dans la figure 1, une requête est traitée comme suit :

1. L'agent envoie une requête HTTPS ordinaire à son modèle, à un outil ou à un serveur MCP. L'agent est lié à la passerelle lors de sa création et n'a pas besoin d'être modifié.
2. La passerelle conserve la requête et appelle l'extension d'autorisation pour obtenir un verdict.
3. L'appel sort par le rattachement de réseau. Il provient donc de votre réseau VPC.
4. Votre zone DNS privée résout le nom d'hôte de l'appel sur l'adresse IP interne du point de terminaison Private Service Connect.
5. Le point de terminaison transfère l'appel au rattachement de service de votre instance Apigee.
6. Le groupe d'environnements achemine l'appel par son nom d'hôte vers le proxy sans cible, où vos règles s'exécutent.
7. Le proxy renvoie un verdict à la passerelle. Apigee ne transfère jamais le trafic de l'agent, car le proxy n'a pas de cible.
8. Si le verdict autorise la requête, la passerelle envoie la requête d'origine à sa destination.

Les AuthzPolicy et AuthzExtension de la figure 1 sont des configurations plutôt que du trafic : la règle associe l'extension à la passerelle, et l'extension nomme le proxy du processeur d'extension qui s'exécute. Vous les créez tous les deux dans Configurer l'extension d'autorisation.

Pour connecter le processeur d'extension à un équilibreur de charge, consultez Premiers pas avec le processeur d'extension Apigee.

Les sections suivantes vous guident tout au long de ces étapes :

• Configurez le processeur d'extension Apigee.
• Connectez l'Agent Gateway à Apigee.
• Configurez l'extension d'autorisation.
• Vérifiez la connexion.

Avant de commencer

Avant de commencer, effectuez les tâches suivantes :

1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Roles required to select or create a project

   • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
   • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.
   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

2. Verify that billing is enabled for your Google Cloud project.

3. Enable the Apigee, Compute Engine, Network Services, Network Security, and Cloud DNS APIs.

   Roles required to enable APIs

   To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

   Enable the APIs

4. Installez la Google Cloud CLI.

   Une fois la Google Cloud CLI installée, exécutez la commande gcloud components update pour obtenir les derniers composants gcloud.

5. Provisionnez une instance Apigee, si vous ne l'avez pas déjà fait.

   Dans la console Google Cloud , accédez à la page Instances Apigee.

   Accéder à la page "Instances Apigee"

6. Déployez une passerelle Agent Gateway dans la même région que votre instance Apigee, avec governedAccessPath défini sur AGENT_TO_ANYWHERE afin que la passerelle régisse le trafic sortant de l'agent. Pour en savoir plus, consultez Configurer Agent Gateway.

   Vous mettrez à jour la configuration réseau de cette passerelle plus tard, dans Mettre à jour l'Agent Gateway, une fois la zone DNS créée.

7. Vérifiez que vous disposez d'un VPC et d'un sous-réseau que l'Agent Gateway et le point de terminaison Private Service Connect peuvent utiliser.

   Accéder aux réseaux VPC

Rôles requis

Pour obtenir les autorisations nécessaires pour connecter le processeur d'extension Apigee à une passerelle d'agent, demandez à votre administrateur de vous accorder les rôles IAM suivants :

• Créer et gérer des ressources Apigee : Administrateur de l'organisation Apigee (roles/apigee.admin) sur l'organisation
• Créer et gérer des extensions de service : Administrateur Service Extensions (roles/networkservices.serviceExtensionsAdmin) au niveau de l'organisation
• Créer et gérer des règles d'autorisation : Administrateur de la sécurité du réseau (roles/networksecurity.admin) sur l'organisation
• Créer et gérer des ressources réseau, y compris des points de terminaison Private Service Connect et DNS : Administrateur de réseaux Compute (roles/compute.networkAdmin) au niveau de l'organisation

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

Définir des variables d'environnement

Définissez les variables d'environnement suivantes pour identifier les ressources que vous avez créées dans Avant de commencer. Chaque section ultérieure de cette page définit les variables supplémentaires dont elle a besoin, au moment où vous créez la ressource qu'elle nomme.

export PROJECT_ID=PROJECT_ID
export ORG_NAME=$PROJECT_ID
export REGION=REGION
export INSTANCE=INSTANCE
export VPC_NETWORK_NAME=VPC_NETWORK_NAME
export SUBNET=SUBNET
export GATEWAY=GATEWAY

Où :

• PROJECT_ID est l'ID du projet qui contient votre instance Apigee.
• REGION est la région Google Cloud de votre instance Apigee.
• INSTANCE est le nom de votre instance Apigee.
• VPC_NETWORK_NAME et SUBNET sont le réseau VPC et le sous-réseau utilisés par l'Agent Gateway et le point de terminaison Private Service Connect.
• GATEWAY correspond au nom de l'Agent Gateway que vous avez déployée.

Pour vérifier que les variables d'environnement sont correctement définies, exécutez la commande suivante et examinez le résultat :

echo $PROJECT_ID $ORG_NAME $REGION $INSTANCE $VPC_NETWORK_NAME $SUBNET $GATEWAY

Choisissez le nom d'hôte de l'accroche.

La passerelle contacte Apigee à l'aide d'un nom d'hôte privé de votre choix. Vous le choisissez maintenant, avant de créer quoi que ce soit, car la première ressource que vous créez (le groupe d'environnements Apigee) l'utilise comme nom d'hôte, tandis que la zone DNS qui le résout n'est créée qu'à l'étape Créer une zone DNS privée.

export DNS_DOMAIN=DNS_DOMAIN
export EXTPROC_HOST=apigee-extproc.$DNS_DOMAIN

Où DNS_DOMAIN est un domaine DNS privé qui ne doit pas nécessairement être résolvable sur l'Internet public, écrit sans point à la fin, par exemple internal.example.com. Cela donne un EXTPROC_HOST de apigee-extproc.internal.example.com. Vous pouvez utiliser un libellé autre que apigee-extproc, à condition que le nom d'hôte reste dans DNS_DOMAIN.

Important : EXTPROC_HOST est utilisé à trois endroits : le nom d'hôte du groupe d'environnements Apigee, l'enregistrement DNS privé et les champs authority et service de l'extension d'autorisation. Les trois doivent être identiques, sinon l'appel n'atteindra jamais Apigee. Le nom d'hôte doit également se trouver dans DNS_DOMAIN. C'est pourquoi la commande ci-dessus le dérive de cette variable.

Configurer un jeton d'authentification

export TOKEN=$(gcloud auth print-access-token)
echo $TOKEN

Remarque : Si votre organisation utilise la résidence des données, remplacez apigee.googleapis.com dans les commandes de cette page par le point de terminaison régional de votre organisation. Pour en savoir plus, consultez Utiliser des points de terminaison régionaux pour la résidence des données.

Configurer le processeur d'extension Apigee

Nommez les ressources Apigee que cette section crée :

export EXTPROC_ENV=EXTPROC_ENV
export EXTPROC_ENVGROUP=EXTPROC_ENVGROUP
export PROXY_NAME=PROXY_NAME

Où :

• EXTPROC_ENV et EXTPROC_ENVGROUP sont des noms que vous choisissez pour un environnement et un groupe d'environnements Apigee dédiés au processeur d'extension, par exemple extproc-env et extproc-envgroup. Chaque nom doit comporter entre 2 et 32 caractères (lettres minuscules, chiffres ou traits d'union), commencer par une lettre et ne pas se terminer par un trait d'union. Le nom de l'environnement doit être différent de tous les autres noms d'environnement de votre organisation.
• PROXY_NAME est le nom que vous choisissez pour le proxy du processeur d'extension, par exemple extproc-authz.

La configuration côté Apigee est la même que pour un équilibreur de charge. Suivez la section Configurer le processeur d'extension Apigee du guide de démarrage rapide pour :

1. Créez un environnement Apigee avec la propriété apigee-service-extension-enabled définie sur true, associez-le à votre instance et créez un groupe d'environnements dont le nom d'hôte est $EXTPROC_HOST.
2. Créez et déployez un proxy de processeur d'extension sans cible dans cet environnement.

Remarque : Le guide de démarrage rapide nomme ces ressources ENV_NAME, ENV_GROUP_NAME et ENV_GROUP_HOSTNAME. Utilisez respectivement $EXTPROC_ENV, $EXTPROC_ENVGROUP et $EXTPROC_HOST.

Remarque : Si une règle du proxy appelle une API Google Cloud , déployez le proxy avec un compte de service en ajoutant ?serviceAccount=SERVICE_ACCOUNT_EMAIL à la requête de déploiement. Sinon, le déploiement échoue avec MISSING_SERVICE_ACCOUNT.

Ensuite, listez les déploiements dans l'environnement :

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/environments/$EXTPROC_ENV/deployments"

Plusieurs proxys peuvent être déployés dans l'environnement. Dans la réponse, recherchez l'entrée dont le apiProxy est $PROXY_NAME et notez son revision.

Vous pouvez examiner le proxy dans la console Google Cloud  :

Accéder aux proxys d'API

Définissez la variable suivante sur cette révision, dont vous aurez besoin dans Vérifier la connexion :

export REVISION=REVISION

Connecter l'Agent Gateway à Apigee

La passerelle accède à Apigee via un point de terminaison Private Service Connect dans votre VPC, qu'elle trouve en résolvant $EXTPROC_HOST dans une zone DNS privée.

Rechercher le rattachement de service

Recherchez le rattachement de service de votre instance Apigee :

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/instances"

Définissez la variable suivante sur la valeur serviceAttachment de l'instance dans votre région :

export SERVICE_ATTACHMENT=SERVICE_ATTACHMENT

Créer un rattachement de réseau

L'Agent Gateway sort de votre VPC via un rattachement de réseau. Choisissez un nom pour le fichier, par exemple agent-gateway-attachment, puis créez-le :

export NETWORK_ATTACHMENT=NETWORK_ATTACHMENT
gcloud compute network-attachments create $NETWORK_ATTACHMENT \
    --region=$REGION --subnets=$SUBNET --connection-preference=ACCEPT_AUTOMATIC

Créer le point de terminaison Private Service Connect

Réservez une adresse IP interne et créez le point de terminaison Private Service Connect :

gcloud compute addresses create apigee-extproc-psc-ip \
    --region=$REGION --subnet=$SUBNET --purpose=GCE_ENDPOINT
gcloud compute forwarding-rules create apigee-extproc-psc-endpoint \
    --region=$REGION --network=$VPC_NETWORK_NAME \
    --address=apigee-extproc-psc-ip \
    --target-service-attachment=$SERVICE_ATTACHMENT

Dans la console Google Cloud , accédez à la page Private Service Connect .

Accéder à Private Service Connect

Vérifiez que le point de terminaison indique pscConnectionStatus: ACCEPTED et définissez la variable suivante sur son adresse IP :

gcloud compute forwarding-rules describe apigee-extproc-psc-endpoint \
    --region=$REGION --format="value(pscConnectionStatus,IPAddress)"
export PSC_IP=PSC_IP

Si l'état est PENDING, votre projet ne figure pas dans le consumerAcceptList de l'instance Apigee et la connexion ne peut pas être acceptée.

Créer une zone DNS privée

Créez une zone DNS privée pour $DNS_DOMAIN et un enregistrement A qui résout $EXTPROC_HOST en adresse IP du point de terminaison :

gcloud dns managed-zones create extproc-zone \
    --dns-name=$DNS_DOMAIN. --visibility=private --networks=$VPC_NETWORK_NAME \
    --description="Apigee extension processor callout host"
gcloud dns record-sets create $EXTPROC_HOST. --type=A --ttl=300 \
    --rrdatas=$PSC_IP --zone=extproc-zone

Mettre à jour l'Agent Gateway

Mettez à jour Agent Gateway à partir de la section Avant de commencer afin qu'il sorte via votre attachement réseau et puisse résoudre la zone que vous avez créée.

Attention : L'importation d'une Agent Gateway remplace l'intégralité de la ressource. Commencez toujours par la configuration exportée et modifiez-la, plutôt que d'écrire un nouveau fichier. Les champs que vous omettez, tels que protocols et registries, sont supprimés de la passerelle.

1. Exportez la configuration actuelle :

   gcloud network-services agent-gateways export $GATEWAY \
       --location=$REGION --destination=agent-gateway.yaml

2. Dans agent-gateway.yaml, ajoutez le bloc networkConfig suivant, en remplaçant chaque espace réservé par la valeur de la variable d'environnement correspondante. Le fichier est modifié directement. Les variables shell ne sont donc pas remplacées ici :

   networkConfig:
     egress:
       networkAttachment: projects/PROJECT_ID/regions/REGION/networkAttachments/NETWORK_ATTACHMENT
     dnsPeeringConfig:
       domains: [ DNS_DOMAIN. ]
       targetProject: PROJECT_ID
       targetNetwork: projects/PROJECT_ID/global/networks/VPC_NETWORK_NAME

   Conservez le reste du fichier tel qu'il a été exporté, y compris googleManaged.governedAccessPath, protocols et registries.

3. Importez la configuration modifiée :

   gcloud network-services agent-gateways import $GATEWAY \
       --location=$REGION --source=agent-gateway.yaml

Pour obtenir l'ensemble des champs de la passerelle d'agent, consultez Configurer la passerelle d'agent.

Configurer l'extension d'autorisation

Deux ressources connectent la passerelle à votre proxy de processeur d'extension : une extension d'autorisation qui pointe vers Apigee et une règle d'autorisation qui associe l'extension à la passerelle.

Créer l'extension d'autorisation

Choisissez un nom pour l'extension d'autorisation, par exemple apigee-authz-extension. Les champs metadata permettent de sélectionner le proxy Apigee à exécuter et d'indiquer si les corps de message lui sont envoyés :

export AUTHZ_EXT=AUTHZ_EXT
cat > authz-extension.yaml <<EOF
name: projects/$PROJECT_ID/locations/$REGION/authzExtensions/$AUTHZ_EXT
authority: $EXTPROC_HOST
service: $EXTPROC_HOST
timeout: 5s
metadata:
  apigee-extension-processor: $PROXY_NAME
  apigee-request-body: 'true'
  apigee-response-body: 'true'
EOF
gcloud service-extensions authz-extensions import $AUTHZ_EXT \
    --source=authz-extension.yaml --location=$REGION

Où :

• apigee-extension-processor sélectionne le proxy du processeur d'extension qui traite le trafic.
• apigee-request-body et apigee-response-body rendent les corps de requête et de réponse disponibles dans le proxy sous la forme request.content et response.content. Sans eux, les règles qui inspectent la charge utile ne trouvent rien.

Créer la règle d'autorisation

Choisissez un nom pour la règle d'autorisation, par exemple apigee-content-authz-policy. La règle associe l'extension à la passerelle et détermine le trafic à envoyer à Apigee :

export AUTHZ_POLICY=AUTHZ_POLICY
cat > authz-policy.yaml <<EOF
name: projects/$PROJECT_ID/locations/$REGION/authzPolicies/$AUTHZ_POLICY
action: CUSTOM
policyProfile: CONTENT_AUTHZ
customProvider:
  authzExtension:
    resources:
    - projects/$PROJECT_ID/locations/$REGION/authzExtensions/$AUTHZ_EXT
httpRules:
- to:
    operations:
    - paths:
      - prefix: "/"
target:
  resources:
  - projects/$PROJECT_ID/locations/$REGION/agentGateways/$GATEWAY
EOF
gcloud beta network-security authz-policies import $AUTHZ_POLICY \
    --source=authz-policy.yaml --location=$REGION

Utilisez policyProfile: CONTENT_AUTHZ pour que les corps des messages soient inspectés. Une règle REQUEST_AUTHZ n'évalue que les en-têtes de requête.

Important : L'exemple ci-dessus fait correspondre chaque requête à prefix: "/", ce qui envoie tout le trafic de l'agent à Apigee, y compris ses appels de session, de télémétrie et d'outil. Réduisez le champ d'application avec to.operations.paths ou avec une expression CEL (Common Expression Language) dans un champ when, afin que seul le trafic que vous souhaitez régir soit traité.

Vérifier la connexion

Pour générer du trafic, vous avez besoin d'un agent dont la sortie est régie par cette passerelle. Un agent est lié à une passerelle lors de sa création, en définissant sa configuration Agent Gateway sur $GATEWAY. Vous ne pouvez pas exercer la connexion avec une requête HTTP directe à la passerelle. Pour en savoir plus, consultez Configurer la passerelle d'agent.

Démarrez une session de débogage Apigee sur le proxy du processeur d'extension, puis envoyez une requête via l'agent :

curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/environments/$EXTPROC_ENV/apis/$PROXY_NAME/revisions/$REVISION/debugsessions?timeout=600" \
  -d '{"count":15,"tracesize":5120,"filter":"(request.uri Like \"*generateContent*\")"}'

Remarque : Un seul tour d'agent génère plusieurs transactions, car les appels de session et de télémétrie de l'agent passent également par la passerelle. Utilisez le champ filter pour n'enregistrer que le trafic que vous souhaitez inspecter. Sinon, le tampon peut se remplir avant l'arrivée de la requête que vous recherchez.

Dans les transactions capturées, vérifiez que :

• L'URL de la requête est l'adresse appelée par l'agent, telle que le point de terminaison du modèle ou un hôte d'outil, plutôt qu'un chemin de base Apigee.
• request.content et response.content sont renseignés, ce qui confirme que les métadonnées du corps de l'extension d'autorisation fonctionnent.

Si aucune transaction n'apparaît, vérifiez que le nom d'hôte du groupe d'environnements, l'enregistrement DNS et les champs authority et service de l'extension sont tous définis sur $EXTPROC_HOST, que le point de terminaison Private Service Connect indique ACCEPTED et que le champ governedAccessPath de la passerelle est défini sur AGENT_TO_ANYWHERE.

Étapes suivantes

• Consultez la présentation du processeur d'extension Apigee.
• Commencez à utiliser le processeur d'extension Apigee sur un équilibreur de charge.