1. Introduzione
Questo documento fornisce un'architettura di riferimento per la configurazione di un dominio personalizzato per accedere ad AgentSpace. Anziché l'URL gestito da Google assegnato durante la creazione dell'app Agentspace, gli utenti possono utilizzare un dominio personalizzato. Questo codelab mostra l'accesso alle applicazioni di calendario e drive di Agentspace utilizzando il dominio nip.io. nip.io è un servizio senza costi e open source che fornisce DNS con caratteri jolly per qualsiasi indirizzo IP. In sostanza, ti consente di creare un nome host che si risolve in un indirizzo IP specifico senza dover configurare un server DNS o modificare il file /etc/hosts.
È consigliabile utilizzare il proprio dominio, ma a scopo dimostrativo nel tutorial viene utilizzato nip.io.
Nello scenario di deployment illustrato di seguito (Figura 1), AgentSpace ha pubblicato un datastore contenente un'applicazione di calendario a cui si accede tramite un URL pubblico gestito da Google.
Figura 1

La crescita continua del datastore e delle applicazioni successive comporta un'ulteriore gestione degli URL pubblici gestiti da Google, come illustrato nello scenario di deployment riportato di seguito (Figura 2), con conseguente mappatura 1:1 delle applicazioni Agentspace e dell'URL.
Figura 2.

Un dominio personalizzato consente di mappare varie applicazioni AgentSpace a un singolo dominio cliente specificato dall'utente. Questa funzionalità consente di associare un percorso URL specifico a ogni applicazione Agentspace, offrendo una maggiore flessibilità, come illustrato nello scenario di deployment riportato di seguito (Figura 3). Ad esempio, un dominio gestito dal cliente agentspace.cosmopup.com è segmentato in regole di percorso, ognuna mappata a un'applicazione Agentspace specifica. Ecco alcuni esempi:
- agentspace.cosmopup.com/drive-app che esegue il mapping all'applicazione Agentspace per Workspace Drive
- agentspace.cosmopup.com/calendar-app che esegue il mapping all'applicazione Agentspace per Workspace Calendar
Le regole host e percorso del bilanciatore del carico delle applicazioni esterno,configurate tramite la mappa URL, controllano la logica che mappa il dominio personalizzato all'URL gestito da Google. Esegue la seguente funzione utilizzando lo spazio di lavoro dell'agente di esempio agentspace.cosmopup.com/drive-app
- Il percorso dell'host del dominio personalizzato agentspace.cosmopup.com/drive-app viene ricevuto dal load balancer
- La mappa URL è configurata per la corrispondenza avanzata delle regole host e percorso
- L'agentespace.cosmopup.com è idoneo per la corrispondenza e la riscrittura dei percorsi
- Il percorso dell'host del dominio personalizzato agentspace.cosmopup.com/drive-app è soggetto a UrlRewrite
- PathPrefixRewrite è il percorso Agentspace: /us/home/cid/5970a1b4-080a-4b44-8acd-fa89460cf0cd
- hostRewrite è l'host di Agentspace: vertexaisearch.cloud.google.com
- L'operazione di riscrittura viene eseguita prima del routing al servizio di backend
- Il servizio di backend indirizza il traffico all'applicazione drive-app in base all'URL di Agentspace
Figura 3

Cosa imparerai a fare
- Crea un bilanciatore del carico delle applicazioni esterno globale
- Crea una riscrittura del servizio di backend utilizzando un dominio personalizzato e un'operazione di riscrittura in un'applicazione Agentspace
- Come integrare nip.io e Cloud DNS per creare un dominio personalizzato
- Come convalidare l'accesso a un dominio personalizzato di Agentspace
Che cosa ti serve
- Progetto Google Cloud con autorizzazioni di proprietario
- URL delle applicazioni Agentspace esistenti
- Dominio personalizzato di proprietà (facoltativo)
- Certificati - Autofirmati o gestiti da Google
2. Cosa creerai
Configurerai un bilanciatore del carico delle applicazioni esterno globale con funzionalità di gestione avanzata del traffico per attivare la corrispondenza del percorso del dominio personalizzato per le applicazioni AgentSpace utilizzando la riscrittura di host e percorsi. Una volta eseguito il deployment, esegui le seguenti azioni per convalidare l'accesso all'applicazione Agentspace:
- Accedi all'applicazione Agentspace aprendo un browser web e andando al dominio personalizzato e al percorso specificato.

3. Requisiti di rete
Di seguito è riportata la suddivisione dei requisiti di rete:
Componenti | Descrizione |
VPC (agentspace-vpc) | VPC in modalità personalizzata |
NEG Internet | Una risorsa utilizzata per definire un backend esterno per il bilanciatore del carico configurato come FQDN che indica l'FQDN gestito da Google di Agentspace (vertexaisearch.cloud.google.com). Il nome di dominio completo (FQDN) di internet esegue la ricerca DNS all'interno del VPC per la risoluzione. |
Servizio di backend | Un servizio di backend funge da ponte tra il bilanciatore del carico e le risorse di backend. Nel tutorial, il servizio di backend è associato al NEG internet. |
Certificati | Per configurare i certificati per un bilanciamento del carico delle applicazioni in Google Cloud, utilizzerai il servizio Certificate Manager e i certificati SSL gestiti da Google o autogestiti. |
Cloud DNS | La zona pubblica Cloud DNS viene utilizzata per risolvere l'IP esterno del bilanciatore del carico delle applicazioni esterno in nip.io (agentspace.externalip.nip.io). In alternativa, utilizza il tuo dominio personalizzato e il record A costituito dall'indirizzo IP del bilanciatore del carico. |
4. Topologia del codelab


5. Configurazione e requisiti
Configurazione dell'ambiente autonomo
- Accedi alla console Google Cloud e crea un nuovo progetto o riutilizzane uno esistente. Se non hai ancora un account Gmail o Google Workspace, devi crearne uno.



- Il nome del progetto è il nome visualizzato per i partecipanti a questo progetto. È una stringa di caratteri non utilizzata dalle API di Google. Puoi sempre aggiornarlo.
- L'ID progetto è univoco in tutti i progetti Google Cloud ed è immutabile (non può essere modificato dopo l'impostazione). La console Cloud genera automaticamente una stringa univoca, di solito non ti interessa di cosa si tratta. Nella maggior parte dei codelab, dovrai fare riferimento all'ID progetto (in genere identificato come
PROJECT_ID). Se l'ID generato non ti piace, puoi generarne un altro casuale. In alternativa, puoi provare a crearne uno e vedere se è disponibile. Non può essere modificato dopo questo passaggio e rimane per tutta la durata del progetto. - Per tua informazione, esiste un terzo valore, un numero di progetto, utilizzato da alcune API. Scopri di più su tutti e tre questi valori nella documentazione.
- Successivamente, devi abilitare la fatturazione in Cloud Console per utilizzare le risorse/API Cloud. Completare questo codelab non costa molto, se non nulla. Per arrestare le risorse ed evitare addebiti oltre a quelli previsti in questo tutorial, puoi eliminare le risorse che hai creato o il progetto. I nuovi utenti di Google Cloud possono beneficiare del programma prova senza costi di 300$.
Avvia Cloud Shell
Sebbene Google Cloud possa essere gestito da remoto dal tuo laptop, in questo codelab utilizzerai Google Cloud Shell, un ambiente a riga di comando in esecuzione nel cloud.
Nella console Google Cloud, fai clic sull'icona di Cloud Shell nella barra degli strumenti in alto a destra:

Bastano pochi istanti per eseguire il provisioning e connettersi all'ambiente. Al termine, dovresti vedere un risultato simile a questo:

Questa macchina virtuale è caricata con tutti gli strumenti per sviluppatori di cui avrai bisogno. Offre una home directory permanente da 5 GB e viene eseguita su Google Cloud, migliorando notevolmente le prestazioni e l'autenticazione della rete. Tutto il lavoro in questo codelab può essere svolto all'interno di un browser. Non devi installare nulla.
6. Prima di iniziare
Abilita API
In Cloud Shell, assicurati che l'ID progetto sia configurato:
gcloud config list project
gcloud config set project [YOUR-PROJECT-ID]
project=[YOUR-PROJECT-ID]
region=[YOUR-REGION]
echo $project
echo $region
Attiva tutti i servizi necessari:
gcloud services enable compute.googleapis.com
gcloud services enable dns.googleapis.com
7. Crea rete VPC
Rete VPC
In Cloud Shell, esegui le seguenti operazioni:
gcloud compute networks create agentspace-vpc --subnet-mode custom
8. Configura i componenti del bilanciatore del carico
Prenota l'indirizzo IP esterno del bilanciatore del carico
In Cloud Shell, prenota un indirizzo IP esterno per il bilanciatore del carico:
gcloud compute addresses create external-ip \
--network-tier=PREMIUM \
--ip-version=IPV4 \
--global
In Cloud Shell, visualizza l'indirizzo IP riservato:
gcloud compute addresses describe external-ip \
--global | grep -i address:
Output di esempio:
user@cloudshell$ gcloud compute addresses describe external-ip \
--global | grep -i address:
address: 34.54.158.206
Configura il NEG internet
Crea un NEG internet e imposta –network-endpoint-type su internet-fqdn-port (il nome host e la porta su cui è raggiungibile il backend esterno). Per risolvere Agentspace, vengono utilizzati l'FQDN vertexaisearch.cloud.google.com e la porta 443.
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
Crea il bilanciatore del carico
In Cloud Shell, esegui le seguenti operazioni:
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
Creare il certificato
A questo punto, hai creato il NEG internet e il servizio di backend. Nella sezione seguente dovrai creare una risorsa del certificato da utilizzare nel proxy HTTPS di destinazione. Puoi creare una risorsa del certificato SSL utilizzando un certificato SSL gestito da Google o un certificato SSL autogestito. Ti consigliamo di utilizzare i certificati gestiti da Google perché Google Cloud li ottiene, gestisce e rinnova automaticamente.
Per scoprire di più sui certificati supportati per il bilanciatore del carico delle applicazioni esterno globale utilizzato in questo tutorial, consulta quanto segue:
Panoramica dei certificati SSL | Bilanciamento del carico | Google Cloud
Nella sezione seguente, creerai un certificato autofirmato (anche se è possibile utilizzare un certificato gestito da Google) che richiede il mapping del nome comune al nome di dominio completo (agentspace.YOUR-EXTERNAL-IP.nip.io) corrisponde all'indirizzo IP esterno del bilanciatore del carico generato in precedenza, come nell'esempio seguente:
Nome comune: agentspace.34.54.158.206.nip.io
In Cloud Shell, crea la chiave privata
openssl genrsa -out private-key-file.pem 2048
In Cloud Shell, crea un file config.txt utilizzato per generare il file pem. Specifica il nome di dominio completo nella voce DNS 1 agentspace.YOUR-EXTERNAL-IP.nip.io, ad esempio agentspace.34.54.158.206.nip.io nella configurazione riportata di seguito.
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
In Cloud Shell, verifica che siano stati generati i file config.txt e private-key-file.pem.
user@cloudshell:$ ls
config.txt private-key-file.pem
In Cloud Shell, esegui quanto segue.
sudo openssl req -new -key private-key-file.pem \
-out csr.pem \
-config config.txt
Esempio:
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 []:
In Cloud Shell, convalida la creazione del file PEM richiesto per la firma del certificato.
user@cloudshell:$ ls
config.txt csr.pem private-key-file.pem
In Cloud Shell, genera il certificato.
sudo openssl x509 -req \
-signkey private-key-file.pem \
-in csr.pem \
-out cert.cert \
-extfile config.txt \
-extensions extension_requirements \
-days 365
Output di esempio:
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
In Cloud Shell, convalida la creazione del file cert.cert
user@cloudshell:$ ls
cert.cert config.txt csr.pem private-key-file.pem
Crea una risorsa certificato da associare al bilanciatore del carico esterno. Sostituisci i parametri del certificato e della chiave privata con i nomi dei file specifici.
In Cloud Shell, esegui le seguenti operazioni:
gcloud compute ssl-certificates create agentspace-self-signed-cert \
--certificate=cert.cert \
--private-key=private-key-file.pem \
--global
In Cloud Shell, esegui le seguenti operazioni:
gcloud compute url-maps create agentspace-lb \
--default-service=agentspace-ineg-bes \
--global
In Cloud Shell, esegui le seguenti operazioni:
gcloud compute target-https-proxies create https-proxy \
--ssl-certificates=agentspace-self-signed-cert \
--url-map=agentspace-lb \
--global
In Cloud Shell, esegui le seguenti operazioni:
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. Crea zona DNS pubblica
Nella sezione seguente, creerai una zona DNS pubblica utilizzata da nip.io per la risoluzione rispetto all'indirizzo IP del bilanciatore del carico esterno.
In Cloud Shell, esegui le seguenti operazioni per creare una variabile per l'indirizzo IP del bilanciatore del carico esterno:
externalip=<YOUR-EXTERNAL-IP>
echo $externalip
In Cloud Shell, esegui le seguenti operazioni:
gcloud dns --project=$project managed-zones create agentspace-dns --description="Agentspace public dns" --dns-name="$externalip.nip.io." --visibility="public"
In Cloud Shell, esegui le seguenti operazioni:
gcloud dns --project=$project record-sets create agentspace.$externalip.nip.io. --zone="agentspace-dns" --type="A" --ttl="300" --rrdatas="$externalip"
10. Credenziali OAuth
Nella sezione seguente, creerai una credenziale OAuth per le applicazioni web che reindirizza l'URL gestito da Google a oauth-redirect per l'autenticazione. Le credenziali generate non sono necessarie per il tutorial.
Per saperne di più su OAuth, consulta le seguenti risorse:
Aggiungere azioni di Google Calendar e Gmail | Google Agentspace
Crea un'app OAuth e aggiungi ambiti
- Vai ad API e servizi > Schermata consenso OAuth: Vai alla schermata consenso OAuth
- Seleziona Interno e poi fai clic su Crea.
- Inserisci un nome per l'app OAuth.
- Inserisci un'email di assistenza utenti.
- Inserisci i dati di contatto dello sviluppatore.
- Fai clic su Salva e continua.
Creare un ID client OAuth
Questa procedura descrive come creare un nuovo ID client OAuth per le azioni Google Cloud. Questo ID client OAuth e il client secret possono essere utilizzati anche per altre azioni Google Cloud. Se hai un ID client OAuth Google Cloud esistente per le azioni Google Cloud, puoi utilizzare questo ID client e il relativo segreto per le azioni Google Calendar anziché crearne uno nuovo.
- Vai alla pagina Credenziali e fai clic su Crea credenziali > ID client OAuth.
- Seleziona Applicazione web.
- Inserisci un nome per l'ID client.
- Fai clic su Aggiungi URI e inserisci il seguente URI: https://vertexaisearch.cloud.google.com/oauth-redirect
- Fai clic su Crea e copia le seguenti informazioni:
- ID client
- Client secret
11. Identificare gli URL dell'applicazione Agentspace
La seguente procedura identifica gli URL pubblici di Agentspace gestiti da Google generati da Google e mappati a ogni applicazione Agentspace. L'output degli URL sono esempi basati sull'architettura di riferimento, pertanto devi assicurarti che gli URL siano accurati.
Assicurati di memorizzare il link alla tua app web per ogni applicazione.
Applicazione Calendar
URL web di Agentspace: https://vertexaisearch.cloud.google.com/us/home/cid/bb6b8b27-939b-494d-9227-45903bb8afcf

Applicazione Drive
URL web di Agentspace:
https://vertexaisearch.cloud.google.com/us/home/cid/5970a1b4-080a-4b44-8acd-fa89460cf0cd

12. Crea una regola avanzata per host e percorso
Nella sezione seguente, aggiornerai le regole di routing dei bilanciatori del carico per attivare l'opzione che consente di definire le regole host e percorso utilizzando la console cloud. La tabella riportata di seguito descrive i valori personalizzati (in ordine dall'alto verso il basso), aggiornati in base al tuo ambiente:
Valore personalizzato | Esempio basato sul tutorial | |
Hosting | agentspace.YOUR-EXTERNAL-IP.nip.io | agentspace.34.54.158.206.nip.io |
defaultService | projects/<projectid>/global/backendServices/agentspace-ineg-bes | Vedi screenshot |
prefixMatch | /<name of Agentspace app#1> | /drive-app |
backendService | projects/<projectid>/global/backendServices/agentspace-ineg-bes | Vedi screenshot |
pathPrefixRewrite | /<Agentspace URL path of app#1> | /us/home/cid/5970a1b4-080a-4b44-8acd-fa89460cf0cd |
hostRewrite | vertexaisearch.cloud.google.com | vertexaisearch.cloud.google.com |
prefixMatch | /<name of Agentspace app#2> | /calendar-app |
backendService | projects/<projectid>/global/backendServices/agentspace-ineg-bes | Vedi screenshot |
pathPrefixRewrite | /<Agentspace URL path of app#2> | /us/home/cid/bb6b8b27-939b-494d-9227-45903bb8afcf |
hostRewrite | vertexaisearch.cloud.google.com | vertexaisearch.cloud.google.com |
Per accedere alle regole host e percorso, vai a:
Bilanciamento del carico → agentspace-lb → Seleziona Modifica
Seleziona Regole di routing → Regole avanzate per host e percorso
Seleziona Aggiungi regola host e percorso

Ora puoi creare una nuova regola host e percorso. Nella sezione degli host, inserisci agentspace.YOUR-EXTERNAL-IP.nip.io o il dominio personalizzato.

Nel campo Matcher percorso (corrispondenze, azioni e servizi), aggiorna i contenuti riportati di seguito con la configurazione dell'ambiente, quindi seleziona Aggiorna.
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
Screenshot di esempio:


13. Convalida
Il deployment è stato completato. Puoi accedere all'applicazione Agentspace utilizzando il dominio personalizzato tramite un browser web o un terminale specificando agentspace.YOUR-EXTERNAL-IP.nip.io/path, ad esempio agentspace.34.54.158.206.nip.io.Ecco alcuni esempi:
Applicazione Agentspace: drive-app
Percorso: agentspace.34.54.158.206.nip.io/drive-app
Applicazione Agentspace: drive-app
Percorso: agentspace.34.54.158.206.nip.io/calendar-app
14. Esegui la pulizia
Per eliminare le credenziali OAuth, segui questi passaggi:
Vai ad API e servizi → Credenziali
In ID client OAuth 2.0, seleziona le tue credenziali ed elimina
Da un singolo terminale Cloud Shell, elimina i componenti del lab:
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. Complimenti
Congratulazioni, hai configurato e convalidato correttamente la connettività a un AgentSpace utilizzando un dominio personalizzato tramite un bilanciatore del carico delle applicazioni esterno con gestione avanzata del traffico.
Hai creato l'infrastruttura del bilanciatore del carico, hai imparato a creare un NEG internet, Cloud DNS e la gestione avanzata del traffico che ha abilitato la riscrittura di host e percorsi, consentendo la connettività ad Agentspace utilizzando un dominio personalizzato.
Cosmopup pensa che i codelab siano fantastici.
