Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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

1. Introduzione

Panoramica

In questo lab creerai ed eseguirai il deployment di 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).

In questo lab proverai a:

Creare un'applicazione Node.js Fastify che utilizza Vertex AI.
Eseguire il deployment dell'applicazione in Cloud Run dal codice sorgente senza un Dockerfile.
Proteggere 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

Se non hai già 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 di abilitare le API necessarie per questo lab.
Accedi a Google Cloud Console.
Abilita la fatturazione nella console Cloud.
- Il completamento di questo lab dovrebbe costare meno di 1 $in risorse cloud.
- Puoi seguire i passaggi alla fine di questo lab per eliminare le risorse ed evitare ulteriori addebiti.
- I nuovi utenti hanno diritto alla prova senza costi di 300$.
Crea un nuovo progetto o scegli di riutilizzare un progetto esistente.
- Se visualizzi un errore relativo alla quota del progetto, riutilizza un progetto esistente o elimina un progetto esistente per crearne uno nuovo.

3. Apri editor di Cloud Shell

Fai clic su questo link per passare direttamente all'editor di Cloud Shell
Se ti viene chiesto di autorizzare in qualsiasi momento, fai clic su Autorizza per continuare.
Se il terminale non viene visualizzato nella parte inferiore dello schermo, aprilo:
- Fai clic su Visualizza
- Fai clic su Terminale

Nel terminale, imposta il 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}'
```

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.

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 chiesto di autorizzare, 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 generare un messaggio di successo simile a questo:

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

5. Prepara il progetto Node.js

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
```
Inizializza un progetto Node.js:
```
npm init -y
```
Configura il progetto in modo che utilizzi i moduli ES e definisci uno script di avvio eseguendo questi comandi:
```
npm pkg set type="module"
```
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

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.

Aggiungi il seguente codice sorgente del server dell'interfaccia utente generativa nel 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-west4',
});

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 ascolta le richieste HTTP GET sul 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, il servizio Cloud Run deve disporre di un service account.

Crea un service account denominato gen-navigator-sa:

gcloud iam service-accounts create gen-navigator-sa --display-name="Generative Navigator Service Account"

Concedi al service account l'autorizzazione a 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 in Cloud Run direttamente dal codice sorgente, senza bisogno di un Dockerfile.

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-west4 \
    --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-west4"
```
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, di saltare la fase di build ed eseguire l'applicazione utilizzando un'immagine di base Node.js 24 predefinita.
- --no-allow-unauthenticated: garantisce che solo gli utenti autenticati possano accedere al servizio.
- --iap: abilita Identity-Aware Proxy (IAP) per gestire l'accesso all'applicazione. IAP consente di controllare l'accesso in base all'identità e al contesto dell'utente, anziché solo agli indirizzi IP.

Dopo alcuni minuti, visualizzerai un messaggio simile a:

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 comunque 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é funzioni, devi concedere due autorizzazioni:

Consenti al servizio IAP stesso di richiamare il tuo servizio Cloud Run.
Consenti a te stesso (o ad altri utenti/gruppi) di accedere all'applicazione tramite IAP.

Recupera il numero di progetto, necessario per identificare l'agente di servizio IAP:

export PROJECT_NUMBER=$(gcloud projects describe $GOOGLE_CLOUD_PROJECT --format="value(projectNumber)")

Concedi all'agente di servizio IAP il ruolo roles/run.invoker sul tuo servizio Cloud Run. In questo modo, IAP può richiamare il tuo servizio dopo aver autenticato e autorizzato un utente.

gcloud run services add-iam-policy-binding generative-web-navigator \
    --region=europe-west4 \
    --member="serviceAccount:service-$PROJECT_NUMBER@gcp-sa-iap.iam.gserviceaccount.com" \
    --role="roles/run.invoker"

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-west4 \
    --service=generative-web-navigator \
    --member="user:$(gcloud config get-value account)" \
    --role="roles/iap.httpsResourceAccessor"

10. testa l'applicazione

Recupera l'URL del servizio di cui hai eseguito il deployment:

gcloud run services describe generative-web-navigator --format='value(status.url)' --region=europe-west4

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.
Fai clic su un link qualsiasi 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 interfaccia utente generativa in Cloud Run e lo hai protetto utilizzando IAP.

11. Conclusione

Complimenti. Hai eseguito correttamente il deployment e la protezione di un sito web con interfaccia utente generativa utilizzando Cloud Run, Vertex AI e IAP.

(Facoltativo) Libera spazio

Se vuoi liberare spazio da 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 all'interno del progetto.

Se vuoi, elimina il progetto:

gcloud projects delete $GOOGLE_CLOUD_PROJECT

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

Eliminare la directory del progetto del codelab:
```
rm -rf ~/gen-ui-on-cloudrun
```
Attenzione. Questa azione successiva non può essere annullata. Se vuoi eliminare tutto ciò che è presente in Cloud Shell per liberare spazio, puoi eliminare l'intera home directory. Assicurati che tutto ciò che vuoi conservare sia salvato altrove.
```
sudo rm -rf $HOME
```