La guida definitiva a Cloud Run, dalla demo di produzione da zero

1. Introduzione

Questo codelab ti illustra le nozioni di base per iniziare a utilizzare Cloud Run. Imparerai a utilizzare funzionalità aggiuntive, tra cui l'accesso VPC, Secret Manager e l'ADK per gli agenti di AI ospitati su Cloud Run.

Obiettivi didattici

  • Esegui il deployment di un'immagine nginx
  • Esegui il deployment dal codice sorgente
  • Eseguire il rollback di un deployment
  • Visualizzare l'anteprima di un deployment
  • Utilizzare lo strumento del server MCP per Developer Knowledge
  • Utilizzare Secret Manager con Cloud Run
  • Connettiti a un servizio Cloud Run interno all'interno di un VPC
  • Esegui il deployment di un agente ADK su Cloud Run

Che cosa ti serve

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

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

Imposta le variabili di ambiente

Questo codelab utilizza la seguente variabile di ambiente.

Per prima cosa, imposta la tua regione.

export REGION=<YOUR_REGION>

Successivamente, conferma PROJECT_ID e REGION.

echo "PROJECT_ID: $PROJECT_ID | REGION: $REGION"

2. Esegui il deployment dall'immagine

In questa sezione, eseguirai il deployment di un'immagine nginx standard direttamente da Docker Hub. Lo configurerai in modo che sia accessibile pubblicamente e imposterai la porta del container su 80.

  1. Esegui il deployment del servizio nginx:
   gcloud run deploy nginx-service \
     --image=nginx \
     --allow-unauthenticated \
     --port=80 \
     --region=$REGION
  1. Una volta completato il deployment, l'output del comando fornirà un URL del servizio. Apri l'URL nel browser per visualizzare la pagina "Welcome to nginx!".

3. Esegui il deployment dall'origine 

mkdir color-app && cd $_

Crea un file denominato requirements.txt con i seguenti contenuti:

Flask>=2.0.0
gunicorn>=20.0.0

Crea un file denominato main.py con i seguenti contenuti:

import os
from flask import Flask, render_template_string

app = Flask(__name__)

TEMPLATE = """
<!doctype html>
<html lang="en">
<head>
    <title>Cloud Run Traffic Revisions</title>
    <style>
        body {
            display: flex;
            justify-content: center;
            align-items: center;
            min-height: 50vh;
            background-color: darkseagreen;
            font-family: sans-serif;
        }
        .content {
            background-color: rgba(255, 255, 255, 0.8); /* Semi-transparent white background */
            padding: 2em;
            border-radius: 8px;
            text-align: center;
            box-shadow: 0 4px 8px rgba(0,0,0,0.1);
        }
    </style>
</head>
<body>
    <div class="content">
	  <!-- ROLLBACK DEMO: change this text to "gray" -->
        <p>background color: <strong>darkseagreen</strong></p>
    </div>
</body>
</html>
"""

@app.route('/')
def main():
    
    return render_template_string(TEMPLATE)

if __name__ == '__main__':
    port = int(os.environ.get('PORT', 8080))
    app.run(debug=True, host='0.0.0.0', port=port)

Ora esegui il comando seguente.

gcloud run deploy \
 --allow-unauthenticated
 --region $REGION

4. Rollback e link di anteprima

In questa sezione, introdurrai un bug e imparerai a eseguire il rollback a una revisione precedente mentre esamini la correzione.

  1. Innanzitutto, registra il nome della revisione che attualmente gestisce il traffico, in quanto non contiene il bug.
GOOD_REVISION=$(gcloud run revisions list --service color-app \
  --region $REGION --format 'value(REVISION)')
  1. All'interno del file main.py dell'app di colori, cerca "ROLLBACK DEMO" e aggiorna la riga nel seguente modo:
<p>background color: <strong>gray</strong></p>
  1. Ora esegui di nuovo gcloud run deploy. Nota come sono state utilizzate le configurazioni precedenti.

Ora che hai eseguito il deployment di un bug, puoi tornare alla sorgente, apportare una modifica o eseguire un comando git revert, quindi creare, attivare una nuova build e così via. Tuttavia, è possibile che si verifichi un errore durante la procedura.

Un modo più sicuro è eseguire un rollback.

  1. Per eseguire il rollback alla revisione precedente, esegui questo comando:
gcloud run services update-traffic color-app \
  --to-revisions=$GOOD_REVISION=100 \
  --region=$REGION

Ora puoi eseguire il deployment di una nuova revisione che non riceverà traffico.

  1. Ora correggi il bug modificando il testo e ripristinando darkseagreen
<p>background color: <strong>darkseagreen</strong></p>
  1. e distribuiscilo per verificare la correzione. Tieni presente che non riceverà traffico, perché il 100% del traffico è bloccato sulla revisione GOOD_REVISION
gcloud run deploy color-app --no-traffic --tag bugfix --region $REGION
  1. Verifica il deployment

Noterai che l'URL è leggermente diverso. Quando lo visiti, vedrai la correzione del bug in questo deployment.

  1. Invia il traffico all'ultima revisione.

Ora imposta di nuovo il traffico sull'ultima revisione.

gcloud run services update-traffic color-app \
  --to-latest \
  --region=$REGION

ed elimina il tag di revisione.

gcloud run services update-traffic color-app \
  --remove-tags=bugfix \
  --region=$REGION

Per saperne di più sui rollback, consulta la documentazione.

5. Server MCP per Developer Knowledge

Il server MCP di Developer Knowledge consente agli strumenti di sviluppo basati sull'AI di cercare nella documentazione ufficiale per sviluppatori di Google e recuperare informazioni per i prodotti Google come Firebase, Google Cloud, Android, Maps e altri ancora. Se colleghi la tua applicazione AI direttamente alla nostra libreria ufficiale di documentazione, il codice e le indicazioni che ricevi sono aggiornati e basati su un contesto autorevole.

Ti consigliamo di seguire le indicazioni per l'installazione per concedere all'agente AI l'accesso al server MCP per Developer Knowledge.

Una volta installato, puoi porre domande al tuo agente AI sulle funzionalità più recenti della documentazione che potrebbero essere diventate disponibili dopo la data limite di addestramento del modello.

Ad esempio, se consulti le note di rilascio di Cloud Run, vedrai che per il 24 febbraio 2026 è presente una voce relativa a "Esegui il deployment di un servizio Cloud Run multiregionale a disponibilità elevata con failover e failback automatici per il traffico esterno utilizzando il controllo dell'integrità del servizio Cloud Run (anteprima)".

Ora puoi chiedere al tuo agente AI "Dimmi di più su questa nuova funzionalità di Cloud Run per il failover automatico multiregionale".

6. Utilizzo di Secret Manager

Esistono tre modi per esporre i secret su Cloud Run:

  1. Come variabile di ambiente (bloccata alla versione estratta al momento del deployment).
  2. Montato come volume di file (aggiornato continuamente all'ultima versione).
  3. Utilizzo delle librerie client di Secret Manager nel codice.

In questa sezione, esporrai un secret come variabile di ambiente utilizzando un service account dedicato.

  1. Crea un nuovo secret denominato "my-secret":
gcloud secrets create my-secret --replication-policy="automatic"
  1. Aggiungi il valore del secret come nuova versione:
echo -n "my precious" | gcloud secrets versions add my-secret --data-file=-
  1. Crea un service account dedicato per l'app per i colori:
gcloud iam service-accounts create color-app-sa \
     --display-name="Color App Service Account"
  1. Concedi al service account dedicato l'accesso al secret.
   gcloud secrets add-iam-policy-binding my-secret \
     --member="serviceAccount:color-app-sa@${PROJECT_ID}.iam.gserviceaccount.com" \
     --role="roles/secretmanager.secretAccessor"
  1. Esegui di nuovo il deployment. Ora il servizio avrà accesso alla variabile di ambiente MY_SECRET:
gcloud run deploy color-app \
     --source . \
     --update-secrets=MY_SECRET=my-secret:latest \
     --service-account=color-app-sa@${PROJECT_ID}.iam.gserviceaccount.com \
     --region=$REGION

7. Connettiti a un VPC

In questa sezione configurerai la seguente architettura:

  • backend privato non accessibile da internet pubblico
  • un frontend pubblico che comunica con il backend tramite l'uscita VPC diretta

Questo esempio utilizzerà la rete e la subnet predefinite.

Prerequisito:assicurati che l'accesso privato Google sia abilitato nella subnet in modo che il VPC possa instradare le richieste interne ai servizi Cloud Run.

   gcloud compute networks subnets update default \
     --region=$REGION \
     --enable-private-ip-google-access
  1. Crea una cartella per questa sezione
mkdir ../vpc-demo
cd ../vpc-demo
  1. crea il servizio di backend privato
mkdir backend
touch backend/app.js
touch backend/package.json

Nel file backend/app.js, aggiungi quanto segue:

const http = require('http');

const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('Hello World from the Private Backend!');
});

const port = process.env.PORT || 8080;
server.listen(port, () => {
  console.log(`Private backend listening on port ${port}`);
});

Nel file backend/package.json, aggiungi quanto segue:

{
    "name": "backend",
    "scripts": {
        "start": "node app.js"
    }
}
  1. Esegui il deployment del backend privato con traffico in entrata solo interno:
   gcloud run deploy private-backend \
     --source ./backend \
     --region $REGION \
     --ingress internal \
     --no-allow-unauthenticated
  1. Registra l'URL di backend. Fornirai questo URL all'app di frontend in un secondo momento.
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projec
tNumber)')

export BACKEND_URL="https://private-backend-${PROJECT_NUMBER}.${REGION}.run.app"
  1. Crea l'app frontend
mkdir frontend
touch frontend/app.js
touch frontend/package.json

Nel file frontend/app.js, aggiungi quanto segue:

const http = require('http');

const server = http.createServer(async (req, res) => {
  const backendUrl = process.env.BACKEND_URL;
  
  if (!backendUrl) {
    res.writeHead(500, { 'Content-Type': 'text/plain' });
    return res.end('Error: BACKEND_URL environment variable is missing.');
  }

  try {
    // Fetch the OIDC token from the Metadata server
    const tokenResponse = await fetch(`http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=${backendUrl}`, {
      headers: { 'Metadata-Flavor': 'Google' }
    });

    if (!tokenResponse.ok) {
      throw new Error(`Failed to fetch identity token: ${tokenResponse.statusText}`);
    }
    const token = await tokenResponse.text();

    // Ping the backend with the token
    const response = await fetch(backendUrl, {
      headers: { 'Authorization': `Bearer ${token}` }
    });
    const text = await response.text();

    res.writeHead(200, { 'Content-Type': 'text/plain' });
    res.end(`Frontend successfully routed through VPC. Backend says: "${text}"`);
  } catch (error) {
    res.writeHead(500, { 'Content-Type': 'text/plain' });
    res.end(`Frontend failed to reach the backend. Error: ${error.message}`);
  }
});

const port = process.env.PORT || 8080;
server.listen(port, () => {
  console.log(`Public frontend listening on port ${port}`);
});
  1. Nel file frontend/package.json, aggiungi quanto segue:
{
    "name": "backend",
    "scripts": {
        "start": "node app.js"
    }
}
  1. Crea un service account dedicato per il servizio frontend:
  gcloud iam service-accounts create frontend-sa \
     --display-name="Frontend Service Account"
  1. Concedi il ruolo Cloud Run Invoker
PROJECT_ID=$(gcloud config get project)
  
gcloud projects add-iam-policy-binding $PROJECT_ID \
     --member="serviceAccount:frontend-sa@${PROJECT_ID}.iam.gserviceaccount.com" \
     --role="roles/run.invoker"
  1. Ora esegui il deployment del frontend pubblico utilizzando l'uscita VPC diretto. Impostiamo "–vpc-egress=all-traffic" per forzare la richiesta in uscita nel VPC:
   gcloud run deploy public-frontend \
     --source ./frontend \
     --region $REGION \
     --allow-unauthenticated \
     --network default \
     --subnet default \
     --vpc-egress all-traffic \
    --service-account=frontend-sa@${PROJECT_ID}.iam.gserviceaccount.com \
     --set-env-vars BACKEND_URL=$BACKEND_URL
  1. Verificare i servizi
  • Testa il frontend:esegui il comando curl sull'URL frontend pubblico. Dovrebbe comunicare correttamente con il backend e restituire una risposta.
     FRONTEND_URL=$(gcloud run services describe public-frontend --region $REGION --format='value(status.url)')
     curl $FRONTEND_URL
  • Testa il backend (diretto): prova a eseguire curl dell'URL del backend direttamente dalla tua macchina locale (internet pubblico). Dovrebbe restituire un errore 404 perché l'ingresso è limitato a "internal" ed è richiesta l'autenticazione.
  curl $BACKEND_URL

8. Esegui il deployment di un agente ADK

In questa sezione vedrai come il buildpack Python supporta il rilevamento del punto di ingresso predefinito per Agent Development Kit (ADK).

Verrà creata la seguente struttura di cartelle:

adk-demo
 - my_agent
   - __init.py__
   - agent.py
 - requirements.txt
  1. Crea la struttura delle cartelle
mkdir ../adk-demo
cd ../adk-demo
mkdir my_agent
touch my_agent/__init.py__
touch my_agent/agent.py
touch requirements.txt
  1. Aggiungi i contenuti seguenti al file my_agent/__init.py__:
from . import agent
  1. Aggiungi i contenuti seguenti al file my_agent/agent.py:
from google.adk import Agent

root_agent = Agent(
    name="demo_agent",
    model="gemini-3-flash-preview",
    instruction="You are a helpful assistant for a Cloud Run demo."
)
  1. Aggiungi i contenuti seguenti al file requirements.txt:
google-adk
  1. Crea un service account dedicato per l'agente:
  gcloud iam service-accounts create agent-sa \
     --display-name="Agent Service Account"
  1. Concedi al service account il ruolo Utente Vertex AI:
PROJECT_ID=$(gcloud config get-value project)
  
gcloud projects add-iam-policy-binding $PROJECT_ID \
     --member="serviceAccount:agent-sa@${PROJECT_ID}.iam.gserviceaccount.com" \
     --role="roles/aiplatform.user"
  1. Esegui il deployment dell'agente ADK

Devi eseguire il deployment in una regione in cui è accessibile l'API Gemini. In questo esempio, è us-west1.

gcloud run deploy my-adk-agent-demo \
   --source . \
   --region us-west1 \
   --allow-unauthenticated \
   --service-account=agent-sa@${PROJECT_ID}.iam.gserviceaccount.com \
   --set-env-vars="GOOGLE_GENAI_USE_VERTEXAI=TRUE,GOOGLE_CLOUD_PROJECT=$PROJECT_ID,GOOGLE_CLOUD_LOCATION=global"
  1. Esegui curl dell'endpoint

Puoi vedere come l'agente è immediatamente disponibile come API pronta per la produzione.

Registra l'URL del servizio Cloud Run in una variabile di ambiente.

AGENT_URL=$(gcloud run services describe my-adk-agent-demo \
  --region us-west1 \
  --format 'value(status.url)')

Crea una sessione con l'agente

curl -X POST $AGENT_URL/apps/my_agent/users/u_123/sessions/s_123 -H "Content-Type: application/json" -d '{"key1": "value1", "key2": 42}'

Chiedi che cos'è Cloud Run e filtra la risposta in modo da mostrare solo ciò che dice l'agente

curl -X POST $AGENT_URL/run \
-H "Content-Type: application/json" \
-d "{
   \"appName\": \"my_agent\",
   \"userId\": \"u_123\",
   \"sessionId\": \"s_123\",
   \"newMessage\": { 
        \"role\": \"user\", 
        \"parts\": [{ \"text\": \"What is Cloud Run?\" 
    }]}
}" | python3 -c "import sys, json; print(json.load(sys.stdin)[-1]['content']['parts'][0]['text'])"

e dovresti visualizzare un risultato simile al seguente:

Hello! I am **demo_agent**, and I'm here to help you with your Cloud Run demo. **Cloud Run** is a fully managed compute platform by Google Cloud that allows you to run **containerized applications** in a serverless environment...

9. Esegui la pulizia

Per evitare addebiti continui al tuo account Google Cloud, puoi eliminare l'intero progetto (mostrato di seguito) o le singole risorse create durante questo codelab.

Elimina i servizi nginx, color-app, private-backend e public-frontend

gcloud run services delete nginx-service --region $REGION --quiet
gcloud run services delete color-app --region $REGION --quiet
gcloud run services delete private-backend --region $REGION --quiet
gcloud run services delete public-frontend --region $REGION --quiet

Elimina l'agente ADK (nota: è stato eseguito il deployment in us-west1 per questo esempio)

gcloud run services delete my-adk-agent-demo --region us-west1 --quiet

Rimuovi il secret archiviato in Secret Manager:

gcloud secrets delete my-secret --quiet

Elimina il service account dell'app Color

gcloud iam service-accounts delete color-app-sa@${PROJECT_ID}.iam.gserviceaccount.com --quiet

Elimina il service account dell'agente ADK

gcloud iam service-accounts delete agent-sa@${PROJECT_ID}.iam.gserviceaccount.com --quiet

(Facoltativo) Elimina il progetto

Se hai creato un nuovo progetto appositamente per questo codelab, puoi eliminarlo per assicurarti che tutte le risorse vengano rimosse contemporaneamente:

# run only if you want to delete the entire project
gcloud projects delete $PROJECT_ID

10. Complimenti!

Hai completato il codelab. Hai esaminato le nozioni di base per iniziare a utilizzare Cloud Run.

Che cosa hai imparato

  • Esegui il deployment di un'immagine nginx
  • Esegui il deployment dal codice sorgente
  • Eseguire il rollback di un deployment
  • Visualizzare l'anteprima di un deployment
  • Utilizzare lo strumento del server MCP per Developer Knowledge
  • Utilizzare Secret Manager con Cloud Run
  • Connettiti a un servizio Cloud Run interno all'interno di un VPC
  • Esegui il deployment di un agente ADK su Cloud Run