שימוש בגרסאות ב-Cloud Run לחלוקת תנועה, להשקות הדרגתיות ולחזרות לאחור

שימוש בגרסאות ב-Cloud Run לחלוקת תנועה, להשקות הדרגתיות ולחזרות לאחור

מידע על Codelab זה

subjectהעדכון האחרון: אפר׳ 5, 2025
account_circleנכתב על ידי גוגלר

1.‏ מבוא

סקירה כללית

גרסאות של Cloud Run מאפשרות לכם לציין אילו גרסאות יקבלו תנועה ואת אחוז התנועה שיישלח לכל גרסה. בעזרת הגרסאות אפשר לבצע חזרה לגרסה קודמת, להשיק גרסה בהדרגה ולחלק את התנועה בין כמה גרסאות.

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

מה תלמדו

  • איך לפצל את התנועה בין שתי גרסאות או יותר של שירות Cloud Run
  • איך משיקים גרסה חדשה בהדרגה
  • איך חוזרים לגרסה קודמת

2.‏ הגדרה ודרישות

דרישות מוקדמות

  • אתם מחוברים למסוף Cloud.
  • כבר פרסתם שירות Cloud Run. לדוגמה, תוכלו לפעול לפי ההוראות לפריסה של שירות Cloud Run כדי להתחיל.

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

אפשר להגדיר משתני סביבה שישמשו במהלך הקודלאב הזה.

PROJECT_ID=YOUR-PROJECT-ID
REGION=YOUR_REGION

BG_COLOR=darkseagreen
SERVICE_NAME=traffic-revisions-color
AR_REPO=traffic-revisions-color-repo

יצירת מאגר של Artifact Registry לשירות

gcloud artifacts repositories create $AR_REPO \
    --repository-format=docker \
    --location=$REGION \
    --description="codelab for finetuning using CR jobs" \
    --project=$PROJECT_ID

3.‏ חלוקת התנועה

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

בשיעור הזה נעשה שימוש ב-Python, אבל אפשר להשתמש בכל סביבת זמן ריצה.

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

אפשר להגדיר משתני סביבה שישמשו במהלך הקודלאב הזה.

REGION=<YOUR_REGION>
PROJECT_ID=<YOUR-PROJECT-ID>
BG_COLOR=darkseagreen
SERVICE_NAME=traffic-revisions-color
AR_REPO=traffic-revisions-color-repo

יצירת השירות

קודם יוצרים ספרייה לקוד המקור ומעבירים את עצמנו לספרייה הזו באמצעות cd.

mkdir traffic-revisions-codelab && cd $_

לאחר מכן, יוצרים קובץ 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: {{ bg_color }}; /* Set by environment variable */
            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">
        <p>background color: <strong>{{ color_name }}</strong></p>
    </div>
</body>
</html>
"""

@app.route('/')
def main():
    """Serves the main page with a background color from the ENV."""
    # Get the color from the 'BG_COLOR' environment variable.
    # Default to 'white' if the variable is not set.
    color = os.environ.get('BG_COLOR', 'white').lower()

    return render_template_string(TEMPLATE, bg_color=color, color_name=color)

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

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

Flask>=2.0.0
gunicorn>=20.0.0

לבסוף, יוצרים Dockerfile

FROM python:3.12-slim

WORKDIR /app

COPY requirements.txt .

RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 8080

ENV PYTHONPATH /app

CMD ["gunicorn", "--bind", "0.0.0.0:8080", "main:app"]

יוצרים את קובץ האימג' ב-Artifact Registry באמצעות Buildpacks באמצעות Cloud Build:

gcloud builds submit \
   --tag $REGION-docker.pkg.dev/$PROJECT_ID/$AR_REPO/$SERVICE_NAME

ופורסים את הגרסה הראשונה ב-Cloud Run עם הצבע darkseagreen:

gcloud run deploy $SERVICE_NAME \
    --image $REGION-docker.pkg.dev/$PROJECT_ID/$AR_REPO/$SERVICE_NAME:latest \
    --region $REGION \
    --allow-unauthenticated \
    --set-env-vars BG_COLOR=darkseagreen

כדי לבדוק את השירות, אפשר לפתוח את נקודת הקצה ישירות בדפדפן האינטרנט כדי לראות את צבע הרקע כירוק ים כהה.

עכשיו פורסים גרסה שנייה עם צבע רקע חום.

# update the env var
BG_COLOR=tan

gcloud run deploy $SERVICE_NAME \
    --image $REGION-docker.pkg.dev/$PROJECT_ID/$AR_REPO/$SERVICE_NAME:latest \
    --region $REGION \
    --set-env-vars BG_COLOR=tan

עכשיו, כשתרעננו את האתר, יופיע צבע הרקע החום.

חלוקת התנועה ביחס של 50-50

כדי לפצל את התנועה בין הגרסאות בצבע ירוק כהה ובצבע חום, צריך למצוא את מזהי הגרסאות של שירותי Cloud Run הבסיסיים. כדי לראות את מזהי הגרסאות, מריצים את הפקודה הבאה:

gcloud run revisions list --service $SERVICE_NAME \
  --region $REGION --format 'value(REVISION)'

אמורות להופיע תוצאות דומות לאלה שבהמשך

traffic-revisions-color-00003-qoq
traffic-revisions-color-00002-zag

כדי לפצל את התנועה ביחס של 50/50 בין שתי הגרסאות, מריצים את הפקודה הבאה עם הגרסאות:

gcloud run services update-traffic $SERVICE_NAME \
  --region $REGION \
  --to-revisions YOUR_REVISION_1=50,YOUR_REVISION_2=50

בדיקת חלוקת התנועה

כדי לבדוק את השירות, אפשר לרענן את הדף בדפדפן.

חצי מהזמן אמורה להופיע הגרסה בצבע ירוק כהה של הים, ובחצי השני אמורה להופיע הגרסה בצבע חום. שם הגרסה יופיע גם בפלט, למשל:

<html><body style="background-color:tan;"><div><p>Hello traffic-revisions-color-00003-qoq</p></div></body></html>

4.‏ השקות הדרגתיות

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

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

קודם כול, מגדירים את צבע הרקע כ-beige ופורסים את הפונקציה בשם gradual-rollouts-colors.

כדי לפרוס פונקציית Cloud Run ישירות ב-Cloud Run, מריצים את הפקודה הבאה:

# update the env var
BG_COLOR=beige

gcloud beta run deploy gradual-rollouts-colors \
      --image $REGION-docker.pkg.dev/$PROJECT_ID/$AR_REPO/$SERVICE_NAME:latest \
      --region $REGION \
      --allow-unauthenticated \
      --update-env-vars BG_COLOR=$BG_COLOR

נניח שאנחנו רוצים להשיק בהדרגה גרסה חדשה עם צבע רקע לבנדר.

קודם כול, נגדיר שהגרסה הנוכחית (beige) תקבל 100% מהתנועה. כך תוכלו לוודא שלא תהיה תנועה לגרסאות העתידיות שלכם. כברירת מחדל, Cloud Run מגדיר 100% מהתנועה לגרסה עם הדגל latest. אם מציינים ידנית שגרסת beige הנוכחית תקבל את כל התנועה, גרסת השגיאה עם הדגל latest לא תקבל יותר 100% מהתנועה. לצפייה במסמכי התיעוד

# get the revision name

BEIGE_REVISION=$(gcloud run revisions list --service gradual-rollouts-colors \
  --region $REGION --format 'value(REVISION)')

# now set 100% traffic to that revision

gcloud run services update-traffic gradual-rollouts-colors \
  --to-revisions=$BEIGE_REVISION=100 \
  --region $REGION

יוצג פלט שדומה ל-Traffic: 100% radual-rollouts-colors-00001-yox

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

כדי לפרוס פונקציית Cloud Run ישירות ב-Cloud Run, מריצים את הפקודה הבאה:

# update color

BG_COLOR=lavender

# deploy the function that will not receive any traffic
gcloud beta run deploy gradual-rollouts-colors \
      --image $REGION-docker.pkg.dev/$PROJECT_ID/$AR_REPO/$SERVICE_NAME:latest \
      --region $REGION \
      --allow-unauthenticated \
      --update-env-vars BG_COLOR=$BG_COLOR

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

בדיקה של גרסה שמוצגת ל-0% מהתנועה

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

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

קודם כול, צריך לקבל את כתובת ה-URL של התמונה בגרסה האחרונה (הסגולה).

IMAGE_URL_LAVENDER=$(gcloud run services describe gradual-rollouts-colors --region $REGION --format 'value(IMAGE)')

עכשיו מסמנים את התמונה בצבע המשויך לה.

gcloud run deploy gradual-rollouts-colors --image $IMAGE_URL_LAVENDER --no-traffic --tag $BG_COLOR --region $REGION

הפלט אמור להיראות כך:

The revision can be reached directly at https://lavender---gradual-rollouts-colors-<hash>-<region>.a.run.app

עכשיו, כשנכנסים לכתובת ה-URL הספציפית של הגרסה, מופיע הצבע סגול בהיר.

עלייה הדרגתית בנפח התנועה

עכשיו אפשר להתחיל לשלוח תנועה לגרסה lavender. בדוגמה הבאה מוסבר איך לשלוח 1% מהתנועה אל lavender.

gcloud run services update-traffic gradual-rollouts-colors --region $REGION --to-tags lavender=1

כדי לשלוח 50% מהתנועה אל lavender, אפשר להשתמש באותה פקודה, אבל לציין 50% במקום זאת.

gcloud run services update-traffic gradual-rollouts-colors --region $REGION --to-tags lavender=50

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

Traffic:
  50% gradual-rollouts-colors-00001-hos
  50% gradual-rollouts-colors-00004-mum
        lavender: https://lavender---gradual-rollouts-colors-<hash>-<region>.a.run.app

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

gcloud run services update-traffic gradual-rollouts-colors --region $REGION --to-tags lavender=100

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

5.‏ החזרות לאחור

נניח שקיבלת משוב ראשוני על חוויית המשתמש, שמראה שהלקוחות מעדיפים את הצבע בז' לבן לילך, וצריך לבצע חזרה לאחור לצבע בז'.

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

gcloud run services update-traffic gradual-rollouts-colors --region $REGION --to-revisions $BEIGE_REVISION=100

מעכשיו, כשתבקרו באתר, צבע הרקע יהיה בז'.

במסמכי העזרה מפורט מידע נוסף על החזרות לאחור.

6.‏ מעולה!

כל הכבוד על השלמת ה-Codelab!

מומלץ לעיין במסמכים בנושא השקות, החזרות לאחור והעברת תנועה

מה עסקנו בו

  • איך לפצל את התנועה בין שתי גרסאות או יותר של שירות Cloud Run
  • איך משיקים גרסה חדשה בהדרגה
  • איך חוזרים לגרסה קודמת

7.‏ הסרת המשאבים

כדי להימנע מחיובים לא מכוונים (לדוגמה, אם הפונקציה הזו ב-Cloud Run מופעלת בטעות יותר פעמים מההקצאה החודשית שלכם להפעלות של Cloud Run ברמה החינמית), אתם יכולים למחוק את שירות Cloud Run או למחוק את הפרויקט שיצרתם בשלב 2.

כדי למחוק שירות Cloud Run, נכנסים אל Cloud Run במסוף Cloud בכתובת https://console.cloud.google.com/run/ ומוחקים את הפונקציות שיצרתם בקודלאב הזה.

אם בוחרים למחוק את הפרויקט כולו, אפשר לעבור אל https://console.cloud.google.com/cloud-resource-manager, לבחור את הפרויקט שיצרתם בשלב 2 ולבחור באפשרות Delete (מחיקה). אם תמחקו את הפרויקט, תצטרכו לשנות את הפרויקטים ב-Cloud SDK. כדי להציג את רשימת כל הפרויקטים הזמינים, מריצים את הפקודה gcloud projects list.

bug_report דיווח על טעות