1. Introduzione
Questo documento fornisce un'architettura di riferimento per la configurazione di un dominio personalizzato per accedere ad AgentSpace utilizzando WIF. 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 open source senza costi che fornisce DNS 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 nell'esercitazione 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 unico 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, ciascuna 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/sharepoint-app che esegue la mappatura all'applicazione Agentspace per SharePoint
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'host agentspace.cosmopup.com è idoneo per la corrispondenza del percorso e il reindirizzamento
- Il percorso dell'host del dominio personalizzato agentspace.cosmopup.com/drive-app è soggetto a UrlRedirect
- pathRedirect è il percorso di Agentspace: /us/home/cid/5970a1b4-080a-4b44-8acd-fa89460cf0cd
- hostRedirect è l'host di Agentspace: vertexaisearch.cloud.google.com
- Il percorso dell'host del dominio personalizzato agentspace.cosmopup.com/sharepoint-app è soggetto a UrlRedirect
- pathRedirect è il percorso 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 è l'host di Agentspace: auth.cloud.google
- L'operazione di reindirizzamento viene eseguita prima del routing al servizio di backend
Figura 3
Cosa imparerai a fare
- Crea un bilanciatore del carico delle applicazioni esterno globale
- Crea un routing per reindirizzare un dominio personalizzato a 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
Stabilirai 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 il reindirizzamento di host e percorso. 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 Agentspace (vertexaisearch.cloud.google.com). Il nome di dominio completo 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 di internet. |
Certificati | Per configurare i certificati per un bilanciamento del carico delle applicazioni in Google Cloud, utilizzerai il servizio Certificate Manager e 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 autonoma
- Accedi alla console Google Cloud e crea un nuovo progetto o riutilizzane uno esistente. Se non hai già 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 non ti piace l'ID generato, 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 da questo tutorial, puoi eliminare le risorse che hai creato o il progetto. I nuovi utenti di Google Cloud possono usufruire 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 di sviluppo di cui avrai bisogno. Offre una home directory permanente da 5 GB e viene eseguita su Google Cloud, migliorando notevolmente le prestazioni di rete e l'autenticazione. 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. 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 di internet e imposta –network-endpoint-type su internet-fqdn-port (il nome host e la porta in 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 servizio di backend e il NEG internet. Nella sezione seguente dovrai creare una risorsa 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 | 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 le operazioni riportate di seguito.
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 di firma del certificato richiesto.
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 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
8. 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"
9. 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 Drive
URL web di Agentspace:
https://vertexaisearch.cloud.google.com/us/home/cid/5970a1b4-080a-4b44-8acd-fa89460cf0cd
Applicazione SharePoint
URL web di 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. 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 di host e percorso utilizzando la console Cloud. La tabella riportata di seguito mostra i valori personalizzati (in ordine dall'alto verso il basso) da aggiornare 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 | projects/your-project-id/global/backendServices/agentspace-ineg-bes |
prefixMatch | /<name of Agentspace app#1> | /drive-app |
pathRedirect | /<Agentspace URL path of app#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 | /<Agentspace URL path of app#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 |
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
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
Screenshot di esempio:
11. 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: sharepoint-app
Percorso: agentspace.34.54.158.206.nip.io/sharepoint-app
12. Esegui la pulizia
Per eliminare le credenziali OAuth, procedi nel seguente modo:
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
13. Complimenti
Congratulazioni, hai configurato e convalidato correttamente la connettività a uno spazio di lavoro dell'agente 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 il reindirizzamento di host e percorsi che ha consentito la connettività ad AgentSpace utilizzando un dominio personalizzato.
Cosmopup pensa che i codelab siano fantastici.
