Configurer Agent Gateway avec la connectivité VPC

Ce document vous guide tout au long du processus de configuration de la connectivité VPC lors du déploiement d'une Agent Gateway afin qu'elle puisse communiquer de manière privée avec un réseau VPC de votre organisation.

La configuration de la connectivité VPC vous permet d'effectuer les opérations suivantes :

  • Appliquer la sortie VPC pour le trafic : acheminez le trafic provenant de vos agents via votre rattachement de réseau Private Service Connect vers votre réseau VPC en mode PRIVATE_RANGES_ONLY ou ALL_TRAFFIC.
  • Plage d'adresses IP sources statiques : le trafic de sortie utilise la plage d'adresses IP privées du sous-réseau de rattachement de réseau Private Service Connect comme adresse IP source. Cette plage d'adresses IP sources statiques vous permet de configurer des stratégies de pare-feu pour votre réseau VPC afin de régir le trafic provenant de la passerelle.
  • Résolution DNS personnalisée : résolvez les noms de domaine privés internes et les noms de domaine externes directement à partir de vos agents à l'aide de l'appairage Cloud DNS.
  • Sécurité du périmètre : protégez les communications des agents à l'aide des périmètres de service VPC Service Controls.
  • Validation de certificats privés ou autosignés : connectez-vous à des destinations qui utilisent des autorités de certification privées ou des certificats autosignés.

Pour configurer la connectivité VPC, vous devez créer un modèle de connectivité Agent Gateway (AgentConnectivityTemplate) dans lequel vous définissez et gérez les paramètres de mise en réseau de sortie pour vos instances Agent Gateway.

Fonctionnement de la connectivité VPC

Lorsque vous déployez une Agent Gateway avec un modèle de connectivité, la passerelle utilise une interface Private Service Connect pour acheminer le trafic sortant de l'agent vers le réseau VPC que vous avez désigné.

Modes de sortie VPC

Vous configurez la manière dont la passerelle achemine le trafic via votre rattachement de réseau à l'aide du paramètre vpcEgress dans votre modèle de connectivité.

  • Trafic vers les plages d'adresses IP privées (PRIVATE_RANGES_ONLY) : achemine le trafic destiné uniquement aux plages d'adresses IP privées vers votre réseau VPC. Le trafic sortant n'est acheminé vers votre réseau VPC que si l'adresse IP de destination se trouve dans l'une des plages suivantes :

    • RFC 1918 : 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16
    • RFC 6598 : 100.64.0.0/10
    • Classe E : 240.0.0.0/4
    • private.googleapis.com : 199.36.153.8/30
    • restricted.googleapis.com : 199.36.153.4/30
    • Points de terminaison PSC pour les API Google : si vous déployez un point de terminaison Private Service Connect personnalisé pour les API Google à l'aide d'une adresse IP privée interne dans votre réseau VPC, le trafic vers ce point de terminaison est acheminé via votre réseau VPC. Assurez-vous que l'appairage Cloud DNS est configuré dans le modèle de connectivité afin qu'Agent Gateway résolve correctement les domaines des API Google vers l'adresse IP de votre point de terminaison PSC interne.

    Les requêtes adressées aux API Google publiques standards sont gérées automatiquement à l'aide de l'accès privé à Google, et le trafic vers Internet est acheminé directement via Agent Gateway plutôt que via votre réseau VPC.

  • Trafic vers toutes les plages d'adresses IP (ALL_TRAFFIC) : achemine tout le trafic sortant provenant de vos agents via votre réseau VPC, y compris l'Internet public, les API SaaS externes et les adresses non-RFC 1918.

    • Routage et sécurité : étant donné que ce paramètre achemine tout le trafic sortant vers votre VPC, vous êtes responsable de la gestion de son routage et de sa sécurité. Assurez-vous que votre réseau VPC dispose d'une route par défaut (0.0.0.0/0) pour transférer ce trafic vers vos passerelles sortantes ou vos dispositifs de sécurité (tels que les pare-feu de saut suivant ou les interfaces Cloud Interconnect).
    • Sortie Internet publique : Agent Gateway envoie le trafic sortant vers votre réseau VPC, d'où il sort vers l'Internet public via une passerelle Cloud NAT sur le sous-réseau de rattachement de réseau Private Service Connect. Si vous attribuez des adresses IP externes statiques à la passerelle Cloud NAT, les services distants peuvent ajouter le trafic de sortie de vos agents à une liste d'autorisation en fonction de ces adresses IP sources.
    • VPC Service Controls : le mode de sortie doit être défini sur ALL_TRAFFIC pour prendre en charge les périmètres de service VPC Service Controls.

Résolution DNS et routage du trafic

Par défaut, Agent Gateway résout les noms de domaine à l'aide d'un DNS récursif public. Si vos agents doivent accéder à des charges de travail internes, à des outils privés ou à des API Google hébergées sur des noms de domaine privés de votre réseau VPC (comme corp.internal. ou des points de terminaison PSC), vous pouvez configurer l'appairage Cloud DNS pour transférer les requêtes DNS vers les zones gérées Cloud DNS privées de votre réseau.

Le tableau suivant récapitule les exigences d'appairage Cloud DNS et le comportement de routage du trafic pour différentes destinations lorsque la connectivité VPC est configurée en mode ALL_TRAFFIC :

Tableau : Résolution DNS et routage du trafic en mode ALL_TRAFFIC
Destination du trafic Appairage Cloud DNS requis ? Résolution DNS Chemin de sortie
Services d'adresses IP privées
(RFC 1918/internes)
Oui (par exemple, corp.internal.) Résolution à l'aide de l'appairage Cloud DNS avec la zone gérée Cloud DNS privée de votre réseau VPC cible. Le trafic entre dans votre réseau VPC via le rattachement de réseau pour se connecter aux charges de travail internes.
Noms d'hôte publics avec adresses IP privées
(DNS fractionné)
Non Résout les requêtes à l'aide du DNS récursif public standard au niveau du proxy de la passerelle, sans nécessiter d'appairage Cloud DNS. Le trafic entre dans votre réseau VPC via le rattachement de réseau pour se connecter aux charges de travail internes.
Internet public et API SaaS
(domaines externes)
Non Résout les requêtes à l'aide du DNS récursif public standard au niveau du proxy de la passerelle, sans nécessiter d'appairage Cloud DNS. Le trafic entre dans votre réseau VPC via le rattachement de réseau et en sort vers l'Internet public à l'aide de Cloud NAT configuré sur le sous-réseau.
Google Cloud API
(standard, sans VPC Service Controls)
Non Résout les requêtes à l'aide du DNS récursif public standard au niveau du proxy de la passerelle, sans nécessiter d'appairage Cloud DNS. Le trafic entre dans votre réseau VPC via le rattachement de réseau et est acheminé de manière privée à l'aide de l'accès privé à Google activé sur le sous-réseau, sans utiliser Cloud NAT ni l'appairage DNS.
APIGoogle Cloud
(avec VPC Service Controls)
Oui (pour googleapis.com.) Résout la plage d'API Google restreinte (199.36.153.4/30) ou les points de terminaison Private Service Connect internes à l'aide d'une zone Cloud DNS privée. Le trafic entre dans votre réseau VPC via le rattachement de réseau pour appliquer les règles de sécurité du périmètre VPC Service Controls1.

1 Si les requêtes échouent en raison de non-respects de VPC Service Controls tels que NETWORK_NOT_IN_SAME_SERVICE_PERIMETER ou SECURITY_POLICY_VIOLATED sur compute.googleapis.com ou dns.googleapis.com qui font référence au projet hôte, vérifiez que le projet hôte se trouve dans le même périmètre que le projet de passerelle.

Exigences concernant les certificats TLS

Lors du routage du trafic de sortie via HTTPS, Agent Gateway valide la chaîne de certificats TLS du serveur de destination lors du handshake TLS. Les exigences de certificat pour les connexions HTTPS dépendent de l'utilisation par vos points de terminaison cibles d'autorités de certification (CA) publiques ou privées/autosignées.

  • Autorités de certification publiques : par défaut, Agent Gateway approuve les certificats émis par des autorités de certification (CA) de confiance publique qui répondent aux exigences standards des certificats de serveur (y compris un autre nom de l'objet (SAN) correspondant au nom d'hôte cible).

  • Autorités de certification privées et certificats autosignés : si votre destination cible (agents, outils ou serveurs MCP de votre réseau VPC) utilise une autorité de certification privée ou une infrastructure PKI interne, vous pouvez configurer des ancres de confiance personnalisées à l'aide du paramètre tlsConfig de votre modèle de connectivité.

    En référençant une ressource Certificate Manager TrustConfig, vous pouvez configurer Agent Gateway pour qu'il ne fasse confiance qu'à des autorités de certification privées spécifiques, ou combiner des autorités de certification racines privées avec des autorités de certification publiques de confiance (PUBLICLY_TRUSTED_ROOTS). Cela permet d'établir une relation de confiance pour les points de terminaison publics et privés.

    Si vos agents se connectent aux API Google Cloud (*.googleapis.com) ou à d'autres points de terminaison HTTPS publics, vous devez définir additionalRoots sur PUBLICLY_TRUSTED_ROOTS. Sans ce paramètre, Agent Gateway ne fait pas confiance aux certificats signés par Google pour googleapis.com.

    Tenez compte des limites suivantes lorsque vous utilisez tlsConfig :

    • Lorsque vous utilisez des trustConfig pour acheminer le trafic vers des destinations qui utilisent des autorités de certification privées, vous devez effectuer une rotation manuelle des fichiers PEM. La rotation automatisée des fichiers PEM à l'aide de gestionnaires de secrets, tels que Secret Manager deGoogle Cloud, n'est pas prise en charge.
    • Le champ trustConfig est immuable une fois configuré sur un modèle de connectivité, et Agent Gateway ne récupère pas automatiquement les modifications apportées à tlsConfig (comme la mise à jour de additionalRoots) sur un modèle de connectivité associé. Pour savoir comment mettre à jour les paramètres TLS, consultez Mettre à jour les paramètres de sortie VPC.

Si Agent Gateway ne parvient pas à valider la chaîne de certificats, la connexion échoue.

Rôles et autorisations nécessaires

Pour configurer la connectivité VPC pour Agent Gateway, assurez-vous que l'identité utilisée pour le provisionnement et l'agent de service de la passerelle disposent des rôles requis.

Déploiements de projets autonomes

Dans un projet autonome où la passerelle, le rattachement de réseau et le réseau VPC résident dans le même projet, les autorisations Agent Gateway standards s'appliquent. Pour en savoir plus, consultez Autorisations requises.

Si vous configurez un rattachement de réseau, l'identité qui crée ou met à jour le modèle de connectivité de la passerelle ou de l'agent (votre compte utilisateur ou votre compte de service de déploiement) doit également disposer de l'autorisation compute.networkAttachments.use sur le rattachement de réseau, par exemple via le rôle d'administrateur de réseau Compute (roles/compute.networkAdmin) sur le projet contenant le rattachement de réseau. Le rôle "Utilisateur de réseau Compute" n'est pas suffisant. Sans cette autorisation, la requête échoue et renvoie une erreur PERMISSION_DENIED qui nomme le rattachement de réseau.

De plus, si vous configurez l'appairage DNS, Agent Gateway valide la configuration de l'appairage DNS (ainsi que tout rattachement de réseau et son sous-réseau) à l'aide de l'agent de service Agent Gateway (service-AGENT_GATEWAY_PROJECT_NUMBER@gcp-sa-agentgateway.iam.gserviceaccount.com). Attribuez à l'agent de service les rôles suivants sur le projet contenant le réseau VPC cible, le rattachement de réseau et les zones DNS privées (votre propre projet dans un déploiement autonome) :

  • Lecteur de réseau Compute (roles/compute.networkViewer)
  • Lecteur DNS (roles/dns.reader)

Ces rôles ne sont pas attribués automatiquement. Les rattachements de réseau seuls, sans appairage DNS, n'en ont pas besoin.

Sans ces rôles, la création ou la mise à jour d'un modèle de connectivité de passerelle ou d'agent qui configure l'appairage DNS échoue à la validation avec une erreur INVALID_ARGUMENT qui indique l'agent de service et le rôle manquant.

Déploiements de VPC partagé ou inter-projets

Dans un déploiement de VPC partagé, vous pouvez provisionner Agent Gateway dans un projet de service ou dans le projet hôte. Si vous provisionnez la passerelle dans le projet hôte (où résident également le réseau VPC partagé, le sous-réseau et le rattachement de réseau), les autorisations de projet autonome s'appliquent.

Si vous provisionnez l'Agent Gateway dans un projet de service alors que le réseau VPC cible, le rattachement de réseau ou les zones DNS privées résident dans le projet hôte (TARGET_VPC_PROJECT_ID), les identités du projet de service ne disposent pas automatiquement des autorisations nécessaires pour valider, rattacher ou appairer des ressources réseau et DNS dans le projet hôte. Attribuez les rôles suivants sur le projet hôte en plus des autorisations Agent Gateway standards :

Tableau : Autorisations requises pour les déploiements de VPC partagés et inter-projets
Compte principal ou identité Accorder sur le projet Rôle IAM requis Objectif
Identité de provisionnement1
(Compte utilisateur ou compte de service de déploiement)
Projet hôte (TARGET_VPC_PROJECT_ID)
  • Lecteur de réseau Compute (roles/compute.networkViewer)
  • Lecteur DNS (roles/dns.reader)
  • Administrateur de point de terminaison régional Connectivité réseau (roles/networkconnectivity.regionalEndpointAdmin)
  • Administrateur du réseau client Connectivité réseau (roles/networkconnectivity.consumerNetworkAdmin)
  • Administrateur de réseaux Compute (roles/compute.networkAdmin) sur le projet contenant le rattachement de réseau, pour l'autorisation compute.networkAttachments.use
Permet à l'identité de provisionnement d'afficher le réseau du projet hôte et les ressources DNS privées, par exemple dans la console Google Cloud , de gérer le point de terminaison régional et d'utiliser le rattachement de réseau. C'est l'agent de service Agent Gateway, et non l'identité de provisionnement, qui valide le réseau VPC cible, les sous-réseaux, le rattachement de réseau et les zones DNS privées lors de la création ou de la mise à jour de la passerelle.
Créateur de rattachement de réseau
(administrateur créant le rattachement PSC)
Projet hôte (TARGET_VPC_PROJECT_ID)
  • Utilisateur de réseau Compute (roles/compute.networkUser)
Permet d'utiliser un sous-réseau de VPC partagé dans le projet hôte pour créer un rattachement de réseau Private Service Connect.
Rattachement de réseau dans le projet de service (recommandé)
Agent de service Agent Gateway2 Projet hôte (TARGET_VPC_PROJECT_ID)
  • Utilisateur de réseau Compute (roles/compute.networkUser)
  • Lecteur de réseau Compute (roles/compute.networkViewer)
  • Lecteur DNS (roles/dns.reader)
  • Appairage DNS (roles/dns.peer)
Permet à l'agent de service Agent Gateway d'utiliser le sous-réseau du projet hôte pour le rattachement de réseau, de connecter l'interface Private Service Connect pour acheminer le trafic de sortie et de s'appairer avec des zones Cloud DNS privées dans le projet hôte. Permet également à l'agent de service de valider le réseau VPC, les sous-réseaux et les zones DNS privées cibles lors de la création ou de la mise à jour de la passerelle.
Agent de service Agent Gateway2 Projet de service (AGENT_GATEWAY_PROJECT_ID)
  • Lecteur de réseau Compute (roles/compute.networkViewer)
Permet à l'agent de service de lire le rattachement de réseau, qui se trouve dans le projet de service, lorsqu'il valide une configuration d'appairage DNS lors de la création ou de la mise à jour de la passerelle. Le rôle par défaut de l'agent de service n'inclut pas compute.networkAttachments.get.
Rattachement de réseau dans le projet hôte
Agent de service Agent Gateway2 Projet hôte (TARGET_VPC_PROJECT_ID)
  • Administrateur de réseaux Compute (roles/compute.networkAdmin) ou un rôle personnalisé avec :
    • compute.networkAttachments.get
    • compute.networkAttachments.update
    • compute.regionOperations.get
  • Lecteur de réseau Compute (roles/compute.networkViewer)
  • Lecteur DNS (roles/dns.reader)
  • Appairage DNS (roles/dns.peer)
Permet à l'agent de service Agent Gateway de mettre à jour le rattachement de réseau du projet hôte pour autoriser la connexion depuis le projet locataire Agent Gateway, d'acheminer le trafic sortant et d'appairer des zones Cloud DNS privées dans le projet hôte. Permet également à l'agent de service de valider le réseau VPC cible, les sous-réseaux, le rattachement de réseau et les zones DNS privées lors de la création ou de la mise à jour de la passerelle.

1 Pour l'identité de provisionnement, les rôles de base au niveau du projet, tels que Lecteur (roles/viewer) ou Éditeur (roles/editor) sur le projet hôte, sont également suffisants.

2 L'agent de service Agent Gateway est au format service-AGENT_GATEWAY_PROJECT_NUMBER@gcp-sa-agentgateway.iam.gserviceaccount.com, où AGENT_GATEWAY_PROJECT_NUMBER est le numéro du projet dans lequel vous provisionnez Agent Gateway. Pour les déploiements de VPC partagé, ce projet peut être un projet de service ou le projet hôte.

Si vous connectez plusieurs projets de service Agent Runtime à un projet hôte Agent Gateway, vous devez également accorder un accès interprojets sur le projet de passerelle à chaque agent de service Agent Runtime. Pour les déploiements à grande échelle, consultez Effectuer le scaling des projets de service Agent Runtime avec un groupe Google.

Configurer la connectivité VPC

Pour déployer une Agent Gateway avec un modèle de connectivité, suivez les étapes décrites dans les sections suivantes.

Créer un rattachement de réseau Private Service Connect

Créez un rattachement de réseau Private Service Connect dans votre réseau VPC cible.

Assurez-vous que votre rattachement de réseau répond aux exigences suivantes :

  • Préférence de connexion : configurez le rattachement de réseau pour accepter automatiquement les connexions (--connection-preference=ACCEPT_AUTOMATIC).
  • Exigence concernant le même réseau VPC : le sous-réseau de rattachement de réseau et le réseau cible configuré pour l'appairage DNS (targetNetwork) doivent se trouver exactement dans le même réseau VPC. Si le sous-réseau du rattachement de réseau appartient à un réseau différent de celui de la cible d'appairage DNS, la validation de la configuration échoue.
  • Compatibilité avec la MTU du réseau VPC : Agent Gateway est compatible avec une unité de transmission maximale (MTU) de 1 500 octets maximum pour le réseau VPC qui contient le sous-réseau du rattachement de réseau. Si ce réseau VPC utilise une MTU plus grande, comme des trames géantes, contactez Cloud Customer Care pour aligner le service producteur Agent Gateway sur votre MTU VPC personnalisée.
  • Exigences concernant les sous-réseaux : tenez compte des exigences suivantes pour le sous-réseau de rattachement de réseau :
    • Plage de sous-réseau : le sous-réseau de rattachement de réseau accepte toutes les plages valides.
    • Taille du sous-réseau : Agent Gateway nécessite un sous-réseau /28 minimum pour le rattachement de réseau. Un sous-réseau /28 fournit 12 adresses IP utilisables, ce qui est suffisant pour une seule instance Agent Gateway. Si vous prévoyez de connecter plusieurs passerelles au même rattachement de réseau ou sous-réseau, utilisez un sous-réseau plus grand (tel que /26 ou /24) pour éviter l'épuisement des adresses IP.
    • Exigence concernant l'accès privé à Google : vous devez activer l'accès privé à Google (private_ip_google_access = true) sur le sous-réseau hébergeant le rattachement de réseau.
  • Déploiements de VPC partagé : pour les déploiements de VPC partagé, consultez Topologies de déploiement de VPC partagé.

Notez l'URI complet de la ressource du rattachement de réseau (par exemple, projects/NETWORK_ATTACHMENT_PROJECT_NUMBER/regions/NETWORK_ATTACHMENT_REGION/networkAttachments/NETWORK_ATTACHMENT_NAME). Vous en aurez besoin lorsque vous créerez la ressource de modèle de connectivité lors d'une étape ultérieure.

Facultatif : Configurer l'appairage DNS

L'appairage DNS permet à Agent Gateway de résoudre les noms DNS à l'aide des enregistrements d'une zone gérée privée Cloud DNS de votre réseau VPC. L'appairage DNS n'est requis que lorsque vos agents doivent résoudre des noms de domaine internes privés (comme corp.internal.) ou appliquer VPC Service Controls pour les API Google (googleapis.com.). Il n'est pas requis pour les domaines Internet publics ni pour les API Google standards sans VPC Service Controls.

Agent Gateway n'est compatible avec l'appairage DNS transitif que jusqu'à un seul saut transitif, ce qui signifie un maximum de trois réseaux VPC. Par exemple, vpc-net-a (le réseau locataire de l'Agent Gateway) peut s'appairer à vpc-net-b (réseau associé), qui s'appaire à son tour à vpc-net-c (réseau distant) pour résoudre les requêtes DNS dans la chaîne.

Pour configurer l'appairage DNS, procédez comme suit :

  1. Configurez votre zone DNS privée dans votre réseau VPC cible. Pour ajouter des enregistrements DNS à votre zone DNS privée, consultez Ajouter un jeu d'enregistrements de ressources.

  2. Rassemblez les informations suivantes pour configurer le modèle de connectivité afin d'activer l'appairage :

    • URI du réseau cible (targetNetwork) : notez l'URI complet de la ressource du réseau VPC cible au format suivant : projects/TARGET_VPC_PROJECT_ID/global/networks/TARGET_VPC_NETWORK_NAME. Le réseau cible est toujours le réseau VPC qui contient le sous-réseau référencé par le rattachement de réseau. Si le réseau cible est un réseau VPC partagé, veillez à utiliser l'ID du projet hôte de VPC partagé correspondant.

    • Noms de domaine : un ou plusieurs suffixes de domaine pour l'appairage DNS. Chaque domaine doit se terminer par un point (.) (par exemple, corp.internal. ou googleapis.com.).

      Pour en savoir plus sur la configuration du champ domains, consultez Modèles de domaine d'appairage DNS. Pour les déploiements inter-projets tels que le VPC partagé, consultez Exigences concernant les zones DNS et l'appairage inter-projets.

Facultatif : Configurer la configuration de confiance TLS

Si votre destination cible utilise une autorité de certification privée ou un certificat autosigné, vous devez créer une ressource TrustConfig dans Certificate Manager. La ressource TrustConfig définit les ancres de confiance et les certificats qu'Agent Gateway utilise pour valider les connexions TLS.

  1. Préparez vos fichiers de certificat au format PEM :

    • Magasin de confiance : certificats CA racine ou intermédiaires au format PEM. Agent Gateway fait confiance à tout certificat de serveur dont la chaîne de confiance mène à l'un de ces certificats CA. Le magasin de confiance doit contenir au moins un certificat CA racine ou intermédiaire.
    • Certificats sur liste d'autorisation (facultatif) : certificats de serveur au format PEM que vous souhaitez approuver explicitement, par exemple un certificat autosigné.
  2. Exécutez la commande suivante pour créer la ressource TrustConfig. La ressource TrustConfig doit être créée dans le même projet et la même région que l'Agent Gateway et le modèle de connectivité.

    gcloud certificate-manager trust-configs create TRUST_CONFIG_NAME \
        --location=LOCATION \
        --trust-store="trust-anchors=ROOT_CERT_FILE" \
        --allowlisted-certificates=ALLOWLISTED_CERT_FILE
    

    Remplacez les éléments suivants :

    • TRUST_CONFIG_NAME : nom de la ressource TrustConfig.
    • LOCATION : région de la configuration de confiance (par exemple, europe-west1). Elle doit être identique à celle de l'Agent Gateway et du modèle de connectivité.
    • ROOT_CERT_FILE : chemin d'accès à votre certificat CA racine ou intermédiaire encodé au format PEM.
    • ALLOWLISTED_CERT_FILE : (facultatif) chemin d'accès à un certificat encodé au format PEM que vous souhaitez approuver explicitement. Si vous n'utilisez pas de certificats sur liste d'autorisation, omettez cette option.

    Pour en savoir plus sur la gestion des configurations de confiance, consultez Créer et gérer des configurations de confiance.

Déployer l'Agent Gateway

  1. Créez le fichier de configuration du modèle de connectivité :

    Créez un fichier YAML nommé agw-connectivity-template.yaml :

    name: projects/AGENT_GATEWAY_PROJECT_NUMBER/locations/LOCATION/agentConnectivityTemplates/CONNECTIVITY_TEMPLATE_NAME
    accessPath: AGENT_TO_ANYWHERE
    deploymentModel: CENTRALIZED
    egressNetworkConfig:
      networkAttachment: projects/NETWORK_ATTACHMENT_PROJECT_NUMBER/regions/NETWORK_ATTACHMENT_REGION/networkAttachments/NETWORK_ATTACHMENT_NAME
      dnsPeeringConfig:
        domains:
          - DOMAIN_NAME
        targetNetwork: projects/TARGET_VPC_PROJECT_ID/global/networks/TARGET_VPC_NETWORK_NAME
      vpcEgress: VPC_EGRESS_MODE
      tlsConfig:
        trustConfig: projects/AGENT_GATEWAY_PROJECT_NUMBER/locations/LOCATION/trustConfigs/TRUST_CONFIG_NAME
        additionalRoots: ADDITIONAL_ROOTS_OPTION
    

    Remplacez les éléments suivants :

    • AGENT_GATEWAY_PROJECT_NUMBER : numéro du projet Google Cloud dans lequel vous provisionnez Agent Gateway. Pour récupérer votre numéro de projet, exécutez la commande suivante : gcloud projects describe PROJECT_ID --format="value(projectNumber)".

    • LOCATION : région du modèle de connectivité (par exemple, europe-west1).

    • CONNECTIVITY_TEMPLATE_NAME : nom de la ressource de modèle de connectivité.

    • accessPath : chemin d'accès contrôlé pour le modèle de connectivité. Définissez cette option sur AGENT_TO_ANYWHERE (les modèles de connectivité ne sont compatibles qu'avec les passerelles de sortie).

    • deploymentModel : modèle de déploiement de la passerelle. Défini sur CENTRALIZED.

    • networkAttachment : URI de ressource complet du rattachement de réseau Private Service Connect :

      • NETWORK_ATTACHMENT_PROJECT_NUMBER : numéro du projet dans lequel vous avez créé le rattachement de réseau. Ce projet peut être le même que le projet Agent Gateway, ou un projet différent si vous provisionnez Agent Gateway dans un projet de service de VPC partagé et créez le rattachement de réseau dans le projet hôte de VPC partagé.
      • NETWORK_ATTACHMENT_REGION : région qui contient le rattachement de réseau.
      • NETWORK_ATTACHMENT_NAME : nom du rattachement de réseau.
    • DOMAIN_NAME : (facultatif) un ou plusieurs suffixes de domaine pour l'appairage DNS (par exemple, corp.internal., googleapis.com. ou .). Ajoutez un élément de liste sous domains pour chaque suffixe de domaine que vous souhaitez appairer. Chaque valeur doit se terminer par un point (.) et disposer d'une zone gérée Cloud DNS privée correspondante autorisée pour le réseau cible.

      Pour en savoir plus sur la configuration du champ domains, consultez Modèles de domaine d'appairage DNS.

    • targetNetwork : (facultatif) URI de ressource complet du réseau VPC cible pour l'appairage DNS. Le réseau cible est toujours le réseau VPC qui contient le sous-réseau référencé par le rattachement de réseau :

      • TARGET_VPC_PROJECT_ID : ID du projet propriétaire du réseau VPC cible. Si le réseau qui contient le sous-réseau référencé par le rattachement de réseau est un réseau VPC partagé, TARGET_VPC_PROJECT_ID est l'ID du projet hôte du VPC partagé. Spécifiez toujours targetNetwork à l'aide de l'ID du projet plutôt que du numéro du projet.
      • TARGET_VPC_NETWORK_NAME : nom du réseau VPC cible.
    • VPC_EGRESS_MODE : définissez le mode de routage de sortie. Définissez cette valeur sur PRIVATE_RANGES_ONLY ou ALL_TRAFFIC.

    • tlsConfig : (facultatif) configuration TLS pour la validation du certificat de serveur lors de la connexion à des points de terminaison privés via HTTPS :

      • TRUST_CONFIG_NAME : nom de la ressource TrustConfig de Certificate Manager contenant vos certificats CA privés ou vos ancres de confiance.
      • ADDITIONAL_ROOTS_OPTION : indique s'il faut faire confiance aux autorités de certification racines de confiance publique en plus de votre configuration de confiance personnalisée :
      • Définissez cette option sur PUBLICLY_TRUSTED_ROOTS (par défaut) pour approuver à la fois les certificats validés par le paramètre trustConfig et toutes les autorités de certification publiques de confiance. Vous devez définir additionalRoots sur PUBLICLY_TRUSTED_ROOTS si vos agents se connectent également aux APIGoogle Cloud (*.googleapis.com) ou à d'autres points de terminaison HTTPS publics. Sans ce paramètre, Agent Gateway ne fera pas confiance aux certificats signés par Google pour googleapis.com.
      • Définissez ce paramètre sur NO_ADDITIONAL_ROOTS pour ne faire confiance qu'aux certificats validés par le paramètre trustConfig.
  2. Créez le modèle de connectivité :

    Exécutez la commande suivante pour créer le modèle de connectivité :

    gcloud network-services agent-connectivity-templates import CONNECTIVITY_TEMPLATE_NAME \
        --source="agw-connectivity-template.yaml" \
        --location=LOCATION
    

    Remplacez les éléments suivants :

    • CONNECTIVITY_TEMPLATE_NAME : nom de la ressource de modèle de connectivité.
    • LOCATION : emplacement où vous souhaitez créer la ressource de modèle de connectivité. Exemple :europe-west1
  3. Définissez la ressource Agent Gateway :

    Définissez une nouvelle ressource Agent Gateway en mode AGENT_TO_ANYWHERE en créant un fichier de configuration YAML de passerelle (par exemple, my-agent-gateway-vpc-egress.yaml) qui référence le modèle de connectivité :

    name: AGENT_GATEWAY_NAME
    protocols:
      - MCP
    googleManaged:
      governedAccessPath: AGENT_TO_ANYWHERE
    agentConnectivityTemplate: projects/AGENT_GATEWAY_PROJECT_NUMBER/locations/LOCATION/agentConnectivityTemplates/CONNECTIVITY_TEMPLATE_NAME
    registries:
      - AGENT_REGISTRY_PATH
    

    Remplacez les éléments suivants :

    • AGENT_GATEWAY_NAME : nom de la ressource Agent Gateway.

    • AGENT_GATEWAY_PROJECT_NUMBER : numéro du projet Google Cloud dans lequel vous provisionnez l'Agent Gateway et le modèle de connectivité. Pour les déploiements de VPC partagé, ce projet peut être un projet de service ou le projet hôte. Pour récupérer votre numéro de projet, exécutez la commande suivante : gcloud projects describe PROJECT_ID --format="value(projectNumber)".

    • LOCATION : emplacement du modèle de connectivité (par exemple, europe-west1).

    • CONNECTIVITY_TEMPLATE_NAME : nom de la ressource de modèle de connectivité.

      • AGENT_REGISTRY_PATH : chemin d'accès à l'instance Agent Registry régionale dans le même projet et la même région que la passerelle, au format //agentregistry.googleapis.com/projects/PROJECT_ID/locations/LOCATION. Pour obtenir des conseils, consultez Planifier votre déploiement d'Agent Gateway.
  4. Importer et déployer Agent Gateway :

    Exécutez la commande suivante pour créer la ressource Agent Gateway en fonction de la spécification YAML :

    gcloud network-services agent-gateways import AGENT_GATEWAY_NAME \
        --source="my-agent-gateway-vpc-egress.yaml" \
        --location=LOCATION
    

    Remplacez LOCATION par l'emplacement où vous souhaitez créer la ressource Agent Gateway. Exemple : europe-west1.

Considérations sur l'architecture et la mise en réseau

Cette section fournit des conseils d'architecture et des modèles de mise en réseau avancés pour déployer Agent Gateway avec une connectivité VPC.

Mise à jour des paramètres de sortie VPC…

Un modèle de connectivité ne peut pas être modifié sur place lorsqu'il est référencé par un Agent Gateway, et l'Agent Gateway ne récupère pas automatiquement les modifications apportées à un modèle de connectivité associé :

  • Mise à jour de l'appairage DNS, du mode de sortie VPC ou des paramètres TLS (tlsConfig) : dans un modèle de connectivité, le champ tlsConfig.trustConfig est immuable une fois configuré, et les mises à jour sur place de tlsConfig (comme l'ajout ou la modification de additionalRoots) ne sont pas prises en compte par une Agent Gateway associée. Pour mettre à jour la configuration de l'appairage DNS, le mode de sortie VPC ou les paramètres tlsConfig sur une passerelle existante, créez un modèle de connectivité qui utilise le même networkAttachment avec les paramètres mis à jour, puis mettez à jour l'Agent Gateway pour référencer le nouveau modèle (ou dissociez et associez à nouveau le modèle de connectivité).

  • Modifier le rattachement de réseau : le networkAttachment lui-même est immuable une fois configuré sur le modèle de connectivité et sur l'Agent Gateway. Pour passer à un autre rattachement de réseau (ou réseau VPC cible), vous devez créer un modèle de connectivité et une Agent Gateway.

Topologies de déploiement de VPC partagé

Dans une architecture de VPC partagé, vous pouvez provisionner Agent Gateway dans un projet de service ou dans le projet hôte. Lorsque vous provisionnez l'Agent Gateway dans un projet de service, vous pouvez créer le rattachement de réseau dans le projet de service (recommandé) ou dans le projet hôte :

Conformité avec VPC Service Controls

Pour appliquer les périmètres VPC Service Controls aux communications des agents, assurez-vous de respecter les conditions suivantes :

  • Définissez vpcEgress sur ALL_TRAFFIC dans votre modèle de connectivité.

  • Dirigez les requêtes d'API Google vers la plage d'adresses IP restricted.googleapis.com (199.36.153.4/30) ou vers un point de terminaison Private Service Connect interne pour les API Google.

  • Configurez la résolution DNS pour googleapis.com. Créez une zone Cloud DNS privée dans votre réseau VPC en mappant *.googleapis.com sur restricted.googleapis.com, puis incluez googleapis.com. dans le champ domains de votre modèle de connectivité.

    Pour en savoir plus sur la configuration DNS, consultez Configurer le DNS pour googleapis.com dans la documentation sur l'accès privé à Google.

  • Pour les déploiements de VPC partagés, le projet hôte qui possède le sous-réseau du rattachement de réseau et le dnsPeeringConfig.targetNetwork doivent se trouver dans le même périmètre de service que le projet dans lequel vous déployez l'Agent Gateway. Cela s'applique même lorsque vous créez le rattachement de réseau dans le projet de service, car le sous-réseau et le réseau VPC appartiennent toujours au projet hôte. Si vos zones DNS privées sont hébergées dans un projet DNS distinct, incluez également ce projet dans le périmètre.

Modèles de domaine d'appairage DNS

Cette section décrit les modèles de résolution de domaine et les options de configuration du champ domains dans un modèle de connectivité.

Configuration du nom de domaine : configurez le champ domains dans le modèle de connectivité en fonction des considérations suivantes :

  • Domaines internes privés : pour résoudre les services internes privés hébergés sur votre réseau VPC (par exemple, service.corp.internal), spécifiez votre suffixe de domaine interne (tel que corp.internal.). Une zone gérée Cloud DNS privée de correspondance exacte pour ce domaine doit être autorisée pour le réseau VPC cible.

  • DNS split-horizon (domaine public avec adresse IP RFC 1918) : si vous utilisez une zone DNS publique pour héberger des enregistrements pointant vers des adresses IP privées internes (par exemple, mcp.example.com résolvant une adresse RFC 1918 pour les certificats publics Certificate Manager), la passerelle résout automatiquement ces enregistrements à l'aide d'un DNS récursif public, sans nécessiter d'appairage DNS.

  • Google Cloud API avec VPC Service Controls : lorsque ALL_TRAFFIC est configuré pour appliquer VPC Service Controls, les requêtes d'API Google doivent être résolues dans la plage d'adresses IP restricted.googleapis.com (199.36.153.4/30) ou dans des points de terminaison PSC internes. Créez une zone Cloud DNS privée dans votre réseau VPC en mappant *.googleapis.com sur restricted.googleapis.com, puis incluez googleapis.com. dans le champ domains de votre modèle de connectivité.

  • Modèles de résolution multidomaine : si votre déploiement nécessite la résolution de plusieurs suffixes de domaine privé, choisissez l'un des modèles suivants :

    • Appairer plusieurs domaines individuels : spécifiez une liste de suffixes de domaine dans le champ domains de dnsPeeringConfig (par exemple, corp.internal., prod.internal. et googleapis.com.). Chaque domaine de la liste doit se terminer par un point (.) et disposer d'une zone gérée Cloud DNS privée correspondante autorisée pour le réseau VPC cible.
    • Suffixe parent consolidé (recommandé) : consolidez les services internes sous un suffixe de domaine parent partagé (tel que *.internal. ou *.corp.internal.) et incluez ce domaine parent dans la liste domains.
    • Appairage racine catch-all avec une zone de transfert privée : incluez "." dans le champ domains du modèle de connectivité, puis configurez une zone de transfert privée Cloud DNS pour le domaine racine (.) dans votre réseau VPC pointant vers un résolveur récursif en amont (tel que 8.8.8.8 ou un résolveur d'entreprise interne). Les zones privées plus spécifiques de votre VPC sont d'abord mises en correspondance par correspondance de suffixe la plus longue, tandis que les requêtes publiques sans correspondance sont résolues via le redirecteur en amont.

Exigences concernant les zones DNS et l'appairage multiprojets

Le paramètre dnsPeeringConfig du modèle de connectivité n'est pas compatible avec l'appairage Cloud DNS interprojets direct. Lorsque vous importez le modèle de connectivité, la validation échoue si le sous-réseau référencé par networkAttachment appartient à un réseau VPC différent de targetNetwork, ou si vous utilisez une liaison de zone DNS inter-projets à partir d'un service ou d'un projet externe.

La zone gérée du domaine doit être créée dans le projet hôte propriétaire de targetNetwork. La zone gérée peut être l'un des types de zones suivants :

  • Zone privée de référence
  • Zone de transfert
  • Zone d'appairage Cloud DNS : doit être associée au réseau VPC du projet hôte et cibler un réseau VPC de destination. Le VPC de destination doit résoudre la requête directement à l'aide d'une zone privée faisant autorité. Le transfert de la requête vers une autre zone d'appairage DNS (chaînage) n'est pas accepté et entraîne une erreur NXDOMAIN.

Effectuer le scaling des projets de service Agent Runtime avec un groupe Google

Si vous connectez plusieurs projets de service Agent Runtime à un projet hôte Agent Gateway et que vous accordez un accès interprojets à chaque agent de service individuellement, vous devez mettre à jour la stratégie IAM du projet hôte chaque fois que vous ajoutez un projet. Dans les déploiements à grande échelle, vous pouvez également atteindre les limites des stratégies IAM lorsque vous ajoutez des liaisons de rôles.

Pour éviter de mettre à jour la stratégie IAM du projet hôte pour chaque nouveau projet de service, vous pouvez gérer l'accès via un seul groupe de sécurité Google :

  1. Créer un groupe de sécurité : créez un groupe de sécurité dans la console d'administration Google ou en exécutant la commande gcloud identity groups create.

  2. Accordez au groupe l'accès au projet hôte Agent Gateway : associez le groupe au rôle Lecteur de services réseau (roles/networkservices.viewer) sur AGENT_GATEWAY_PROJECT_ID :

    gcloud projects add-iam-policy-binding AGENT_GATEWAY_PROJECT_ID \
        --member="group:GROUP_EMAIL" \
        --role="roles/networkservices.viewer"
    

    Remplacez les éléments suivants :

    • AGENT_GATEWAY_PROJECT_ID : ID du projet hôte Agent Gateway.
    • GROUP_EMAIL : adresse e-mail de votre groupe de sécurité (par exemple, agw-cross-project-runtime@example.com).
  3. Ajoutez l'agent de service Agent Runtime de chaque projet de service au groupe : Pour chaque projet de service Agent Runtime, ajoutez son agent de service au groupe de sécurité en exécutant la commande gcloud identity groups memberships add comme suit :

    gcloud identity groups memberships add \
        --group-email="GROUP_EMAIL" \
        --member-email="service-AGENT_RUNTIME_PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com"
    

    Remplacez AGENT_RUNTIME_PROJECT_NUMBER par le numéro du projet de service Agent Runtime.

Étapes suivantes

Guide

Découvrez comment acheminer le trafic Agent Runtime via Agent Gateway pour une connectivité sécurisée et régie.

Atelier de programmation

Découvrez comment gouverner les charges de travail agentiques avec Agent Gateway sur Gemini Enterprise Agent Platform.

Atelier de programmation

Découvrez la gouvernance de sortie d'Agent Gateway pour les agents IA accédant à des destinations dans un réseau VPC.

Guide

Découvrez comment déléguer l'autorisation pour Agent Gateway à IAP, Model Armor ou à votre propre service d'autorisation personnalisé.

Guide

Découvrez comment afficher, mettre à jour, dissocier et supprimer des ressources Agent Gateway.

Guide

Découvrez comment surveiller Agent Gateway.

Guide

Découvrez comment acheminer le trafic Gemini Enterprise via Agent Gateway.