1. Introduction
Ce document fournit une architecture de référence pour configurer un domaine personnalisé afin d'accéder à AgentSpace à l'aide de WIF. Au lieu d'utiliser l'URL gérée par Google qui est 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 d'autres termes, 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. Toutefois, à 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 d'agenda accessible via une URL publique gérée par Google.
Figure 1
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 un-à-un des applications Agentspace et de l'URL.
Figure 2.
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 étant mappée à une application Agentspace spécifique. Voici quelques exemples :
- agentspace.cosmopup.com/drive-app qui correspond à l'application Agentspace pour Workspace Drive
- agentspace.cosmopup.com/sharepoint-app qui correspond à l'application Agentspace pour SharePoint
Les règles d'hôte et de chemin d'accès de l'équilibreur de charge d'application externe,configurées via le mappage d'URL, contrôlent la logique qui mappe le domaine personnalisé à l'URL gérée par Google. Elle effectue la fonction suivante à l'aide de l'espace agent exemple agentspace.cosmopup.com/drive-app
- L'équilibreur de charge reçoit le chemin d'hôte du domaine personnalisé agentspace.cosmopup.com/drive-app.
- 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.
- L'hôte agentspace.cosmopup.com est éligible à la mise en correspondance des chemins d'accès et à la redirection.
- Le chemin d'hôte de domaine personnalisé agentspace.cosmopup.com/drive-app est soumis à UrlRedirect
- pathRedirect est le chemin d'accès à Agentspace : /us/home/cid/5970a1b4-080a-4b44-8acd-fa89460cf0cd
- hostRedirect est l'hôte Agentspace : vertexaisearch.cloud.google.com
- Le chemin d'hôte du domaine personnalisé agentspace.cosmopup.com/sharepoint-app est soumis à UrlRedirect.
- pathRedirect est le chemin d'accès à Agentspace : /signin/locations/global/workforcePools/your-pool-name/providers/your-provider-name?continueUrl=https://vertexaisearch.cloud.google/home/cid/f190000-0000-4d0a-0000-d08df6e3bef6
- hostRedirect est l'hôte Agentspace : auth.cloud.google
- L'opération de redirection est effectuée avant le routage vers le service de backend.
Figure 3
Points abordés
- Créer un équilibreur de charge d'application externe global
- Créer un routage pour rediriger un domaine personnalisé vers 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 des autorisations de propriétaire
- URL des applications Agentspace existantes
- Domaine personnalisé appartenant à l'utilisateur (facultatif)
- Certificats autosignés ou gérés par Google
2. Ce que vous allez faire
Vous allez établir un équilibreur de charge d'application externe global avec des fonctionnalités avancées de gestion du trafic pour activer la correspondance du chemin d'accès au domaine personnalisé pour les applications Agentspace à l'aide de la redirection d'hôte et de chemin d'accès. Une fois déployé, vous effectuerez les actions suivantes pour valider l'accès à l'application Agentspace :
- Accédez à votre application Agentspace en ouvrant un navigateur Web et en accédant à votre domaine personnalisé et au chemin spécifié.
3. Configuration réseau requise
Voici la répartition 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 désignant le nom de domaine complet géré par Google pour 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 le tutoriel, 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 Certificate Manager et des certificats SSL gérés par Google ou des certificats SSL autogérés. |
Cloud DNS | La zone publique Cloud DNS est utilisée pour 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
5. Préparation
Configuration de l'environnement au rythme de chacun
- 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.
- 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.
- 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 :
Le provisionnement et la connexion à l'environnement prennent quelques instants seulement. Une fois l'opération terminée, le résultat devrait ressembler à ceci :
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. 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" (le nom d'hôte et le 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 mondial utilisé dans ce tutoriel, consultez les ressources suivantes :
Présentation des certificats SSL | Équilibrage de charge | 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 le mappage du nom commun au nom de domaine complet (agentspace.YOUR-EXTERNAL-IP.nip.io) correspondant à l'adresse IP externe de l'équilibreur de charge générée précédemment. Voici un exemple :
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.YOUR-EXTERNAL-IP.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 ont été 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, validez 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
8. Créer une zone DNS publique
Dans la section suivante, vous allez créer une zone DNS publique utilisée par nip.io pour la résolution par rapport à l'adresse IP de l'équilibreur de charge externe.
Dans Cloud Shell, procédez comme suit pour créer une variable pour l'adresse IP de votre équilibreur de charge externe :
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"
9. Identifier les URL des applications Agentspace
La procédure suivante identifie les URL publiques Agentspace gérées par Google et générées par Google qui sont mappées à Agentspace pour chaque application. Les URL de sortie sont des exemples basés sur l'architecture de référence. Vous devez donc vous assurer que vos URL sont exactes.
Veillez à stocker le lien vers votre application Web pour chaque application.
Application Drive
URL Web Agentspace :
https://vertexaisearch.cloud.google.com/us/home/cid/5970a1b4-080a-4b44-8acd-fa89460cf0cd
Application SharePoint
URL Web Agentspace : https://auth.cloud.google/signin/locations/global/workforcePools/your-pool-name/providers/your-provider-name?continueUrl=https://vertexaisearch.cloud.google/home/cid/f190000-0000-4d0a-0000-d08df6e3bef6
10. 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 pouvoir 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 (de haut en bas). Mettez-les à 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 | projects/your-project-id/global/backendServices/agentspace-ineg-bes |
prefixMatch | /<name of Agentspace app#1> | /drive-app |
pathRedirect | /<chemin d'URL de l'espace agent de l'application 1> | /us/home/cid/5970a1b4-080a-4b44-8acd-fa89460cf0cd |
hostRedirect | vertexaisearch.cloud.google.com | vertexaisearch.cloud.google.com |
prefixMatch | /<name of Agentspace app#2> | /sharepoint-app |
pathRedirect | /<chemin d'URL de l'espace agent de l'application n°2> | //signin/locations/global/workforcePools/your-pool-name/providers/your-provider-name?continueUrl=https://vertexaisearch.cloud.google/home/cid/f190000-0000-4d0a-0000-d08df6e3bef6 |
hostRedirect | auth.cloud.google | vertexaisearch.cloud.google.com |
Pour accéder aux règles d'hôte et de chemin d'accès, accédez à :
É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".
Vous êtes maintenant invité à créer une règle d'hôte et de chemin d'accès. Dans la section des hôtes, insérez agentspace.YOUR-EXTERNAL-IP.nip.io ou un domaine personnalisé.
Dans le champ "Outil de mise en correspondance des chemins d'accès" (correspondances, actions et services), mettez à jour le contenu ci-dessous avec la configuration de votre 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
urlRedirect:
pathRedirect: /<Agentspace URL path of app#1>
hostRedirect: vertexaisearch.cloud.google.com
redirectResponseCode: FOUND
- matchRules:
- prefixMatch: /<name of Agentspace app#2>
priority: 2
urlRedirect:
pathRedirect: /<Agentspace URL path of app#2>
hostRedirect: auth.cloud.google
redirectResponseCode: FOUND
Exemple de capture d'écran :
11. 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.YOUR-EXTERNAL-IP.nip.io/path, par exemple agentspace.34.54.158.206.nip.io.Vous trouverez des exemples ci-dessous :
Application Agentspace : drive-app
Chemin d'accès : agentspace.34.54.158.206.nip.io/drive-app
Application Agentspace : sharepoint-app
Chemin d'accès : agentspace.34.54.158.206.nip.io/sharepoint-app
12. Effectuer un nettoyage
Pour supprimer des identifiants OAuth, procédez comme suit :
Accédez à API et services → Identifiants.
Sous "ID clients 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
13. Félicitations
Félicitations, vous avez réussi à configurer et à valider la connectivité à un Agentspace à l'aide d'un domaine personnalisé utilisant 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 permettaient la redirection d'hôte et de chemin d'accès, ce qui permettait la connectivité à Agentspace à l'aide d'un domaine personnalisé.
Cosmopup pense que les ateliers de programmation sont géniaux !
