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 di Drive di Agentspace utilizzando il dominio nip.io. nip.io è un servizio open source senza costi che fornisce DNS con caratteri jolly per qualsiasi indirizzo IP. In sostanza, ti consente di creare un nome host che risolve in un indirizzo IP specifico senza dover configurare il tuo server DNS o modificare il file /etc/hosts.
Ti consigliamo di utilizzare il tuo dominio, ma per scopi dimostrativi nel tutorial viene utilizzato nip.io.
Nello scenario di implementazione illustrato di seguito (Figura 1), AgentSpace ha pubblicato un data store 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 implementazione di seguito (Figura 2), con una mappatura 1:1 delle applicazioni e degli URL di Agentspace.
Figura 2.
Un dominio personalizzato consente la mappatura di 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 implementazione di seguito (Figura 3). Ad esempio, un dominio gestito dal cliente agentspace.cosmopup.com è suddiviso in regole di percorso, ciascuna mappata a un'applicazione Agentspace specifica, ad esempio:
- agentspace.cosmopup.com/drive-app che mappa l'applicazione Agentspace per Drive di Workspace
- agentspace.cosmopup.com/calendar-app che mappa l'applicazione Agentspace per Calendar di Workspace
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 l'esempio agentspace.cosmopup.com/drive-app
- Il percorso dell'host del dominio personalizzato agentspace.cosmopup.com/drive-app viene ricevuto dal bilanciatore del carico
- La mappa URL è configurata per la corrispondenza delle regole avanzate per host e percorso
- L'host agentspace.cosmopup.com è idoneo per la corrispondenza e la riscrittura del percorso
- Il percorso dell'host del dominio personalizzato agentspace.cosmopup.com/drive-app è soggetto a UrlRewrite
- PathPrefixRewrite è il percorso di 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 inoltra il traffico all'applicazione di guida in base all'URL di Agentspace
Figura 3
Cosa imparerai a fare
- Creare 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 dell'applicazione Agentspace esistenti
- (Facoltativo) Dominio personalizzato di proprietà dell'utente
- Certificati: autofirmati o gestiti da Google
2. Cosa creerai
Dovrai creare un bilanciatore del carico delle applicazioni esterno globale con funzionalità di gestione avanzata del traffico per abilitare la corrispondenza del percorso del dominio personalizzato per le applicazioni Agentspace che utilizzano la riscrittura dell'host e del percorso. Una volta eseguito il deployment, dovrai eseguire 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). L'FQDN 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 bilanciatore 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'indirizzo 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 composto dall'indirizzo IP del bilanciatore del carico. |
4. Topologia del codelab
5. Configurazione e requisiti
Configurazione dell'ambiente a tuo ritmo
- 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 al progetto. Si tratta di una stringa di caratteri non utilizzata dalle API di Google. Puoi sempre aggiornarlo.
- L'ID progetto è univoco per tutti i progetti Google Cloud ed è immutabile (non può essere modificato dopo essere stato impostato). La console Cloud genera automaticamente una stringa univoca; di solito non ti interessa quale sia. Nella maggior parte dei codelab, dovrai fare riferimento al tuo ID progetto (in genere identificato come
PROJECT_ID). Se l'ID generato non ti piace, puoi generarne un altro casuale. In alternativa, puoi provare il tuo e vedere se è disponibile. Non può essere modificato dopo questo passaggio e rimane invariato per tutta la durata del progetto. - Per tua informazione, esiste un terzo valore, un Numero progetto, utilizzato da alcune API. Scopri di più su tutti e tre questi valori nella documentazione.
- Successivamente, dovrai abilitare la fatturazione nella console Cloud per utilizzare le API/risorse Cloud. La partecipazione a questo codelab non ha costi, o quasi. Per arrestare le risorse ed evitare di incorrere in fatturazione al termine di questo tutorial, puoi eliminare le risorse che hai creato o il progetto. I nuovi utenti di Google Cloud sono idonei al programma Prova senza costi di 300$.
Avvia Cloud Shell
Sebbene Google Cloud possa essere utilizzato 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:
Dovrebbe richiedere solo pochi istanti per eseguire il provisioning e connettersi all'ambiente. Al termine, dovresti vedere qualcosa di simile a questo:
Questa macchina virtuale contiene tutti gli strumenti di sviluppo 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 di rete. Tutto il lavoro in questo codelab può essere svolto in 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, svolgi i seguenti passaggi:
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 il parametro –network-endpoint-type su internet-fqdn-port (il nome host e la porta su cui è possibile raggiungere 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, svolgi i seguenti passaggi:
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
Crea il certificato
A questo punto, hai creato il servizio neg e il servizio di backend. Nella sezione seguente dovrai creare una risorsa del certificato da utilizzare nel proxy di destinazione HTTPs. 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, li gestisce e li 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 | Load Balancing | Google Cloud
Nella sezione seguente, creerai un certificato autofirmato (anche se è possibile utilizzare un certificato gestito da Google) che richiede la mappatura del nome comune al nome di dominio completo (agentspace.YOUR-EXTERNAL-IP.nip.io) corrispondente 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 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, convalida che i file config.txt e private-key-file.pem siano stati generati.
user@cloudshell:$ ls
config.txt private-key-file.pem
In Cloud Shell, svolgi i seguenti passaggi.
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 del certificato da associare al bilanciatore del carico esterno. Sostituisci i parametri del certificato e della chiave privata con i nomi file specifici.
In Cloud Shell, svolgi i seguenti passaggi:
gcloud compute ssl-certificates create agentspace-self-signed-cert \
--certificate=cert.cert \
--private-key=private-key-file.pem \
--global
In Cloud Shell, svolgi i seguenti passaggi:
gcloud compute url-maps create agentspace-lb \
--default-service=agentspace-ineg-bes \
--global
In Cloud Shell, svolgi i seguenti passaggi:
gcloud compute target-https-proxies create https-proxy \
--ssl-certificates=agentspace-self-signed-cert \
--url-map=agentspace-lb \
--global
In Cloud Shell, svolgi i seguenti passaggi:
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 una 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, segui questa procedura per creare una variabile per l'indirizzo IP del bilanciatore del carico esterno:
externalip=<YOUR-EXTERNAL-IP>
echo $externalip
In Cloud Shell, svolgi i seguenti passaggi:
gcloud dns --project=$project managed-zones create agentspace-dns --description="Agentspace public dns" --dns-name="$externalip.nip.io." --visibility="public"
In Cloud Shell, svolgi i seguenti passaggi:
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 scoprire di più su OAuth, consulta quanto segue:
Aggiungere azioni di Google Calendar e Gmail | Google Agentspace
Creare un'app OAuth e aggiungere ambiti
- Vai ad API e servizi > Schermata consenso OAuth: Vai alla schermata di consenso OAuth
- Seleziona Interno e poi fai clic su Crea.
- Inserisci un nome per l'app OAuth.
- Inserisci un indirizzo email di assistenza per l'utente.
- 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 questa chiave segreta possono essere utilizzati anche per altre azioni Google Cloud. Se hai già un ID client OAuth di Google Cloud per le azioni di Google Cloud, puoi utilizzare questo ID client e il relativo segreto per le azioni di Google Calendar anziché creare un nuovo ID client.
- 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. Identifica gli URL delle applicazioni Agentspace
La procedura seguente identifica gli URL pubblici di Agentspace gestiti da Google generati da Google e mappati ad Agentspace per ogni applicazione. L'output degli URL è costituito da 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. Creare una regola avanzata per host e percorso
Nella sezione seguente, aggiornerai le regole di routing dei bilanciatori del carico per attivare l'opzione di definizione delle regole per host e percorsi utilizzando la console Cloud. La tabella seguente illustra 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 | Visualizza screenshot |
prefixMatch | /<nome dell'app Agentspace#1> | /drive-app |
backendService | projects/<projectid>/global/backendServices/agentspace-ineg-bes | Visualizza screenshot |
pathPrefixRewrite | /<Percorso dell'URL di Agentspace dell'app 1> | /us/home/cid/5970a1b4-080a-4b44-8acd-fa89460cf0cd |
hostRewrite | vertexaisearch.cloud.google.com | vertexaisearch.cloud.google.com |
prefixMatch | /<nome dell'app Agentspace 2> | /calendar-app |
backendService | projects/<projectid>/global/backendServices/agentspace-ineg-bes | Visualizza screenshot |
pathPrefixRewrite | /<Percorso dell'URL di Agentspace dell'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 host e percorso avanzate
Seleziona Aggiungi regola host e percorso
A questo punto ti viene chiesto di creare una nuova regola host e percorso. Nella sezione Host, inserisci agentspace.YOUR-EXTERNAL-IP.nip.io o un dominio personalizzato.
Nel campo Matcher percorso (corrispondenze, azioni e servizi), aggiorna i contenuti 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, come mostrato di seguito:
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, svolgi i seguenti passaggi:
Vai ad API e servizi → Credenziali
In ID client OAuth 2.0, seleziona le tue credenziali ed eliminale
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 con 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 consentito la riscrittura di host e percorsi che ha consentito la connettività ad Agentspace utilizzando un dominio personalizzato.
Cosmopup pensa che i codelab siano fantastici.
