Come eseguire il deployment di un sito web Generative UI su Cloud Run

1. Introduzione

Panoramica

In questo lab creerai e implementerai un sito web il cui contenuto viene generato al volo dai modelli linguistici di grandi dimensioni Gemini di Google. Il sito web sarà un semplice navigatore in stile "Scegli la tua avventura" per esplorare gli argomenti, in cui ogni clic genera una nuova pagina con nuovi link in base alla tua selezione. Lo creerai con Node.js e Fastify, utilizzerai l'SDK Vertex AI per chiamare Gemini, lo eseguirai il deployment come servizio sicuro e pronto per la produzione su Cloud Run e lo proteggerai utilizzando Identity-Aware Proxy (IAP).

Attività previste

  • Crea un'applicazione Node.js Fastify che utilizza Vertex AI.
  • Esegui il deployment dell'applicazione in Cloud Run dal codice sorgente senza un Dockerfile.
  • Proteggi l'endpoint Cloud Run utilizzando Identity-Aware Proxy (IAP).

Obiettivi didattici

  • Come utilizzare l'SDK Vertex AI per Node.js per generare contenuti.
  • Come eseguire il deployment di un'applicazione Node.js in Cloud Run.
  • Come proteggere un'applicazione Cloud Run con IAP.

2. Configurazione del progetto

  1. Se non hai ancora un Account Google, devi crearne uno.
    • Utilizza un account personale anziché un account di lavoro o della scuola. Gli account di lavoro e della scuola potrebbero avere limitazioni che impediscono l'attivazione delle API necessarie per questo lab.
  2. Accedi a Google Cloud Console.
  3. Abilita la fatturazione nella console Cloud.
    • Il completamento di questo lab dovrebbe costare meno di 1 $in risorse cloud.
    • Per evitare ulteriori addebiti, puoi seguire i passaggi alla fine di questo lab per eliminare le risorse.
    • I nuovi utenti hanno diritto alla prova senza costi di 300$.
  4. Crea un nuovo progetto o scegli di riutilizzarne uno esistente.
    • Se visualizzi un errore relativo alla quota del progetto, riutilizza un progetto esistente o eliminalo per crearne uno nuovo.

3. Apri editor di Cloud Shell

  1. Fai clic su questo link per andare direttamente all'editor di Cloud Shell.
  2. Se ti viene richiesto di concedere l'autorizzazione in qualsiasi momento della giornata, fai clic su Autorizza per continuare. Fai clic per autorizzare Cloud Shell
  3. Se il terminale non viene visualizzato nella parte inferiore dello schermo, aprilo:
    • Fai clic su Visualizza.
    • Fai clic su TerminaleApri un nuovo terminale nell'editor di Cloud Shell.
  4. Nel terminale, imposta il tuo progetto con questo comando:
    • Formato:
      gcloud config set project [PROJECT_ID]
    • Esempio:
      gcloud config set project lab-project-id-example
    • Se non ricordi l'ID progetto:
      • Puoi elencare tutti gli ID progetto con:
        gcloud projects list | awk '/PROJECT_ID/{print $2}'
      Imposta l'ID progetto nel terminale dell'editor di Cloud Shell
  5. Dovresti visualizzare questo messaggio:
    Updated property [core/project].
    Se visualizzi un WARNING e ti viene chiesto Do you want to continue (Y/n)?, probabilmente hai inserito l'ID progetto in modo errato. Premi n, premi Enter e prova a eseguire di nuovo il comando gcloud config set project.
  1. Imposta la variabile di ambiente GOOGLE_CLOUD_PROJECT 
    export GOOGLE_CLOUD_PROJECT=$(gcloud config get-value project)

4. Abilita API

Nel terminale, abilita le API:

gcloud services enable \
  run.googleapis.com \
  aiplatform.googleapis.com \
  cloudresourcemanager.googleapis.com \
  iap.googleapis.com

Se ti viene richiesto di concedere l'autorizzazione, fai clic su Autorizza per continuare. Fai clic per autorizzare Cloud Shell

Il completamento di questo comando potrebbe richiedere alcuni minuti, ma alla fine dovrebbe essere visualizzato un messaggio di operazione riuscita simile a questo:

Operation "operations/acf.p2-73d90d00-47ee-447a-b600" finished successfully.

5. Prepara il progetto Node.js

  1. Crea una cartella denominata gen-ui-on-cloudrun per archiviare il codice sorgente per il deployment:
    mkdir gen-ui-on-cloudrun && cd gen-ui-on-cloudrun
  2. Inizializza un progetto Node.js:
    npm init -y
  3. Configura il progetto in modo che utilizzi i moduli ES e definisci uno script di avvio eseguendo questi comandi:
    npm pkg set type="module"
  4. Installa fastify per il server web e @google/genai per l'SDK Vertex AI:
    npm install fastify @google/genai

6. Crea il codice dell'applicazione

  1. Crea e apri un nuovo file index.ts per il codice sorgente dell'applicazione:
    cloudshell edit ~/gen-ui-on-cloudrun/index.ts
    Il comando cloudshell edit aprirà il file index.ts nell'editor sopra il terminale.
  2. Aggiungi il seguente codice sorgente del server dell'interfaccia utente generativa al file index.ts:
    import fastifyLib from 'fastify';
import { GoogleGenAI } from '@google/genai';

const fastify = fastifyLib({ logger: true });

const ai = new GoogleGenAI({
    vertexai: true,
    project: process.env.GOOGLE_CLOUD_PROJECT,
    location: process.env.GOOGLE_CLOUD_LOCATION || 'europe-west1',
});

const SYSTEM_INSTRUCTION = `The user should have submitted an html page and the id of the element just clicked.
Given the next page description, create a new webpage with a link back to "Start Over" (the / route), a brief overview of the topic, and a list of clickable link elements related to the page.
When an element is clicked, the webpage should link to the base route / with the nextPageDescription as a query string parameter.
All information needed to generate the next page should be included in the nextPageDescription without additional context.
Each nextPageDescription should be less than 1500 characters.

Example:
If the current HTML page is for a small pet store, it might include a link to an "About" page.
The href for the about page link should be /?nextPageDescription=about%20page%20for%20small%20pet%20store%20website

All responses should be valid HTML without markdown backticks.`;

interface QueryParams {
    nextPageDescription?: string;
}

fastify.get<{ Querystring: QueryParams }>('/', async (request, reply) => {
    const {
        nextPageDescription = 'A web page with interesting fun facts where I can select a fact to learn more about that topic.'
    } = request.query;

    try {
        const response = await ai.models.generateContent({
            model: 'gemini-2.5-flash',
            contents: nextPageDescription,
            config: {
                systemInstruction: SYSTEM_INSTRUCTION,
                temperature: 0.9,
            }
        });

        reply.type('text/html; charset=utf-8').send(response.text);
    } catch (error: any) {
        request.log.error(error);
        reply.status(500).send('An error occurred calling the AI.');
    }
});

const start = async () => {
    try {
        await fastify.listen({ port: Number(process.env.PORT) || 8080, host: '0.0.0.0' });
    } catch (err) {
        fastify.log.error(err);
        process.exit(1);
    }
};

start();

Questo codice configura un server web che è in attesa di richieste HTTP GET nel percorso principale (/). Quando viene ricevuta una richiesta, utilizza il parametro di query nextPageDescription (o un valore predefinito) come prompt per il modello Gemini 2.5 Flash tramite Vertex AI. Il modello riceve l'istruzione SYSTEM_INSTRUCTION di restituire una pagina HTML contenente link, in cui ogni link include un nextPageDescription per generare la pagina successiva.

7. Crea service account

Per autenticarsi con l'API Vertex AI, devi disporre di un service account per il tuo servizio Cloud Run.

  1. Crea un account di servizio denominato gen-navigator-sa:
    gcloud iam service-accounts create gen-navigator-sa --display-name="Generative Navigator Service Account"
  2. Concedi al service account l'autorizzazione per utilizzare Vertex AI:
    gcloud projects add-iam-policy-binding $GOOGLE_CLOUD_PROJECT \
    --member="serviceAccount:gen-navigator-sa@$GOOGLE_CLOUD_PROJECT.iam.gserviceaccount.com" \
    --role="roles/aiplatform.user"

8. Esegui il deployment in Cloud Run

Ora esegui il deployment dell'applicazione su Cloud Run direttamente dal codice sorgente, senza bisogno di un Dockerfile.

  1. Esegui il comando gcloud per eseguire il deployment dell'applicazione:
    cd ~/gen-ui-on-cloudrun
gcloud beta run deploy generative-web-navigator \
    --source . \
    --no-build \
    --base-image=nodejs24 \
    --command="node" \
    --args="index.ts" \
    --region=europe-west1 \
    --no-allow-unauthenticated \
    --iap \
    --service-account="gen-navigator-sa@$GOOGLE_CLOUD_PROJECT.iam.gserviceaccount.com" \
    --set-env-vars GOOGLE_CLOUD_PROJECT="$GOOGLE_CLOUD_PROJECT",GOOGLE_CLOUD_LOCATION="europe-west1"
    Qui utilizziamo alcuni flag importanti:
    • --source . --no-build --base-image=nodejs24: indica a Cloud Run di eseguire il deployment del codice sorgente dalla directory corrente, ignorare la fase di build ed eseguire l'applicazione utilizzando un'immagine di base Node.js 24 predefinita.
    • --no-allow-unauthenticated: In questo modo, solo gli utenti autenticati possono accedere al servizio.
    • --iap: in questo modo Identity-Aware Proxy (IAP) può gestire l'accesso alla tua applicazione. IAP ti consente di controllare l'accesso in base all'identità e al contesto dell'utente, anziché solo agli indirizzi IP.
  2. Dopo alcuni minuti, vedrai un messaggio simile a questo:
    Service [generative-web-navigator] revision [generative-web-navigator-12345-abc] has been deployed and is serving 100 percent of traffic.

Hai eseguito il deployment dell'applicazione, ma devi ancora configurare IAP per consentire l'accesso.

9. Configura l'accesso IAP

Quando abiliti IAP su Cloud Run, IAP intercetta tutte le richieste e richiede agli utenti di autenticarsi e di essere autorizzati prima di poter raggiungere il tuo servizio. Affinché questa operazione funzioni, devi concedere due autorizzazioni:

  • Consenti al servizio IAP stesso di richiamare il servizio Cloud Run.
  • Consenti a te (o ad altri utenti/gruppi) di accedere all'applicazione tramite IAP.
  1. Recupera il numero del progetto, necessario per identificare il service agent IAP:
    export PROJECT_NUMBER=$(gcloud projects describe $GOOGLE_CLOUD_PROJECT --format="value(projectNumber)")
  2. Concedi all'agente di servizio IAP il ruolo roles/run.invoker sul tuo servizio Cloud Run. Ciò consente a IAP di richiamare il servizio dopo aver autenticato e autorizzato un utente.
    gcloud run services add-iam-policy-binding generative-web-navigator \
    --region=europe-west1 \
    --member="serviceAccount:service-$PROJECT_NUMBER@gcp-sa-iap.iam.gserviceaccount.com" \
    --role="roles/run.invoker"
  3. Concedi al tuo account utente il ruolo roles/iap.httpsResourceAccessor. In questo modo puoi accedere alle risorse HTTPS protette da IAP.
    gcloud beta iap web add-iam-policy-binding \
    --resource-type=cloud-run \
    --region=europe-west1 \
    --service=generative-web-navigator \
    --member="user:$(gcloud config get-value account)" \
    --role="roles/iap.httpsResourceAccessor"

10. testa l'applicazione

  1. Ottieni l'URL del servizio di cui hai eseguito il deployment: 
    gcloud run services describe generative-web-navigator --format='value(status.url)' --region=europe-west1
  2. Copia l'URL e aprilo nel browser web. Poiché il servizio è protetto con IAP, ti verrà chiesto di accedere con il tuo Account Google se non hai già eseguito l'accesso. Dopo l'autenticazione, dovresti visualizzare la prima pagina generata automaticamente.
  3. Fai clic su un link per passare a una nuova pagina, che verrà generata dall'AI in base al link su cui hai fatto clic.

Ce l'hai fatta. Hai eseguito correttamente il deployment di un sito web con UI generativa in Cloud Run e lo hai protetto utilizzando IAP.

11. Conclusione

Complimenti! Hai eseguito il deployment e protetto correttamente un sito web con UI generativa utilizzando Cloud Run, Vertex AI e IAP.

(Facoltativo) Pulizia

Se vuoi eseguire la pulizia di ciò che hai creato, puoi eliminare il progetto Cloud per evitare addebiti aggiuntivi.

Sebbene non siano previsti addebiti per Cloud Run quando il servizio non è in uso, ti potrebbero comunque essere addebitati i costi di archiviazione degli artefatti di build, se ne sono stati creati. L'eliminazione del progetto Cloud interrompe la fatturazione per tutte le risorse utilizzate al suo interno.

Se vuoi, elimina il progetto:

gcloud projects delete $GOOGLE_CLOUD_PROJECT

Potresti anche voler eliminare le risorse non necessarie dal disco Cloud Shell. Puoi:

  1. Elimina la directory del progetto codelab: 
    rm -rf ~/gen-ui-on-cloudrun
  2. Attenzione. La prossima azione non può essere annullata. Se vuoi eliminare tutti i contenuti di Cloud Shell per liberare spazio, puoi eliminare l'intera home directory. Fai attenzione che tutto ciò che vuoi conservare sia salvato altrove. 
    sudo rm -rf $HOME