Domaine personnalisé Agentspace

À propos de cet atelier de programmation
schedule45 minutes
subjectDernière mise à jour : 27 mai 2025
account_circleRédigé par Deepak Michael, Lorin Price, Zach Seils

Ce document fournit une architecture de référence pour configurer un domaine personnalisé afin d'accéder à AgentSpace. Au lieu de l'URL gérée par Google attribuée lors de la création de l'application Agentspace, les utilisateurs peuvent utiliser un domaine personnalisé. Cet atelier de programmation montre comment accéder aux applications Agenda et Drive d'Agentspace à l'aide du domaine nip.io. nip.io est un service Open Source sans frais qui fournit un DNS générique pour n'importe quelle adresse IP. En substance, il vous permet de créer un nom d'hôte qui se résout en une adresse IP spécifique sans avoir à configurer votre propre serveur DNS ni à modifier votre fichier /etc/hosts.

Il est recommandé d'utiliser votre propre domaine, mais à des fins de démonstration, nip.io est utilisé dans le tutoriel.

Dans le scénario de déploiement illustré ci-dessous (figure 1), AgentSpace a publié un datastore contenant une application Agenda accessible via une URL publique gérée par Google.

Figure 1

27591afa06891dcb.png

La croissance continue du datastore et des applications ultérieures entraîne une gestion plus poussée des URL publiques gérées par Google, comme illustré dans le scénario de déploiement ci-dessous (figure 2), ce qui se traduit par un mappage individuel des applications et des URL Agentspace.

Figure 2.

7e31bfae7ac56b22.png

Un domaine personnalisé permet de mapper différentes applications AgentSpace à un seul domaine client spécifié par l'utilisateur. Cette fonctionnalité permet d'associer un chemin d'URL spécifique à chaque application Agentspace, ce qui offre une plus grande flexibilité, comme illustré dans le scénario de déploiement ci-dessous (figure 3). Par exemple, un domaine géré par le client agentspace.cosmopup.com est segmenté en règles de chemin d'accès, chacune mappée à une application Agentspace spécifique, par exemple:

  • agentspace.cosmopup.com/drive-app qui correspond à l'application Agentspace pour Workspace Drive
  • agentspace.cosmopup.com/calendar-app qui correspond à l'application Agentspace pour Agenda Workspace

Les règles d'hôte et de chemin de l'équilibreur de charge d'application externe,configurées via le mappage d'URL, contrôlent la logique qui met en correspondance le domaine personnalisé avec l'URL gérée par Google. Il effectue la fonction suivante à l'aide de l'exemple agentspace.cosmopup.com/drive-app.

  • Le chemin d'hôte de domaine personnalisé agentspace.cosmopup.com/drive-app est reçu par l'équilibreur de charge
  • Le mappage d'URL est configuré pour la mise en correspondance avancée des règles d'hôte et de chemin d'accès
  • Hôtes agentspace.cosmopup.com est éligible à la mise en correspondance et à la réécriture de chemin d'accès
  • Le chemin d'accès de l'hôte du domaine personnalisé agentspace.cosmopup.com/drive-app est soumis à UrlRewrite
  • PathPrefixRewrite correspond au chemin d'Agentspace: /us/home/cid/5970a1b4-080a-4b44-8acd-fa89460cf0cd.
  • hostRewrite est l'hôte Agentspace: vertexaisearch.cloud.google.com
  • L'opération de réécriture est effectuée avant l'acheminement vers le service backend
  • Le service de backend achemine le trafic vers l'application Drive en fonction de l'URL Agentspace.

Figure 3

f8d84ec5fef9af5a.png

Points abordés

  • Créer un équilibreur de charge d'application externe global
  • Créer une réécriture de service backend à l'aide d'un domaine personnalisé et d'une opération de réécriture dans une application Agentspace
  • Intégrer nip.io et Cloud DNS pour créer un domaine personnalisé
  • Valider l'accès à un domaine personnalisé Agentspace

Prérequis

  • Projet Google Cloud avec autorisations de propriétaire
  • URL de l'application Agentspace existante
  • Domaine personnalisé géré par l'utilisateur (facultatif)
  • Certificats : autosignés ou gérés par Google

2. Ce que vous allez faire

Vous allez configurer un équilibreur de charge d'application externe global avec des fonctionnalités avancées de gestion du trafic pour activer la mise en correspondance du chemin de domaine personnalisé pour les applications Agentspace à l'aide de la réécriture d'hôte et de chemin d'accès. Une fois le déploiement effectué, vous devrez effectuer les actions suivantes pour valider l'accès à l'application Agentspace:

  • Pour accéder à votre application Agentspace, ouvrez un navigateur Web et accédez à votre domaine personnalisé et au chemin d'accès spécifié.

c62938d91e00ffa7.png

3. Configuration réseau requise

Vous trouverez ci-dessous le détail des exigences réseau:

Composants

Description

VPC (agentspace-vpc)

VPC en mode personnalisé

NEG Internet

Ressource utilisée pour définir un backend externe pour l'équilibreur de charge configuré en tant que nom de domaine complet (FQDN) désignant le FQDN géré par Google de l'Agentspace (vertexaisearch.cloud.google.com). Le nom de domaine complet Internet effectue une recherche DNS dans le VPC pour la résolution.

Service de backend

Un service de backend sert de pont entre votre équilibreur de charge et vos ressources de backend. Dans l'atelier, le service de backend est associé au NEG Internet.

Certificats

Pour configurer des certificats pour un équilibreur de charge d'application dans Google Cloud, vous devez utiliser le service Gestionnaire de certificats et des certificats SSL gérés par Google ou autogérés.

Cloud DNS

La zone publique Cloud DNS permet de résoudre l'adresse IP externe de l'équilibreur de charge d'application externe en nip.io (agentspace.externalip.nip.io). Vous pouvez également utiliser votre domaine personnalisé et un enregistrement A composé de l'adresse IP de l'équilibreur de charge.

4. Topologie de l'atelier de programmation

c62938d91e00ffa7.png

f712980116d973a3.png

5. Préparation

Configuration de l'environnement au rythme de chacun

  1. Connectez-vous à la console Google Cloud, puis créez un projet ou réutilisez un projet existant. Si vous n'avez pas encore de compte Gmail ou Google Workspace, vous devez en créer un.

fbef9caa1602edd0.png

a99b7ace416376c4.png

5e3ff691252acf41.png

  • Le nom du projet est le nom à afficher pour les participants au projet. Il s'agit d'une chaîne de caractères non utilisée par les API Google. Vous pourrez toujours le modifier.
  • L'ID du projet est unique parmi tous les projets Google Cloud et non modifiable une fois défini. La console Cloud génère automatiquement une chaîne unique (en général, vous n'y accordez d'importance particulière). Dans la plupart des ateliers de programmation, vous devrez indiquer l'ID de votre projet (généralement identifié par PROJECT_ID). Si l'ID généré ne vous convient pas, vous pouvez en générer un autre de manière aléatoire. Vous pouvez également en spécifier un et voir s'il est disponible. Après cette étape, l'ID n'est plus modifiable et restera donc le même pour toute la durée du projet.
  • Pour information, il existe une troisième valeur (le numéro de projet) que certaines API utilisent. Pour en savoir plus sur ces trois valeurs, consultez la documentation.
  1. Vous devez ensuite activer la facturation dans la console Cloud pour utiliser les ressources/API Cloud. L'exécution de cet atelier de programmation est très peu coûteuse, voire sans frais. Pour désactiver les ressources et éviter ainsi que des frais ne vous soient facturés après ce tutoriel, vous pouvez supprimer le projet ou les ressources que vous avez créées. Les nouveaux utilisateurs de Google Cloud peuvent participer au programme d'essai sans frais pour bénéficier d'un crédit de 300 $.

Démarrer Cloud Shell

Bien que Google Cloud puisse être utilisé à distance depuis votre ordinateur portable, nous allons nous servir de Google Cloud Shell pour cet atelier de programmation, un environnement de ligne de commande exécuté dans le cloud.

Dans la console Google Cloud, cliquez sur l'icône Cloud Shell dans la barre d'outils supérieure :

55efc1aaa7a4d3ad.png

Le provisionnement et la connexion à l'environnement prennent quelques instants seulement. Une fois l'opération terminée, le résultat devrait ressembler à ceci :

7ffe5cbb04455448.png

Cette machine virtuelle contient tous les outils de développement nécessaires. Elle comprend un répertoire d'accueil persistant de 5 Go et s'exécute sur Google Cloud, ce qui améliore nettement les performances du réseau et l'authentification. Vous pouvez effectuer toutes les tâches de cet atelier de programmation dans un navigateur. Vous n'avez rien à installer.

6. Avant de commencer

Activer les API

Dans Cloud Shell, assurez-vous que l'ID de votre projet est configuré:

gcloud config list project
gcloud config set project [YOUR-PROJECT-ID]
project=[YOUR-PROJECT-ID]
region=[YOUR-REGION]
echo $project
echo $region

Activez tous les services nécessaires :

gcloud services enable compute.googleapis.com
gcloud services enable dns.googleapis.com

7. Créer un réseau VPC

Réseau VPC

Dans Cloud Shell, procédez comme suit:

gcloud compute networks create agentspace-vpc --subnet-mode custom

8. Configurer les composants de l'équilibreur de charge

Réserver l'adresse IP externe de l'équilibreur de charge

Dans Cloud Shell, réservez une adresse IP externe pour l'équilibreur de charge:

gcloud compute addresses create external-ip \
    --network-tier=PREMIUM \
    --ip-version=IPV4 \
    --global

Dans Cloud Shell, affichez l'adresse IP réservée:

gcloud compute addresses describe external-ip \
  --global | grep -i address:

Exemple de résultat :

user@cloudshell$ gcloud compute addresses describe external-ip \
  --global | grep -i address:
address: 34.54.158.206

Configurer le NEG Internet

Créez un NEG Internet et définissez –network-endpoint-type sur internet-fqdn-port (nom d'hôte et port où votre backend externe peut être atteint). Pour résoudre Agentspace, le nom de domaine complet vertexaisearch.cloud.google.com et le port 443 sont utilisés.

gcloud compute network-endpoint-groups create agentspace-ineg \
    --network-endpoint-type="internet-fqdn-port" \
    --global
gcloud compute network-endpoint-groups update agentspace-ineg \
    --add-endpoint="fqdn=vertexaisearch.cloud.google.com,port=443" \
    --global

Créer l'équilibreur de charge

Dans Cloud Shell, procédez comme suit:

gcloud compute backend-services create agentspace-ineg-bes \
      --load-balancing-scheme=EXTERNAL_MANAGED \
      --protocol=HTTPS \
      --global
gcloud compute backend-services add-backend agentspace-ineg-bes \
      --network-endpoint-group=agentspace-ineg \
      --global-network-endpoint-group \
      --global  

Créer le certificat

À ce stade, vous avez créé le NEG Internet et le service de backend. Dans la section suivante, vous devrez créer une ressource de certificat à utiliser dans le proxy cible HTTPs. Vous pouvez créer une ressource de certificat SSL à l'aide d'un certificat SSL géré par Google ou d'un certificat SSL autogéré. Nous vous recommandons d'utiliser des certificats gérés par Google, car Google Cloud obtient, gère et renouvelle automatiquement ces certificats.

Pour en savoir plus sur les certificats compatibles avec l'équilibreur de charge d'application externe global utilisé dans ce tutoriel, consultez les ressources suivantes:

Présentation des certificats SSL | Load Balancing | Google Cloud

Dans la section suivante, vous allez créer un certificat autosigné (bien qu'un certificat géré par Google puisse être utilisé à la place) qui nécessite de mapper le nom commun au nom de domaine complet (agentspace.VOTRE-ADRESSE-IP-EXTERNE.nip.io) correspondant à l'adresse IP externe de l'équilibreur de charge générée précédemment. Exemple ci-dessous:

Nom commun: agentspace.34.54.158.206.nip.io

Dans Cloud Shell, créez la clé privée

openssl genrsa -out private-key-file.pem 2048

Dans Cloud Shell, créez un fichier config.txt qui servira à générer le fichier PEM. Spécifiez le nom de domaine complet dans l'entrée DNS 1 agentspace.VOTRE-ADRESSE-IP-EXTÉRIEUR.nip.io (par exemple, agentspace.34.54.158.206.nip.io) dans la configuration ci-dessous.

cat <<'EOF' >config.txt
[req]
default_bits              = 2048
req_extensions            = extension_requirements
distinguished_name        = dn_requirements

[extension_requirements]
basicConstraints          = CA:FALSE
keyUsage                  = nonRepudiation, digitalSignature, keyEncipherment
subjectAltName            = @sans_list

[dn_requirements]
countryName               = Country Name (2 letter code)
stateOrProvinceName       = State or Province Name (full name)
localityName              = Locality Name (eg, city)
organizationName          = Organization Name (eg, company)
organizationalUnitName    = Organizational Unit Name (eg, section)
commonName                = Common Name (e.g. server FQDN or YOUR name)
emailAddress              = Email Address

[sans_list]
DNS.1                     = agentspace.YOUR-EXTERNAL-IP.nip.io

EOF

Dans Cloud Shell, vérifiez que les fichiers config.txt et private-key-file.pem sont générés.

user@cloudshell:$ ls
config.txt  private-key-file.pem

Dans Cloud Shell, procédez comme suit :

sudo openssl req -new -key private-key-file.pem \
    -out csr.pem \
    -config config.txt

Exemple :

user@cloudshell:$ sudo openssl req -new -key private-key-file.pem \
    -out csr.pem \
    -config config.txt
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) []:
State or Province Name (full name) []:
Locality Name (eg, city) []:
Organization Name (eg, company) []:
Organizational Unit Name (eg, section) []:
Common Name (e.g. server FQDN or YOUR name)[]:agentspace.34.54.158.206.nip.io
Email Address []:

Dans Cloud Shell, validez la création du fichier PEM requis pour la signature du certificat.

user@cloudshell:$ ls
config.txt  csr.pem  private-key-file.pem

Dans Cloud Shell, générez le certificat.

sudo openssl x509 -req \
    -signkey private-key-file.pem \
    -in csr.pem \
    -out cert.cert \
    -extfile config.txt \
    -extensions extension_requirements \
    -days 365

Exemple de résultat :

user@cloudshell:$ sudo openssl x509 -req \
    -signkey private-key-file.pem \
    -in csr.pem \
    -out cert.cert \
    -extfile config.txt \
    -extensions extension_requirements \
    -days 365
Certificate request self-signature ok
subject=CN = agentspace.34.54.158.206.nip.io

Dans Cloud Shell, vérifiez la création du fichier cert.cert.

user@cloudshell:$ ls
cert.cert  config.txt  csr.pem  private-key-file.pem

Créez une ressource de certificat à associer à votre équilibreur de charge externe. Remplacez les paramètres de certificat et de clé privée par vos noms de fichiers spécifiques.

Dans Cloud Shell, procédez comme suit:

gcloud compute ssl-certificates create agentspace-self-signed-cert \
    --certificate=cert.cert \
    --private-key=private-key-file.pem \
    --global

Dans Cloud Shell, procédez comme suit:

gcloud compute url-maps create agentspace-lb \
      --default-service=agentspace-ineg-bes \
      --global  

Dans Cloud Shell, procédez comme suit:

gcloud compute target-https-proxies create https-proxy \
      --ssl-certificates=agentspace-self-signed-cert \
      --url-map=agentspace-lb \
      --global 

Dans Cloud Shell, procédez comme suit:

gcloud compute forwarding-rules create agentspace-fr \
      --load-balancing-scheme=EXTERNAL_MANAGED \
      --network-tier=PREMIUM \
      --address=external-ip \
      --target-https-proxy=https-proxy \
      --global \
      --ports=443

9. Créer une zone DNS publique

Dans la section suivante, vous allez créer une zone DNS publique utilisée par nip.io pour résoudre l'adresse IP externe de l'équilibreur de charge.

Dans Cloud Shell, procédez comme suit pour créer une variable pour l'adresse IP externe de votre équilibreur de charge:

externalip=<YOUR-EXTERNAL-IP>
echo $externalip

Dans Cloud Shell, procédez comme suit:

gcloud dns --project=$project managed-zones create agentspace-dns --description="Agentspace public dns" --dns-name="$externalip.nip.io." --visibility="public"

Dans Cloud Shell, procédez comme suit:

gcloud dns --project=$project record-sets create agentspace.$externalip.nip.io. --zone="agentspace-dns" --type="A" --ttl="300" --rrdatas="$externalip"

10. Identifiants OAuth

Dans la section suivante, vous allez créer des identifiants OAuth pour les applications Web qui redirigeront l'URL gérée par Google vers oauth-redirect pour l'authentification. Les identifiants générés ne sont pas nécessaires pour le tutoriel.

Pour en savoir plus sur OAuth, consultez les ressources suivantes:

Ajouter des actions Google Agenda et Gmail | Google Agentspace

Créer une application OAuth et ajouter des habilitations

  1. Accédez à API et services > Écran de consentement OAuth: Accéder à l'écran de consentement OAuth
  2. Sélectionnez "Interne", puis cliquez sur "Créer".
  3. Attribuez un nom à votre application OAuth.
  4. Saisissez l'adresse e-mail d'assistance de l'utilisateur.
  5. Saisissez les coordonnées du développeur.
  6. Cliquez sur Enregistrer et continuer .

Créer un ID client OAuth

Cette procédure explique comment créer un ID client OAuth pour les actions Google Cloud. Cet ID client et ce secret OAuth peuvent également être utilisés pour d'autres actions Google Cloud. Si vous disposez déjà d'un ID client OAuth Google Cloud pour les actions Google Cloud, vous pouvez utiliser cet ID client et ce code secret pour les actions Google Agenda au lieu de créer un ID client.

  1. Accédez à la page "Identifiants", puis cliquez sur "Créer des identifiants" > "ID client OAuth".
  2. Sélectionnez "Application Web".
  3. Saisissez un nom pour votre ID client.
  4. Cliquez sur "Ajouter un URI", puis saisissez l'URI suivant: https://vertexaisearch.cloud.google.com/oauth-redirect.
  5. Cliquez sur "Créer", puis copiez les informations suivantes:
  • ID client
  • Code secret du client

11. Identifier les URL des applications Agentspace

La procédure suivante identifie les URL publiques Agentspace gérées par Google générées par Google et mappées sur Agentspace pour chaque application. Les URL générées sont des exemples basés sur l'architecture de référence. Vous devez donc vous assurer qu'elles sont exactes.

Veillez à stocker le lien vers votre application Web, par application.

Application Agenda

URL Web d'Agentspace: https://vertexaisearch.cloud.google.com/us/home/cid/bb6b8b27-939b-494d-9227-45903bb8afcf

b90c67aafd825ccd.png

Application Drive

URL Web Agentspace:

https://vertexaisearch.cloud.google.com/us/home/cid/5970a1b4-080a-4b44-8acd-fa89460cf0cd

f8f850425fd11190.png

12. Créer une règle d'hôte et de chemin d'accès avancée

Dans la section suivante, vous allez mettre à jour les règles de routage des équilibreurs de charge pour activer l'option permettant de définir des règles d'hôte et de chemin d'accès à l'aide de la console Cloud. Le tableau ci-dessous présente les valeurs personnalisées (dans l'ordre de haut en bas), mises à jour en fonction de votre environnement:

Valeur personnalisée

Exemple basé sur le tutoriel

Hôtes

agentspace.YOUR-EXTERNAL-IP.nip.io

agentspace.34.54.158.206.nip.io

defaultService

projects/<projectid>/global/backendServices/agentspace-ineg-bes

Voir la capture d'écran

prefixMatch

/<nom de l'application Agentspace 1>

/drive-app

backendService

projects/<projectid>/global/backendServices/agentspace-ineg-bes

Voir la capture d'écran

pathPrefixRewrite

/<Chemin d'URL Agentspace de l'appli 1>

/us/home/cid/5970a1b4-080a-4b44-8acd-fa89460cf0cd

hostRewrite

vertexaisearch.cloud.google.com

vertexaisearch.cloud.google.com

prefixMatch

/<nom de l'application Agentspace 2>

/calendar-app

backendService

projects/<projectid>/global/backendServices/agentspace-ineg-bes

Voir la capture d'écran

pathPrefixRewrite

/<Agentspace URL path of app#2>

/us/home/cid/bb6b8b27-939b-494d-9227-45903bb8afcf

hostRewrite

vertexaisearch.cloud.google.com

vertexaisearch.cloud.google.com

Accédez à la page suivante pour accéder aux règles d'hôte et de chemin d'accès :

Équilibrage de charge → agentspace-lb → sélectionner "Modifier"

Sélectionnez "Règles de routage" → "Règles d'hôte et de chemin d'accès avancées".

Sélectionnez "Ajouter une règle d'hôte et de chemin d'accès".

4bc965db43aed21b.png

Vous pouvez maintenant créer une règle d'hôte et de chemin d'accès. Dans la section "Hosts" (Hôtes), saisissez agentspace.VOTRE-ADRESSE-IP-EXTERNE.nip.io ou un domaine personnalisé.

f36e4fa11c950d8d.png

Dans le champ "Outil de mise en correspondance des chemins d'accès" (correspondances, actions et services), remplacez le contenu ci-dessous par votre configuration d'environnement, puis sélectionnez "Mettre à jour".

defaultService: projects/<projectid>/global/backendServices/agentspace-ineg-bes
name: matcher1
routeRules:
- matchRules:
 - prefixMatch: /<name of Agentspace app#1>
 priority: 1
 routeAction:
   weightedBackendServices:
   - backendService: projects/<projectid>/global/backendServices/agentspace-ineg-bes
     weight: 100
   urlRewrite:
     pathPrefixRewrite: /<Agentspace URL path of app#1>
     hostRewrite: vertexaisearch.cloud.google.com
- matchRules:
 - prefixMatch: /<name of Agentspace app#2>
 priority: 2
 routeAction:
   weightedBackendServices:
   - backendService: projects/<projectid>/global/backendServices/agentspace-ineg-bes
     weight: 101
   urlRewrite:
     pathPrefixRewrite: /<Agentspace URL path of app#2>
     hostRewrite: vertexaisearch.cloud.google.com

Exemple de capture d'écran:

22788283124c59ec.png

cef8f571ca17bf42.png

13. Validation

Le déploiement est terminé. Vous pouvez accéder à l'application Agentspace à l'aide du domaine personnalisé via un navigateur Web ou un terminal en spécifiant agentspace.VOTRE-ADRESSE-IP-EXTERNE.nip.io/chemin d'accès(par exemple, agentspace.34.54.158.206.nip.io). Exemples ci-dessous:

Application Agentspace: drive-app

Chemin d'accès: agentspace.34.54.158.206.nip.io/drive-app

Application Agentspace: drive-app

Chemin d'accès: agentspace.34.54.158.206.nip.io/calendar-app

14. Effectuer un nettoyage

Pour supprimer des identifiants OAuth, procédez comme suit:

Accédez à API et services → Identifiants.

Sous "ID client OAuth 2.0", sélectionnez vos identifiants, puis supprimez-les.

À partir d'un seul terminal Cloud Shell, supprimez les composants de l'atelier:

gcloud compute forwarding-rules delete agentspace-fr --global -q

gcloud compute target-https-proxies delete https-proxy --global -q

gcloud compute url-maps delete agentspace-lb --global -q

cloud compute ssl-certificates delete agentspace-self-signed-cert --global -q

gcloud compute backend-services delete agentspace-ineg-bes --global -q

gcloud compute network-endpoint-groups delete agentspace-ineg --global -q

gcloud dns --project=$projectid record-sets delete agentspace.$externalip.nip.io --zone="agentspace-dns" --type="A"

gcloud dns --project=$projectid managed-zones delete agentspace-dns

gcloud compute addresses delete external-ip --global -q

gcloud compute networks delete agentspace-vpc -q

15. Félicitations

Félicitations, vous avez réussi à configurer et à valider la connectivité à un Agentspace à l'aide d'un domaine personnalisé avec un équilibreur de charge d'application externe avec gestion avancée du trafic.

Vous avez créé l'infrastructure de l'équilibreur de charge, appris à créer un NEG Internet, Cloud DNS et une gestion avancée du trafic qui a permis de réécrire l'hôte et le chemin d'accès, ce qui a permis de se connecter à Agentspace à l'aide d'un domaine personnalisé.

Cosmopup pense que les ateliers de programmation sont géniaux !

c911c127bffdee57.jpeg

Documents de référence