Dominio personalizzato Agentspace

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

27591afa06891dcb.png

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.

7e31bfae7ac56b22.png

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

f8d84ec5fef9af5a.png

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.

c62938d91e00ffa7.png

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

c62938d91e00ffa7.png

f712980116d973a3.png

5. Configurazione e requisiti

Configurazione dell'ambiente autonomo

  1. 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.

fbef9caa1602edd0.png

a99b7ace416376c4.png

5e3ff691252acf41.png

  • 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.
  1. 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:

55efc1aaa7a4d3ad.png

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

7ffe5cbb04455448.png

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

  1. Vai ad API e servizi > Schermata consenso OAuth: Vai alla schermata consenso OAuth
  2. Seleziona Interno e poi fai clic su Crea.
  3. Inserisci un nome per l'app OAuth.
  4. Inserisci un'email di assistenza utenti.
  5. Inserisci i dati di contatto dello sviluppatore.
  6. 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.

  1. Vai alla pagina Credenziali e fai clic su Crea credenziali > ID client OAuth.
  2. Seleziona Applicazione web.
  3. Inserisci un nome per l'ID client.
  4. Fai clic su Aggiungi URI e inserisci il seguente URI: https://vertexaisearch.cloud.google.com/oauth-redirect
  5. 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

b90c67aafd825ccd.png

Applicazione Drive

URL web di Agentspace:

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

f8f850425fd11190.png

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

4bc965db43aed21b.png

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

f36e4fa11c950d8d.png

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:

22788283124c59ec.png

cef8f571ca17bf42.png

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.

c911c127bffdee57.jpeg

Documentazione di riferimento