Esegui rapidamente il deployment delle app con App Design Center

1. Introduzione

In questo codelab imparerai a eseguire il deployment di un'applicazione full-stack utilizzando App Design Center (ADC) di Google Cloud. Eseguirai il deployment dell'applicazione "The Cymbal London Concierge", che include un frontend Vue 3, un backend FastAPI e un server MCP che contiene i dati dell'applicazione.

ADC ti consente di definire visivamente l'architettura dell'applicazione ed eseguirne il deployment come singola unità, gestendo automaticamente dipendenze e connessioni.

In questo lab proverai a:

• Configura App Design Center.
• Assembla visivamente i componenti dell'applicazione.
• Esegui il deployment dell'architettura dell'applicazione.
• Verifica l'applicazione in esecuzione.
• Verifica che l'applicazione sia stata registrata in App Hub.
• Verifica le metriche, le tracce e i log dell'applicazione in Application Monitoring.

Che cosa ti serve

• Un browser web come Chrome.
• Un progetto Google Cloud con la fatturazione abilitata.

Questo codelab è rivolto a sviluppatori di tutti i livelli, inclusi i principianti.

Durata stimata: 45 minuti Costo stimato: meno di 2 $

2. Configurazione

Configurazione del progetto

Crea un progetto Google Cloud

1. Nella console Google Cloud, nella pagina di selezione del progetto, seleziona o crea un progetto Google Cloud.
2. Verifica che la fatturazione sia attivata per il tuo progetto Cloud. Scopri come verificare se la fatturazione è abilitata per un progetto.

Avvia Cloud Shell

Cloud Shell è un ambiente a riga di comando in esecuzione in Google Cloud che viene precaricato con gli strumenti necessari.

1. Fai clic su Attiva Cloud Shell nella parte superiore della console Google Cloud.
2. Una volta connesso a Cloud Shell, verifica l'autenticazione:

   gcloud auth list
   

3. Verifica che il progetto sia configurato:

   gcloud config get project
   

4. Se il progetto non è impostato come previsto, impostalo:

   export PROJECT_ID=<YOUR_PROJECT_ID>
   gcloud config set project $PROJECT_ID
   

3. Configura App Design Center

Prima di poter assemblare l'applicazione, devi configurare lo spazio di lavoro in ADC.

1. Nella console Google Cloud, cerca App Design Center e vai alla pagina.
2. Se è la prima volta che utilizzi ADC in questo progetto, vedrai una schermata di configurazione.
3. Fai clic su Vai alla configurazione.

4. Se non sono già abilitate, ti verrà chiesto di abilitare le API richieste. Fai clic su Attiva per continuare.

4. Esplorare le funzionalità di ADC

In questa attività, imparerai i componenti principali di ADC: spazi, cataloghi e modelli.

ADC Spaces

Uno spazio è un'area in cui creare modelli ed eseguire il deployment delle app. Ogni spazio appartiene a un progetto Google Cloud. ADC crea uno spazio predefinito durante la configurazione iniziale, ma in seguito puoi creare altri spazi in regioni diverse.

Per visualizzare i tuoi spazi tramite il terminale, segui questi passaggi:

1. Fai clic su Apri editor nella barra degli strumenti di Cloud Shell o utilizza il terminale.
2. Esegui questo comando:

gcloud alpha design-center spaces list \
--project="your PROJECT ID" \
--location=us-central1

Dovresti vedere un output simile a questo, che indica che lo spazio predefinito è presente per la regione.

createTime: '20XXXX-XX-XXT09:19:29.456016967Z'
displayName: default-space
enableGcpSharedTemplates: true
name: projects/your-project-id/locations/us-central1/spaces/default-space

5. Assembla il modello

In questo passaggio, assumerai il ruolo di ingegnere del team della piattaforma. Il tuo obiettivo è creare un modello riutilizzabile, sicuro e conforme per le applicazioni con agenti nella tua organizzazione. Aggiungerai componenti e configurerai restrizioni per garantire che qualsiasi applicazione di cui viene eseguito il deployment da questo modello sia conforme alle norme cloud della tua azienda.

1. Crea un nuovo design

1. Nella console ADC, fai clic su Modelli > Crea modello.
2. Assegna al modello il nome simple-3-tier-agentic-app, in quanto verrà utilizzato per il deployment dell'applicazione Cymbal London Concierge e di altre applicazioni simili.

2. Aggiungere il server MCP dati

Questo componente gestisce le interazioni con il database e la ricerca vettoriale.

1. Fai clic su Aggiungi componente > Cloud Run (servizio). Se fai clic su questo componente, vedrai un ID componente nell'angolo in alto a destra. Avrà il formato cloud-run-1. Possiamo modificarlo in data-mcp-server modificandolo nella visualizzazione codice (di cui parleremo più avanti), ma lasciamolo così com'è.
2. Inserisci il nome del servizio: data-mcp-server.
3. In Mostra impostazioni avanzate, imposta Membri su: allUsers. (Nota: in un ambiente di produzione, probabilmente limiteresti questa operazione, ma la utilizziamo qui per semplificare il codelab.)
4. Nella sezione Mostra impostazioni avanzate, imposta ACCESSO VPC, imposta Traffico in uscita su: PRIVATE_RANGES_ONLY.
5. (Facoltativo) Nella sezione Mostra impostazioni avanzate, deseleziona Abilita Prometheus Sidecar.
6. Fai clic su Salva.

3. Aggiungi il backend dell'agente

Si tratta dell'applicazione FastAPI che orchestra il comportamento agentico.

1. Fai clic su Aggiungi componente > Cloud Run (servizio).
2. Assegna il nome agent-backend.
3. In Mostra campi avanzati, seleziona Crea service account e aggiungi i seguenti ruoli in Ruoli di progetto del service account uno alla volta:
   • roles/monitoring.metricWriter
   • roles/logging.logWriter
   • roles/cloudtrace.agent
   • roles/telemetry.writer
   • roles/serviceusage.serviceUsageConsumer. Questi ruoli consentiranno all'agente di utilizzare Cloud Monitoring, Cloud Logging e Cloud Trace. Configurazione della conformità:il team della piattaforma applica il principio del privilegio minimo elencando esplicitamente i ruoli richiesti.
   
4. In Mostra impostazioni avanzate, imposta Membri su: allUsers.
5. Nella sezione Mostra impostazioni avanzate, imposta ACCESSO VPC, imposta Traffico in uscita su: PRIVATE_RANGES_ONLY.
6. (Facoltativo) Nella sezione Mostra impostazioni avanzate, deseleziona Abilita Prometheus Sidecar.
7. Collega agent-backend a data-mcp-server trascinando una connessione da agent-backend a data-mcp-server.
8. Fai clic su Salva.

4. Aggiungi il frontend

L'interfaccia utente front-end.

1. Fai clic su Aggiungi componente > Cloud Run (servizio).
2. Inserisci il nome del servizio: frontend.
3. Nella sezione Mostra impostazioni avanzate, deseleziona Crea service account.
4. In Mostra impostazioni avanzate, imposta Ingresso su: INGRESS_TRAFFIC_INTERNAL_LOADBALANCER. Configurazione della conformità:l'accesso pubblico diretto al container frontend è bloccato, forzando il traffico attraverso il bilanciatore del carico.
5. In Mostra impostazioni avanzate, imposta Membri su: allUsers.
6. (Facoltativo) Nella sezione Mostra impostazioni avanzate, deseleziona Abilita Prometheus Sidecar.
7. Fai clic su Salva.
8. Collega frontend a agent-backend trascinando una connessione da frontend a agent-backend.

5. Aggiungere un componente Vertex AI

1. Fai clic su Aggiungi componente > Vertex AI.
2. Assegna il nome vertex-ai.
3. Collega vertex-ai a agent-backend e data-mcp-server trascinando due connessioni da vertex-ai a agent-backend e data-mcp-server rispettivamente. I ruoli aiplatform.user verranno già assegnati ai service account di agent-backend e data-mcp-server in quanto sono connessi al componente Vertex AI.

6. Aggiungi il bilanciatore del carico globale

Il bilanciatore del carico espone il frontend alla rete internet pubblica. In ADC, questo è suddiviso in un componente backend e uno frontend.

A. Aggiungi il backend del bilanciatore del carico

1. Fai clic su **Aggiungi componente > Global Cloud Load Balancing (backend).
2. Assegna il nome galb-backend.
3. Fai clic su Aggiungi connessione e connettila a frontend.

B. Aggiungi il frontend del bilanciatore del carico

1. Fai clic su **Aggiungi componente > Cloud Load Balancing globale (frontend).
2. Assegna il nome galb-frontend.
3. Fai clic su Aggiungi connessione e connettila a galb-backend.
4. Collega galb-frontend a galb-backend trascinando una connessione da galb-frontend a galb-backend.

Condividere il modello nel catalogo

Un catalogo ti consente di condividere modelli di app in diversi spazi, consentendo la governance dell'architettura. Un catalogo funge da repository centrale per i modelli creati e approvati per la condivisione dal team della piattaforma. La condivisione dei cataloghi tra gli spazi evita il lavoro duplicato per i progetti comuni e semplifica i tempi di avvio.

Ora aggiungi il tuo modello al catalogo:

1. Fai clic sulla scheda Cataloghi.
2. Fai clic su Aggiungi modelli e seleziona il modello simple-3-tier-agentic-app.
3. Fai clic su Aggiungi al catalogo.

Puoi trovare i modelli in tre posizioni: Modelli Google (pattern predefiniti), Modelli condivisi (condivisi in tutta l'organizzazione) e Modelli (blueprint personalizzati nel tuo spazio).

6. Esegui il deployment dell'applicazione

Ora è il momento di assumere il ruolo di sviluppatore di app che vuole utilizzare questo modello per eseguire il deployment dell'applicazione cymbal-london-concierge.

1. Nella console ADC, riapri il modello nella scheda Modelli e fai clic sul pulsante Configura app.
2. Fai clic su Crea nuova applicazione.
3. Configura l'applicazione:
   • Nome dell'applicazione: cymbal-london-concierge
   • Progetto di deployment: l'ID progetto
   • Regione: us-central1
   • Attributi di input> Ambiente: Development
   • Attributi di input> Criticità: Low
4. Fai clic su Crea applicazione.Per un deployment di produzione, seleziona "Produzione" per Ambiente e "Alto" per Criticità. Questi tag aiuteranno i tuoi SRE e il team operativo a ordinare e dare la priorità al lavoro su eventuali problemi che si verificano.
5. Dovrebbe aprirsi la pagina dei dettagli del deployment con il modello di applicazione. Poiché si tratta solo di un modello, dobbiamo comunque aggiungere una configurazione specifica per la nostra applicazione.
6. Configuriamo il frontend. Fai clic sul componente frontend.
   1. Fai clic su Contenitori > Modifica contenitore.
   2. Dobbiamo sostituire l'immagine container generica con quella che vogliamo utilizzare per la nostra applicazione.
   3. Imposta Immagine container su: us-central1-docker.pkg.dev/o11y-movie-guru/london-travel-agency/frontend:codelab-c2c6-v1
   4. Imposta la porta http1 su 80.
   5. Imposta le seguenti variabili di ambiente:
      • API_BASE_URL: module.cloud-run-2.service_uri (assicurati che cloud-run-2 sia il nome del componente di backend dell'agente, altrimenti sostituiscilo con il nome effettivo del componente)
   6. Fai clic su Salva.
7. Configuriamo il backend dell'agente. Fai clic sul componente agent-backend.
   1. Fai clic su Contenitori > Modifica contenitore.
   2. Dobbiamo sostituire l'immagine container generica con quella che vogliamo utilizzare per la nostra applicazione.
   3. Imposta Immagine container su: us-central1-docker.pkg.dev/o11y-movie-guru/london-travel-agency/agent:codelab-c2c6-v1
   4. Imposta le seguenti variabili di ambiente:
   5. GOOGLE_CLOUD_PROJECT:
   6. GOOGLE_CLOUD_LOCATION: us-central1
   7. DATA_BACKEND_URL: module.cloud-run-1.service_uri (assicurati che cloud-run-1 sia il nome del componente del server mcp di dati, altrimenti sostituiscilo con il nome effettivo del componente)
   8. Imposta la porta http1 su 8000.
   9. Fai clic su Salva.
8. Configuriamo il server MCP dei dati. Fai clic sul componente data-mcp-server.
   1. Fai clic su Contenitori > Modifica contenitore.
   2. Dobbiamo sostituire l'immagine container generica con quella che vogliamo utilizzare per la nostra applicazione.
   3. Imposta Immagine container su: us-central1-docker.pkg.dev/o11y-movie-guru/london-travel-agency/data_mcp:codelab-c2c6-v1
   4. Imposta le seguenti variabili di ambiente:
   5. GOOGLE_CLOUD_PROJECT:
   6. GOOGLE_CLOUD_LOCATION: us-central1
   7. DB_TYPE: sqlite
   8. EMBEDDING_MODEL: text-embedding-005
   9. Imposta la porta http1 su 8002.
   10. Fai clic su Salva.
   In uno scenario di produzione reale, configureresti anche un database come CloudSQL o AlloyDB e forniresti la stringa di connessione al database per il server mcp dei dati. Per questo lab, però, utilizzeremo un database in memoria. Inoltre, devi rendere privati il server mcp e il database e renderli accessibili solo dal backend dell'agente o dall'interno della rete.
9. Fai clic sul pulsante Codice nella parte superiore della pagina per visualizzare il codice Terraform per l'applicazione. Puoi anche scaricare il codice Terraform per l'applicazione facendo clic sul pulsante Ottieni codice per memorizzarlo nella tua codebase.
10. Fai clic sul pulsante Esegui il deployment nell'angolo in alto a destra della pagina per eseguire il deployment dell'applicazione.
11. La pagina di deployment ti chiederà di creare un service account per la pipeline di deployment o di sceglierne uno esistente. Fai clic su Crea service account (il nome verrà compilato automaticamente) e poi su Procedi. La creazione di un nuovo service account richiede alcuni secondi.

12. Una volta creato il service account, la pagina verrà aggiornata e vedrai Seleziona service account con un segno di spunta accanto.

13. Poi fai clic su Esegui il deployment nella parte inferiore della pagina.
14. Il completamento dell'operazione richiede alcuni minuti. Al termine del deployment, vedrai un segno di spunta verde accanto a ogni componente. Puoi anche controllare lo stato del deployment facendo clic sul pulsante Link ai log, che aprirà i log di Cloud Build. Potrebbero essere necessari alcuni minuti prima che il pulsante venga visualizzato.

![Deployment Logs](./img/10b_logs.png)

15. Puoi visualizzare i log di Cloud Build per vedere lo stato del deployment o se si verificano errori durante il deployment dell'applicazione. Puoi anche andare direttamente ai log di Cloud Build cercando Cloud Build nella console Google Cloud e facendo clic su Cronologia. Il deployment dell'applicazione richiederà circa 5-8 minuti.

![Cloud Build](./img/10c_cloudbuild.png)

16. Al termine del deployment, vedrai un segno di spunta verde accanto al campo Stato del deployment.

![Deployment Complete](./img/11_deployed.png)

7. Verifica dell'applicazione

Verifichiamo se l'agente è attivo. Nella sezione output della pagina dei dettagli del deployment, vedrai l'URL del componente frontend. Copia l'URL e incollalo nel browser. Assicurati di utilizzare http e non https. Accetta anche gli eventuali avvisi visualizzati nel browser perché il frontend utilizza HTTP.

Chatta con l'app e chiedile di creare un itinerario per un viaggio a Londra.

8. App Hub e monitoraggio delle applicazioni

1. Nella console ADC, fai clic sul pulsante Visualizza app in App Hub nell'angolo in alto a destra della pagina.

2. Si aprirà l'app in App Hub. App Hub è una posizione centrale per visualizzare e gestire tutte le tue applicazioni, passando da una visualizzazione incentrata sulle risorse a una incentrata sulle applicazioni. La creazione di un'app utilizzando ADC crea automaticamente un'app in App Hub. Qui dovresti vedere tutti i servizi e i carichi di lavoro che compongono l'applicazione. Anziché visualizzare le risorse nel cloud come risorse individuali, puoi visualizzarle come parte di una singola applicazione, semplificando la gestione e la governance.

3. Fai clic sul pulsante Visualizza in Observability. Si aprirà l'applicazione nella console Observability.
4. Apri la visualizzazione Dashboard. La dashboard offre una panoramica delle prestazioni e dell'integrità dell'applicazione fornendo metriche come i quattro segnali d'oro: tasso di richieste, tasso di errori, latenza e saturazione. Questo monitoraggio incentrato sulle applicazioni è fondamentale per mantenere l'affidabilità. Puoi anche visualizzare i log e le tracce dell'applicazione, il che ti consente di correlare i segnali e individuare i colli di bottiglia. Ciò è particolarmente importante in un'applicazione di agenti complessa come questa, in cui le risposte lente di Vertex AI o del server Data MCP possono peggiorare l'esperienza utente.

5. Esplorazione guidata: poni all'agente una domanda specifica nell'app (ad es. "Quali sono i posti migliori da visitare a Londra?"). Quindi, torna alla console Observability e visualizza l'elenco Trace. Trova la traccia corrispondente alla tua richiesta. Fai clic per visualizzare la visualizzazione a cascata dettagliata. Nota come puoi vedere il tempo trascorso nel frontend, nel backend dell'agente e nelle chiamate a Vertex AI. In questo modo puoi identificare esattamente dove viene introdotta la latenza.

9. Complimenti

Complimenti! Hai eseguito il deployment di un'architettura applicativa a tre livelli utilizzando ADC.

Cosa hai imparato

• Come assemblare visivamente un'architettura cloud utilizzando ADC.
• Come configurare le credenziali predefinite dell'applicazione e abilitare le API tramite la UI.
• Come eseguire il deployment delle applicazioni utilizzando ADC.
• Come utilizzare App Hub per una visualizzazione delle risorse incentrata sulle applicazioni.
• Come monitorare l'integrità dell'applicazione utilizzando la dashboard di osservabilità.

Documenti di riferimento

• Documentazione ADC
• Documentazione di App Hub
• Monitoraggio delle applicazioni