המדריך האולטימטיבי ל-Cloud Run: הדגמה מפורטת מ-0 ועד ל-Production

1. מבוא

בשיעור Codelab הזה נסביר את העקרונות הבסיסיים של תחילת העבודה עם Cloud Run. תלמדו איך להשתמש בתכונות נוספות, כולל גישה ל-VPC, ל-Secret Manager ול-ADK לסוכני AI שמתארחים ב-Cloud Run.

מה תלמדו

פריסת תמונת nginx
פריסה מקוד המקור
החזרה של פריסה למצב הקודם
תצוגה מקדימה של פריסה
שימוש בכלי שרת MCP של Developer Knowledge
שימוש ב-Secret Manager עם Cloud Run
התחברות לשירות פנימי של Cloud Run בתוך VPC
פריסת סוכן ADK ב-Cloud Run

הדרישות

דפדפן אינטרנט כמו Chrome
פרויקט ב-Google Cloud שהחיוב בו מופעל

יצירת פרויקט ב-Google Cloud

במסוף Google Cloud, בדף לבחירת הפרויקט, בוחרים פרויקט ב-Google Cloud או יוצרים פרויקט.
הקפידו לוודא שהחיוב מופעל בפרויקט שלכם ב-Cloud. כך בודקים אם החיוב מופעל בפרויקט

הפעלת Cloud Shell

‫Cloud Shell היא סביבת שורת פקודה שפועלת ב-Google Cloud וכוללת מראש את הכלים הנדרשים.

לוחצים על Activate Cloud Shell בחלק העליון של מסוף Google Cloud.
אחרי שמתחברים ל-Cloud Shell, מאמתים את האימות:
```
gcloud auth list
```
מוודאים שהפרויקט מוגדר:
```
gcloud config get project
```
אם הפרויקט לא מוגדר כמו שציפיתם, מגדירים אותו:
```
export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID
```

הגדרה של משתני סביבה

ב-Codelab הזה אנחנו משתמשים במשתנה הסביבה הבא.

קודם כל, מגדירים את האזור.

export REGION=<YOUR_REGION>

לאחר מכן, מאשרים את PROJECT_ID ואת האזור.

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

2. פריסה מתמונה

בקטע הזה נסביר איך לפרוס תמונת nginx רגילה ישירות מ-Docker Hub. תגדירו אותו כנגיש באופן ציבורי ותגדירו את יציאת המאגר ל-80.

פורסים את שירות nginx:

   gcloud run deploy nginx-service \
     --image=nginx \
     --allow-unauthenticated \
     --port=80 \
     --region=$REGION

אחרי שהפריסה תושלם, כתובת URL של שירות תופיע בפלט הפקודה. פותחים את כתובת ה-URL הזו בדפדפן כדי לראות את הדף 'Welcome to nginx!‎'.

3. פריסה מקוד המקור

mkdir color-app && cd $_

יוצרים קובץ בשם requirements.txt עם התוכן הבא:

Flask>=2.0.0
gunicorn>=20.0.0

יוצרים קובץ בשם main.py עם התוכן הבא:

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)

מריצים את הפקודה הבאה.

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

4. החזרות לגרסה קודמת וקישורים לתצוגה מקדימה

בקטע הזה נציג באג ונלמד איך לחזור לגרסה קודמת בזמן שבודקים את התיקון.

קודם כול, צריך לתעד את שם הגרסה שמוצגת כרגע למשתמשים, כי היא לא מכילה את הבאג.

GOOD_REVISION=$(gcloud run revisions list --service color-app \
  --region $REGION --format 'value(REVISION)')

בתוך קובץ main.py של אפליקציית הצבע, מחפשים את המחרוזת ROLLBACK DEMO ומעדכנים את השורה כך שתיראה כמו השורה הבאה:

<p>background color: <strong>gray</strong></p>

עכשיו מריצים מחדש את gcloud run deploy. שימו לב לאופן השימוש בהגדרות הקודמות.

אחרי שפרסתם באג, אתם יכולים לחזור למקור, לבצע שינוי או לבצע git revert ואז לבנות, להפעיל בנייה חדשה וכו'. עם זאת, יכול להיות שתגרמו לשגיאה במהלך התהליך.

דרך בטוחה יותר היא לבצע חזרה לגרסה קודמת.

כדי לחזור לגרסה הקודמת, מריצים את הפקודה הבאה:

gcloud run services update-traffic color-app \
  --to-revisions=$GOOD_REVISION=100 \
  --region=$REGION

עכשיו אפשר לפרוס גרסה חדשה שלא תקבל תנועה.

עכשיו צריך לתקן את הבאג על ידי שינוי הטקסט בחזרה ל-darkseagreen

<p>background color: <strong>darkseagreen</strong></p>

ואז פורסים אותו כדי לאמת את התיקון. שימו לב: הגרסה לא תקבל תנועה כי 100% מהתנועה מוצמדים ל-GOOD_REVISION

gcloud run deploy color-app --no-traffic --tag bugfix --region $REGION

אימות הפריסה

תשימו לב שכתובת ה-URL שונה מעט. כשתיכנסו אליו, תוכלו לראות את תיקון הבאג בפריסה הזו.

החזרת התנועה לגרסה האחרונה.

עכשיו צריך להחזיר את התנועה לגרסה האחרונה.

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

ומחיקת תג התיקון

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

מידע נוסף על חזרה לגרסה קודמת זמין במסמכי התיעוד.

5. שרת ה-MCP של Developer Knowledge

שרת ה-MCP של Knowledge למפתחים מאפשר לכלי פיתוח מבוססי-AI לחפש בתיעוד הרשמי למפתחים של Google ולאחזר מידע על מוצרי Google כמו Firebase,‏ Google Cloud,‏ Android,‏ מפות ועוד. חיבור אפליקציית ה-AI ישירות לספריית התיעוד הרשמית שלנו מבטיח שהקוד וההנחיות שתקבלו יהיו עדכניים ומבוססים על הקשר מהימן.

כדאי לפעול לפי ההנחיות להתקנה כדי להעניק לסוכן ה-AI גישה לשרת ה-MCP של Developer Knowledge.

אחרי ההתקנה, תוכלו לשאול את סוכן ה-AI שאלות על התכונות האחרונות במסמכי התיעוד, שאולי הפכו לזמינות אחרי תאריך הסיום של אימון המודל.

לדוגמה, אם תעיינו בהערות לגבי הגרסה של Cloud Run, תראו שבקטע 24 בפברואר 2026 יש רשומה בנושא 'פריסת שירות Cloud Run עם זמינות גבוהה, במספר אזורים, עם מעבר אוטומטי לגיבוי ומגיבוי לגיבוי לתעבורת נתונים חיצונית באמצעות Service Health של Cloud Run (גרסת Preview)'.

עכשיו אפשר לשאול את סוכן ה-AI: "תסביר לי יותר על התכונה החדשה הזו של Cloud Run למעבר אוטומטי לגיבוי באזורים שונים".

6. שימוש ב-Secret Manager

יש 3 דרכים לחשוף סודות ב-Cloud Run:

כמשתנה סביבה (נעול לגרסה שנמשכה בזמן הפריסה).
נטען כנפח קבצים (ומתעדכן באופן רציף לגרסה העדכנית).
שימוש בספריות הלקוח של Secret Manager בקוד.

בקטע הזה נסביר איך חושפים סוד כמשתנה סביבה באמצעות חשבון שירות ייעודי.

יוצרים סוד חדש בשם my-secret:

gcloud secrets create my-secret --replication-policy="automatic"

מוסיפים את ערך הסוד כגרסה חדשה:

echo -n "my precious" | gcloud secrets versions add my-secret --data-file=-

יוצרים חשבון שירות ייעודי לאפליקציית הצבעים:

gcloud iam service-accounts create color-app-sa \
     --display-name="Color App Service Account"

מעניקים לחשבון השירות הייעודי גישה לסוד.

   gcloud secrets add-iam-policy-binding my-secret \
     --member="serviceAccount:color-app-sa@${PROJECT_ID}.iam.gserviceaccount.com" \
     --role="roles/secretmanager.secretAccessor"

פורסים מחדש. עכשיו לשירות תהיה גישה למשתנה הסביבה 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. התחברות ל-VPC

בקטע הזה נגדיר את הארכיטקטורה הבאה:

קצה עורפי פרטי שלא ניתן לגשת אליו מהאינטרנט הציבורי
קצה קדמי שגלוי לכולם ומתקשר עם הבק-אנד באמצעות תעבורת נתונים יוצאת (egress) ישירה של VPC

בדוגמה הזו ייעשה שימוש ברשת ובתת-רשת שמוגדרות כברירת מחדל.

דרישה מוקדמת: מוודאים שהגישה הפרטית ל-Google מופעלת ברשת המשנה, כדי ש-VPC יוכל לנתב בקשות פנימיות לשירותי Cloud Run.

   gcloud compute networks subnets update default \
     --region=$REGION \
     --enable-private-ip-google-access

יצירת תיקייה לקטע הזה

mkdir ../vpc-demo
cd ../vpc-demo

יצירת שירות לקצה העורפי פרטי

mkdir backend
touch backend/app.js
touch backend/package.json

מוסיפים את הטקסט הבא לקובץ backend/app.js:

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

מוסיפים את הטקסט הבא לקובץ backend/package.json:

{
    "name": "backend",
    "scripts": {
        "start": "node app.js"
    }
}

פורסים את הקצה העורפי הפרטי עם תעבורת נכנסת פנימית בלבד:

   gcloud run deploy private-backend \
     --source ./backend \
     --region $REGION \
     --ingress internal \
     --no-allow-unauthenticated

רושמים את כתובת ה-URL של הקצה העורפי. בהמשך תצטרכו לספק את כתובת ה-URL הזו לאפליקציית הקצה הקדמי.

export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projec
tNumber)')

export BACKEND_URL="https://private-backend-${PROJECT_NUMBER}.${REGION}.run.app"

יצירת אפליקציית הקצה הקדמי

mkdir frontend
touch frontend/app.js
touch frontend/package.json

מוסיפים את הטקסט הבא לקובץ frontend/app.js:

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

מוסיפים את הטקסט הבא לקובץ frontend/package.json:

{
    "name": "backend",
    "scripts": {
        "start": "node app.js"
    }
}

יוצרים חשבון שירות ייעודי לשירות הקצה הקדמי:

  gcloud iam service-accounts create frontend-sa \
     --display-name="Frontend Service Account"

מקצים לו את התפקיד 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"

עכשיו פורסים את ממשק המשתמש הציבורי באמצעות תעבורת נתונים יוצאת (egress) ישירה של VPC. הגדרנו את '‎–vpc-egress=all-traffic' כדי לכפות את הבקשה היוצאת לתוך ה-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

אימות השירותים

בדיקת חזית האתר: מריצים את הפקודה curl על כתובת ה-URL הציבורית של חזית האתר. היא אמורה לתקשר עם ה-backend ולהחזיר תשובה.

     FRONTEND_URL=$(gcloud run services describe public-frontend --region $REGION --format='value(status.url)')
     curl $FRONTEND_URL

בדיקת ה-Backend (ישירות): מנסים להשתמש בפקודת curl כדי לגשת לכתובת ה-URL של ה-Backend ישירות מהמחשב המקומי (אינטרנט ציבורי). הפעולה אמורה להיכשל עם שגיאה 404 כי הגישה מוגבלת ל'פנימית' ונדרש אימות.

  curl $BACKEND_URL

8. פריסת סוכן ADK

בקטע הזה נסביר איך ה-buildpack של Python תומך בזיהוי ברירת מחדל של נקודת כניסה לערכה לפיתוח סוכנים (ADK).

תיווצר מבנה התיקיות הבא:

adk-demo
 - my_agent
   - __init.py__
   - agent.py
 - requirements.txt

יצירת מבנה התיקיות

mkdir ../adk-demo
cd ../adk-demo
mkdir my_agent
touch my_agent/__init.py__
touch my_agent/agent.py
touch requirements.txt

מוסיפים את התוכן הבא לקובץ my_agent/__init.py__:

from . import agent

מוסיפים את התוכן הבא לקובץ 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."
)

מוסיפים את התוכן הבא לקובץ requirements.txt:

google-adk

יוצרים חשבון שירות ייעודי לסוכן:

  gcloud iam service-accounts create agent-sa \
     --display-name="Agent Service Account"

מקצים לחשבון השירות את התפקיד Vertex AI User:

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"

פריסת סוכן ADK

אתם צריכים לבצע פריסה באזור שבו יש גישה ל-Gemini API. בדוגמה הזו, זה 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"

הפעלת פקודת Curl בנקודת הקצה

אפשר לראות שהסוכן זמין באופן מיידי כ-API מוכן לייצור.

מתעדים את כתובת ה-URL של שירות Cloud Run במשתנה סביבה.

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

יצירת סשן עם הסוכן

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

תשאל מה זה Cloud Run ותסנן את התשובה כך שיוצג רק מה שהסוכן אומר

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

אמורה להופיע כותרת שדומה לכותרת הבאה:

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. הסרת המשאבים

כדי להימנע מחיובים שוטפים בחשבון Google Cloud, אתם יכולים למחוק את הפרויקט כולו (כפי שמוסבר בהמשך) או למחוק את המשאבים הספציפיים שנוצרו במהלך ה-Codelab הזה.

מחיקת השירותים nginx,‏ color-app,‏ private-backend ו-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 (הערה: הסוכן נפרס ב-us-west1 בדוגמה הזו)

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

מסירים את הסוד שמאוחסן ב-Secret Manager:

gcloud secrets delete my-secret --quiet

מחיקת חשבון השירות של אפליקציית הצבעים

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

מחיקה של חשבון השירות של סוכן ADK

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

(אופציונלי) מחיקת הפרויקט

אם יצרתם פרויקט חדש במיוחד בשביל ה-Codelab הזה, אתם יכולים למחוק את הפרויקט כולו כדי לוודא שכל המשאבים יוסרו בבת אחת:

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

10. מעולה!

סיימתם את ה-Codelab. הסברנו את השלבים הבסיסיים לתחילת העבודה עם Cloud Run.

מה למדתם

פריסת תמונת nginx
פריסה מקוד המקור
החזרה של פריסה למצב הקודם
תצוגה מקדימה של פריסה
שימוש בכלי שרת MCP של Developer Knowledge
שימוש ב-Secret Manager עם Cloud Run
התחברות לשירות פנימי של Cloud Run בתוך VPC
פריסת סוכן ADK ב-Cloud Run