Guide ultime de Cloud Run : démonstration de A à Z pour la production

1. Introduction

Cet atelier de programmation vous présente les bases de Cloud Run. Vous apprendrez à utiliser des fonctionnalités supplémentaires, y compris l'accès au VPC, Secret Manager et l'ADK pour les agents d'IA hébergés sur Cloud Run.

Points abordés

  • Déployer une image nginx
  • Déployer à partir de votre code source
  • Effectuer le rollback d'un déploiement
  • Prévisualiser un déploiement
  • Utiliser l'outil de serveur MCP Developer Knowledge
  • Utiliser Secret Manager avec Cloud Run
  • Se connecter à un service Cloud Run interne dans un VPC
  • Déployer un agent ADK sur Cloud Run

Prérequis

  • Un navigateur Web (par exemple, Chrome)
  • Un projet Google Cloud avec facturation activée

Créer un projet Google Cloud

  1. Dans la console Google Cloud, sur la page de sélection du projet, sélectionnez ou créez un projet Google Cloud.
  2. Assurez-vous que la facturation est activée pour votre projet Cloud. Découvrez comment vérifier si la facturation est activée sur un projet.

Démarrer Cloud Shell

Cloud Shell est un environnement de ligne de commande exécuté dans Google Cloud et fourni avec les outils nécessaires.

  1. Cliquez sur Activer Cloud Shell en haut de la console Google Cloud.
  2. Une fois connecté à Cloud Shell, vérifiez votre authentification :
    gcloud auth list
  3. Vérifiez que votre projet est configuré :
    gcloud config get project
  4. Si votre projet n'est pas défini comme prévu, définissez-le :
    export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

Définir des variables d'environnement

Cet atelier de programmation utilise la variable d'environnement suivante.

Commencez par définir votre région.

export REGION=<YOUR_REGION>

Ensuite, confirmez votre PROJECT_ID et votre REGION.

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

2. Déployer à partir d'une image

Dans cette section, vous allez déployer une image nginx standard directement à partir de Docker Hub. Vous allez le configurer pour qu'il soit accessible publiquement et définir le port du conteneur sur 80.

  1. Déployez le service nginx :
   gcloud run deploy nginx-service \
     --image=nginx \
     --allow-unauthenticated \
     --port=80 \
     --region=$REGION
  1. Une fois le déploiement terminé, le résultat de la commande fournit une URL de service. Ouvrez cette URL dans votre navigateur pour afficher la page "Welcome to nginx!" (Bienvenue dans nginx !).

3. Déployer une fonction à partir d'une source 

mkdir color-app && cd $_

Créez un fichier nommé requirements.txt avec le contenu suivant :

Flask>=2.0.0
gunicorn>=20.0.0

Créez un fichier nommé main.py avec le contenu suivant :

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)

Exécutez maintenant la commande suivante :

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

4. Restauration et liens d'aperçu

Dans cette section, vous allez introduire un bug et apprendre à revenir à une révision précédente pendant que vous recherchez la correction.

  1. Commencez par enregistrer le nom de la révision qui diffuse actuellement du trafic, car elle ne contient pas le bug.
GOOD_REVISION=$(gcloud run revisions list --service color-app \
  --region $REGION --format 'value(REVISION)')
  1. Dans le fichier main.py de l'application de couleurs, recherchez "ROLLBACK DEMO" et remplacez la ligne par ce qui suit :
<p>background color: <strong>gray</strong></p>
  1. Exécutez à nouveau gcloud run deploy. Notez comment vos configurations précédentes ont été utilisées.

Maintenant que vous avez déployé un bug, vous pouvez revenir à votre source, apporter une modification ou effectuer une restauration Git, puis compiler, déclencher une nouvelle compilation, etc. Toutefois, il est possible que vous introduisiez une erreur en cours de route.

Une façon plus sûre de procéder est de revenir en arrière.

  1. Pour revenir à la révision précédente, exécutez la commande suivante :
gcloud run services update-traffic color-app \
  --to-revisions=$GOOD_REVISION=100 \
  --region=$REGION

Vous pouvez désormais déployer une nouvelle révision qui ne recevra aucun trafic.

  1. Corrigez maintenant le bug en remplaçant le texte par darkseagreen.
<p>background color: <strong>darkseagreen</strong></p>
  1. Déployez-le pour vérifier la correction. Notez qu'elle ne recevra aucun trafic, car 100 % du trafic est épinglé à GOOD_REVISION.
gcloud run deploy color-app --no-traffic --tag bugfix --region $REGION
  1. Vérifier le déploiement

Vous remarquerez que l'URL est légèrement différente. Lorsque vous y accéderez, vous verrez votre correction de bug dans ce déploiement.

  1. Renvoyez le trafic vers la dernière révision.

Vous allez maintenant rediriger le trafic vers la dernière révision.

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

et supprimez le tag de révision.

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

Pour en savoir plus sur les rollbacks, consultez la documentation.

5. Serveur MCP Developer Knowledge

Le serveur MCP Developer Knowledge permet aux outils de développement optimisés par l'IA de rechercher dans la documentation officielle pour les développeurs de Google et de récupérer des informations sur les produits Google tels que Firebase, Google Cloud, Android, Maps et plus encore. En connectant votre application d'IA directement à notre bibliothèque officielle de documentation, vous vous assurez que le code et les conseils que vous recevez sont à jour et basés sur un contexte faisant autorité.

Suivez les instructions d'installation pour accorder à votre agent d'IA l'accès au serveur MCP Developer Knowledge.

Une fois installé, vous pouvez poser des questions à votre agent d'IA sur les dernières fonctionnalités de la documentation qui ont pu être disponibles après la date limite d'entraînement de votre modèle.

Par exemple, si vous consultez les notes de version de Cloud Run, vous verrez qu'à la date du 24 février 2026, une entrée concerne le "Déploiement d'un service Cloud Run multirégional à haute disponibilité avec basculement et reprise automatisés pour le trafic externe à l'aide de l'état du service Cloud Run (aperçu)".

Vous pouvez désormais demander à votre agent d'IA "parle-moi de cette nouvelle fonctionnalité Cloud Run pour le basculement automatisé multirégional".

6. Utiliser Secret Manager

Il existe trois façons d'exposer des secrets sur Cloud Run :

  1. En tant que variable d'environnement (verrouillée sur la version extraite au moment du déploiement).
  2. Installé en tant que volume de fichier (mis à jour en continu vers la dernière version).
  3. Utiliser les bibliothèques clientes Secret Manager dans votre code.

Dans cette section, vous allez exposer un secret en tant que variable d'environnement à l'aide d'un compte de service dédié.

  1. Créez un secret nommé "my-secret" :
gcloud secrets create my-secret --replication-policy="automatic"
  1. Ajoutez la valeur du secret en tant que nouvelle version :
echo -n "my precious" | gcloud secrets versions add my-secret --data-file=-
  1. Créez un compte de service dédié pour l'application de couleurs :
gcloud iam service-accounts create color-app-sa \
     --display-name="Color App Service Account"
  1. Accordez au compte de service dédié l'accès au secret.
   gcloud secrets add-iam-policy-binding my-secret \
     --member="serviceAccount:color-app-sa@${PROJECT_ID}.iam.gserviceaccount.com" \
     --role="roles/secretmanager.secretAccessor"
  1. Redéployez. Le service aura désormais accès à la variable d'environnement 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. Se connecter à un VPC

Dans cette section, vous allez configurer l'architecture suivante :

  • un backend privé qui n'est pas accessible depuis l'Internet public.
  • un frontend public qui communique avec le backend via la sortie VPC directe.

Cet exemple utilisera le réseau et le sous-réseau par défaut.

Prérequis : Assurez-vous que l'accès privé à Google est activé sur votre sous-réseau afin que le VPC puisse acheminer les requêtes internes vers les services Cloud Run.

   gcloud compute networks subnets update default \
     --region=$REGION \
     --enable-private-ip-google-access
  1. Créer un dossier pour cette section
mkdir ../vpc-demo
cd ../vpc-demo
  1. créer le service de backend privé ;
mkdir backend
touch backend/app.js
touch backend/package.json

Dans le fichier backend/app.js, ajoutez les éléments suivants :

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}`);
});

Dans le fichier backend/package.json, ajoutez les éléments suivants :

{
    "name": "backend",
    "scripts": {
        "start": "node app.js"
    }
}
  1. Déployez le backend privé avec une entrée interne uniquement :
   gcloud run deploy private-backend \
     --source ./backend \
     --region $REGION \
     --ingress internal \
     --no-allow-unauthenticated
  1. Enregistrez l'URL du backend. Vous fournirez cette URL à l'application frontend ultérieurement.
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projec
tNumber)')

export BACKEND_URL="https://private-backend-${PROJECT_NUMBER}.${REGION}.run.app"
  1. Créer l'application d'interface
mkdir frontend
touch frontend/app.js
touch frontend/package.json

Dans le fichier frontend/app.js, ajoutez les éléments suivants :

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. Dans le fichier frontend/package.json, ajoutez les éléments suivants :
{
    "name": "backend",
    "scripts": {
        "start": "node app.js"
    }
}
  1. Créez un compte de service dédié pour le service d'interface :
  gcloud iam service-accounts create frontend-sa \
     --display-name="Frontend Service Account"
  1. Attribuez-lui le rôle Demandeur Cloud Run.
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. Déployez maintenant le frontend public à l'aide de la sortie VPC directe. Nous définissons "–vpc-egress=all-traffic" pour forcer la requête sortante dans le 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. Vérifier les services
  • Tester l'interface : exécutez une requête cURL sur l'URL publique de l'interface. Il doit communiquer avec le backend et renvoyer une réponse.
     FRONTEND_URL=$(gcloud run services describe public-frontend --region $REGION --format='value(status.url)')
     curl $FRONTEND_URL
  • Tester le backend (directement) : essayez d'envoyer une requête curl à l'URL du backend directement depuis votre machine locale (Internet public). Il devrait échouer avec une erreur 404, car l'entrée est limitée à "internal" et l'authentification est requise.
  curl $BACKEND_URL

8. Déployer un agent ADK

Dans cette section, vous allez découvrir comment le buildpack Python permet la détection du point d'entrée par défaut pour l'Agent Development Kit (ADK).

Vous allez créer la structure de dossiers suivante :

adk-demo
 - my_agent
   - __init.py__
   - agent.py
 - requirements.txt
  1. Créer la structure de dossiers
mkdir ../adk-demo
cd ../adk-demo
mkdir my_agent
touch my_agent/__init.py__
touch my_agent/agent.py
touch requirements.txt
  1. Ajoutez le contenu suivant au fichier my_agent/__init.py__ :
from . import agent
  1. Ajoutez le contenu suivant au fichier 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. Ajoutez le contenu suivant au fichier requirements.txt :
google-adk
  1. Créez un compte de service dédié pour l'agent :
  gcloud iam service-accounts create agent-sa \
     --display-name="Agent Service Account"
  1. Attribuez le rôle Utilisateur Vertex AI au compte de service :
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. Déployer l'agent ADK

Vous devez effectuer le déploiement dans une région où l'API Gemini est accessible. Dans cet exemple, il s'agit de 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. Envoyer une requête cURL au point de terminaison

Vous pouvez voir que l'agent est immédiatement disponible en tant qu'API prête pour la production.

Enregistrez l'URL du service Cloud Run dans une variable d'environnement.

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

Créer une session avec l'agent

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

Demande "Qu'est-ce que Cloud Run ?" et filtre la réponse pour n'afficher que ce que dit l'agent

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'])"

Le résultat doit ressembler à ceci :

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. Effectuer un nettoyage

Pour éviter que des frais ne soient facturés sur votre compte Google Cloud, vous pouvez supprimer l'intégralité du projet (voir ci-dessous) ou les ressources individuelles créées lors de cet atelier de programmation.

Supprimer les services nginx, color-app, private-backend et 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

Supprimez l'agent ADK (remarque : déployé dans us-west1 pour cet exemple).

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

Supprimez le secret stocké dans Secret Manager :

gcloud secrets delete my-secret --quiet

Supprimer le compte de service de l'application Color

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

Supprimer le compte de service de l'agent ADK

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

(Facultatif) Supprimer le projet

Si vous avez créé un projet spécifiquement pour cet atelier de programmation, vous pouvez le supprimer entièrement pour vous assurer que toutes les ressources sont supprimées en même temps :

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

10. Félicitations !

Vous avez terminé l'atelier de programmation. Vous avez découvert les bases pour commencer à utiliser Cloud Run.

Ce que vous avez appris

  • Déployer une image nginx
  • Déployer à partir de votre code source
  • Effectuer le rollback d'un déploiement
  • Prévisualiser un déploiement
  • Utiliser l'outil de serveur MCP Developer Knowledge
  • Utiliser Secret Manager avec Cloud Run
  • Se connecter à un service Cloud Run interne dans un VPC
  • Déployer un agent ADK sur Cloud Run