Der ultimative Cloud Run-Leitfaden – von null zur Produktionsdemo

1. Einführung

In diesem Codelab werden die Grundlagen für die ersten Schritte mit Cloud Run erläutert. Sie erfahren, wie Sie zusätzliche Funktionen wie VPC-Zugriff, Secret Manager und ADK für KI-Agenten verwenden, die in Cloud Run gehostet werden.

Lerninhalte

  • nginx-Image bereitstellen
  • Aus Quellcode bereitstellen
  • Rollback eines Deployments
  • Vorschau eines Deployments
  • MCP-Server-Tool für Entwicklerwissen verwenden
  • Secret Manager mit Cloud Run verwenden
  • Verbindung zu einem internen Cloud Run-Dienst in einer VPC herstellen
  • ADK-Agent in Cloud Run bereitstellen

Voraussetzungen

  • Ein Webbrowser wie Chrome
  • Ein Google Cloud-Projekt mit aktivierter Abrechnung

Google Cloud-Projekt erstellen

  1. Wählen Sie in der Google Cloud Console auf der Seite zur Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.
  2. Die Abrechnung für das Cloud-Projekt muss aktiviert sein. So prüfen Sie, ob die Abrechnung für ein Projekt aktiviert ist.

Cloud Shell starten

Cloud Shell ist eine Befehlszeilenumgebung, die in Google Cloud ausgeführt wird und mit den erforderlichen Tools vorinstalliert ist.

  1. Klicken Sie oben in der Google Cloud Console auf Cloud Shell aktivieren.
  2. Prüfen Sie nach der Verbindung mit Cloud Shell Ihre Authentifizierung:
    gcloud auth list
  3. Prüfen Sie, ob Ihr Projekt konfiguriert ist:
    gcloud config get project
  4. Wenn Ihr Projekt nicht wie erwartet festgelegt ist, legen Sie es fest:
    export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

Umgebungsvariablen festlegen

In diesem Codelab wird die folgende Umgebungsvariable verwendet.

Legen Sie zuerst Ihre Region fest.

export REGION=<YOUR_REGION>

Bestätigen Sie als Nächstes Ihre PROJECT_ID und REGION.

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

2. Bereitstellung über Image

In diesem Abschnitt stellen Sie ein Standard-Nginx-Image direkt von Docker Hub bereit. Sie konfigurieren ihn so, dass er öffentlich zugänglich ist, und legen den Containerport auf 80 fest.

  1. Stellen Sie den nginx-Dienst bereit:
   gcloud run deploy nginx-service \
     --image=nginx \
     --allow-unauthenticated \
     --port=80 \
     --region=$REGION
  1. Nach Abschluss der Bereitstellung wird in der Befehlsausgabe eine Dienst-URL angezeigt. Öffnen Sie diese URL in Ihrem Browser, um die Seite „Willkommen bei nginx!“ aufzurufen.

3. Über Quelle bereitstellen 

mkdir color-app && cd $_

Erstellen Sie eine Datei mit dem Namen requirements.txt und mit folgendem Inhalt:

Flask>=2.0.0
gunicorn>=20.0.0

Erstellen Sie eine Datei mit dem Namen main.py und mit folgendem Inhalt:

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)

Führen Sie nun den folgenden Befehl aus.

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

4. Rollbacks und Vorschaulinks

In diesem Abschnitt führen Sie einen Fehler ein und erfahren, wie Sie ein Rollback auf eine vorherige Überarbeitung durchführen, während Sie die Korrektur untersuchen.

  1. Zuerst notieren Sie den Namen der Überarbeitung, über die derzeit Traffic bereitgestellt wird, da sie den Fehler nicht enthält.
GOOD_REVISION=$(gcloud run revisions list --service color-app \
  --region $REGION --format 'value(REVISION)')
  1. Suchen Sie in der Datei main.py der Farb-App nach „ROLLBACK DEMO“ und aktualisieren Sie die Zeile so:
<p>background color: <strong>gray</strong></p>
  1. Führen Sie gcloud run deploy jetzt noch einmal aus. Sehen Sie sich an, wie Ihre bisherigen Konfigurationen verwendet wurden.

Nachdem Sie einen Fehler bereitgestellt haben, können Sie zur Quelle zurückkehren, eine Änderung vornehmen oder einen Git-Revert durchführen und dann einen neuen Build auslösen usw. Dabei kann es jedoch zu Fehlern kommen.

Eine sicherere Methode ist ein Rollback.

  1. Führen Sie Folgendes aus, um ein Rollback zur vorherigen Version durchzuführen:
gcloud run services update-traffic color-app \
  --to-revisions=$GOOD_REVISION=100 \
  --region=$REGION

Sie können jetzt eine neue Überarbeitung bereitstellen, die keinen Traffic empfängt.

  1. Beheben Sie den Fehler, indem Sie den Text wieder in darkseagreen ändern.
<p>background color: <strong>darkseagreen</strong></p>
  1. Stellen Sie sie bereit, um die Korrektur zu überprüfen. Sie empfängt keinen Traffic, da 100% des Traffics an die GOOD_REVISION weitergeleitet werden.
gcloud run deploy color-app --no-traffic --tag bugfix --region $REGION
  1. Deployment prüfen

Die URL ist etwas anders. Wenn Sie die Website aufrufen, sehen Sie die Fehlerkorrektur in dieser Bereitstellung.

  1. Traffic zurück an die neueste Überarbeitung senden

Jetzt leiten Sie den Traffic wieder an die neueste Überarbeitung weiter.

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

und löschen Sie das Überarbeitungs-Tag.

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

Weitere Informationen zu Rollbacks finden Sie in der Dokumentation.

5. MCP-Server für Entwicklerwissen

Der MCP-Server für Entwicklerwissen ermöglicht es KI-basierten Entwicklungstools, die offizielle Entwicklerdokumentation von Google zu durchsuchen und Informationen zu Google-Produkten wie Firebase, Google Cloud, Android und Maps abzurufen. Wenn Sie Ihre KI-Anwendung direkt mit unserer offiziellen Dokumentationsbibliothek verbinden, sind der Code und die Anleitungen, die Sie erhalten, immer auf dem neuesten Stand und basieren auf maßgeblichen Kontextinformationen.

Folgen Sie der Installationsanleitung, um Ihrem KI-Agenten Zugriff auf den MCP-Server für Entwicklerwissen zu gewähren.

Nach der Installation können Sie Ihrem KI‑Agenten Fragen zu den neuesten Funktionen in der Dokumentation stellen, die möglicherweise nach dem Datum des Trainings Ihres Modells verfügbar geworden sind.

Wenn Sie sich beispielsweise die Cloud Run-Versionshinweise ansehen, finden Sie für den 24. Februar 2026 einen Eintrag zum Thema „Hochverfügbaren, multiregionalen Cloud Run-Dienst mit automatischem Failover und Failback für externen Traffic mithilfe des Cloud Run-Dienstzustands bereitstellen (Vorabversion)“.

Sie können Ihren KI-Agenten jetzt fragen: „Erzähl mir mehr über diese neue Cloud Run-Funktion für multiregionales automatisches Failover.“

6. Secret Manager verwenden

Es gibt drei Möglichkeiten, Secrets in Cloud Run verfügbar zu machen:

  1. Als Umgebungsvariable (an die Version gebunden, die zum Bereitstellungszeitpunkt abgerufen wurde).
  2. Als Dateivolume bereitgestellt (wird kontinuierlich auf die aktuelle Version aktualisiert).
  3. Verwenden der Secret Manager-Clientbibliotheken in Ihrem Code.

In diesem Abschnitt machen Sie ein Secret mithilfe eines dedizierten Dienstkontos als Umgebungsvariable verfügbar.

  1. Erstellen Sie ein neues Secret mit dem Namen „my-secret“:
gcloud secrets create my-secret --replication-policy="automatic"
  1. Fügen Sie den Secret-Wert als neue Version hinzu:
echo -n "my precious" | gcloud secrets versions add my-secret --data-file=-
  1. Erstellen Sie ein dediziertes Dienstkonto für die Farb-App:
gcloud iam service-accounts create color-app-sa \
     --display-name="Color App Service Account"
  1. Gewähren Sie dem dedizierten Dienstkonto Zugriff auf das Secret.
   gcloud secrets add-iam-policy-binding my-secret \
     --member="serviceAccount:color-app-sa@${PROJECT_ID}.iam.gserviceaccount.com" \
     --role="roles/secretmanager.secretAccessor"
  1. Stellen Sie die Funktion noch einmal bereit. Der Dienst hat jetzt Zugriff auf die Umgebungsvariable 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. Mit einer VPC verbinden

In diesem Abschnitt richten Sie die folgende Architektur ein:

  • privates Backend, das nicht über das öffentliche Internet zugänglich ist
  • ein öffentliches Frontend, das über ausgehenden Direct VPC-Traffic mit dem Backend kommuniziert

In diesem Beispiel werden das Standardnetzwerk und das Standardsubnetz verwendet.

Voraussetzung:Achten Sie darauf, dass der private Google-Zugriff für Ihr Subnetz aktiviert ist, damit die VPC interne Anfragen an Cloud Run-Dienste weiterleiten kann.

   gcloud compute networks subnets update default \
     --region=$REGION \
     --enable-private-ip-google-access
  1. Ordner für diesen Abschnitt erstellen
mkdir ../vpc-demo
cd ../vpc-demo
  1. privaten Backend-Dienst erstellen
mkdir backend
touch backend/app.js
touch backend/package.json

Fügen Sie in der Datei backend/app.js Folgendes hinzu:

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

Fügen Sie in der Datei backend/package.json Folgendes hinzu:

{
    "name": "backend",
    "scripts": {
        "start": "node app.js"
    }
}
  1. Stellen Sie das private Backend mit nur internem Ingress bereit:
   gcloud run deploy private-backend \
     --source ./backend \
     --region $REGION \
     --ingress internal \
     --no-allow-unauthenticated
  1. Notieren Sie sich die Backend-URL. Sie stellen diese URL später für die Frontend-App bereit.
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projec
tNumber)')

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

Fügen Sie in der Datei frontend/app.js Folgendes hinzu:

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. Fügen Sie in der Datei frontend/package.json Folgendes hinzu:
{
    "name": "backend",
    "scripts": {
        "start": "node app.js"
    }
}
  1. Erstellen Sie ein dediziertes Dienstkonto für den Frontend-Dienst:
  gcloud iam service-accounts create frontend-sa \
     --display-name="Frontend Service Account"
  1. Weisen Sie ihm die Rolle „Cloud Run Invoker“ zu.
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. Stellen Sie das öffentliche Frontend jetzt mit ausgehendem Direct VPC-Traffic bereit. Wir legen „–vpc-egress=all-traffic“ fest, um die ausgehende Anfrage in die VPC zu erzwingen:
   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. Dienste überprüfen
  • Frontend testen:Führen Sie „curl“ für die öffentliche Frontend-URL aus. Die Kommunikation mit dem Backend sollte erfolgreich sein und eine Antwort zurückgeben.
     FRONTEND_URL=$(gcloud run services describe public-frontend --region $REGION --format='value(status.url)')
     curl $FRONTEND_URL
  • Backend testen (direkt): Versuchen Sie, die Backend-URL direkt von Ihrem lokalen Computer (öffentliches Internet) aus zu senden. Es sollte ein 404-Fehler auftreten, da der Ingress auf „internal“ beschränkt ist und eine Authentifizierung erforderlich ist.
  curl $BACKEND_URL

8. ADK-Agent bereitstellen

In diesem Abschnitt erfahren Sie, wie der Python-Buildpack die automatische Erkennung von Standard-Einstiegspunkten für das Agent Development Kit (ADK) unterstützt.

Sie erstellen die folgende Ordnerstruktur:

adk-demo
 - my_agent
   - __init.py__
   - agent.py
 - requirements.txt
  1. Ordnerstruktur erstellen
mkdir ../adk-demo
cd ../adk-demo
mkdir my_agent
touch my_agent/__init.py__
touch my_agent/agent.py
touch requirements.txt
  1. Fügen Sie der my_agent/__init.py__-Datei diesen Inhalt hinzu:
from . import agent
  1. Fügen Sie der my_agent/agent.py-Datei diesen Inhalt hinzu:
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. Fügen Sie der requirements.txt-Datei diesen Inhalt hinzu:
google-adk
  1. Erstellen Sie ein dediziertes Dienstkonto für den Agent:
  gcloud iam service-accounts create agent-sa \
     --display-name="Agent Service Account"
  1. Weisen Sie dem Dienstkonto die Rolle „Vertex AI-Nutzer“ zu:
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. ADK-Agent bereitstellen

Sie müssen die Bereitstellung in einer Region vornehmen, in der die Gemini API verfügbar ist. In diesem Beispiel ist das 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. Endpunkt mit cURL aufrufen

Sie sehen, dass der Agent sofort als produktionsreife API verfügbar ist.

Speichern Sie die Cloud Run-Dienst-URL in einer Umgebungsvariablen.

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

Sitzung mit dem Agenten erstellen

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

Frage, was Cloud Run ist, und filtere die Antwort so, dass nur das angezeigt wird, was der Agent sagt.

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

Die Ausgabe sollte in etwa so aussehen:

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. Bereinigen

Damit Ihrem Google Cloud-Konto keine laufenden Gebühren in Rechnung gestellt werden, können Sie entweder das gesamte Projekt (siehe unten) oder die einzelnen Ressourcen löschen, die während dieses Codelabs erstellt wurden.

Löschen Sie die Dienste „nginx“, „color-app“, „private-backend“ und „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

ADK-Agent löschen (Hinweis: In diesem Beispiel wird er in „us-west1“ bereitgestellt)

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

Entfernen Sie das in Secret Manager gespeicherte Secret:

gcloud secrets delete my-secret --quiet

Dienstkonto der Color App löschen

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

ADK-Agent-Dienstkonto löschen

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

(Optional) Projekt löschen

Wenn Sie ein neues Projekt speziell für dieses Codelab erstellt haben, können Sie das gesamte Projekt löschen, um alle Ressourcen auf einmal zu entfernen:

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

10. Glückwunsch!

Sie haben das Codelab abgeschlossen. Sie haben die Grundlagen für den Einstieg in Cloud Run kennengelernt.

Das haben Sie gelernt

  • nginx-Image bereitstellen
  • Aus Quellcode bereitstellen
  • Rollback eines Deployments
  • Vorschau eines Deployments
  • MCP-Server-Tool für Entwicklerwissen verwenden
  • Secret Manager mit Cloud Run verwenden
  • Verbindung zu einem internen Cloud Run-Dienst in einer VPC herstellen
  • ADK-Agent in Cloud Run bereitstellen