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

1. מבוא

סקירה כללית

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

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

מה תלמדו

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

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

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

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

הפעלת Cloud Shell

ב-Cloud Console, לוחצים על Activate Cloud Shell .

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

הקצאת המשאבים והחיבור ל-Cloud Shell נמשכים רק כמה רגעים.

המכונה הווירטואלית הזו כוללת את כל הכלים הדרושים למפתחים. יש בה ספריית בית בנפח מתמיד של 5GB והיא פועלת ב-Google Cloud, מה שמשפר מאוד את הביצועים והאימות ברשת. אפשר לבצע את רוב העבודה ב-codelab הזה, אם לא את כולה, באמצעות דפדפן.

אחרי שמתחברים ל-Cloud Shell, אמור להופיע אימות ושהפרויקט מוגדר לפי מזהה הפרויקט.

מריצים את הפקודה הבאה ב-Cloud Shell כדי לוודא שעברתם אימות:

gcloud auth list

פלט הפקודה

 Credentialed Accounts
ACTIVE  ACCOUNT
*       <my_account>@<my_domain.com>

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

מריצים את הפקודה הבאה ב-Cloud Shell כדי לוודא שפקודת gcloud מכירה את הפרויקט:

gcloud config list project

פלט הפקודה

[core]
project = <PROJECT_ID>

אם לא, אפשר להגדיר אותו באמצעות הפקודה הבאה:

gcloud config set project <PROJECT_ID>

פלט הפקודה

Updated property [core/project].

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

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

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

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

אתם יכולים להגדיר משתני סביבה שישמשו אתכם לאורך כל ה-codelab הזה.

REGION=<YOUR_REGION>
PROJECT_ID=<YOUR-PROJECT-ID>
BG_COLOR=darkseagreen

יצירת הפונקציה

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

mkdir revisions-gcf-codelab && cd $_

לאחר מכן, יוצרים קובץ package.json עם התוכן הבא:

{
    "dependencies": {
        "@google-cloud/functions-framework": "^3.0.0"
    }
}

לאחר מכן, יוצרים קובץ מקור index.js עם התוכן הבא:

const functions = require('@google-cloud/functions-framework');

const BG_COLOR = process.env.BG_COLOR;
const K_REVISION = process.env.K_REVISION;

functions.http('helloWorld', (req, res) => {
    res.writeHead(200, { 'Content-Type': 'text/html' });
    res.end('<html><body style="background-color:' + BG_COLOR + ';"' + '><div><p>' + 'Hello from ' + K_REVISION + ' using color ' + BG_COLOR + '</p></div></body>' + '</html>');
});

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

gcloud beta run deploy traffic-splitting-gcf \
      --source . \
      --function helloWorld \
      --region $REGION \
      --no-allow-unauthenticated \
      --set-env-vars BG_COLOR=$BG_COLOR

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

gcloud functions deploy traffic-splitting-gcf \
  --gen2 \
  --runtime=nodejs20 \
  --region=$REGION \
  --source=. \
  --entry-point=helloWorld \
  --trigger-http \
  --no-allow-unauthenticated \
  --set-env-vars BG_COLOR=$BG_COLOR

כדי לבדוק את הפונקציה, אפשר להשתמש בפקודה curl כדי להציג את נקודת הקצה הקיימת ולראות את הצבע darkseagreen ב-HTML, או להשתמש בדפדפן כדי להגיע ישירות לנקודת הקצה ולראות את צבע הרקע.

SERVICE_URL=$(gcloud run services describe traffic-splitting-gcf --platform managed --region $REGION --format 'value(status.url)')

curl -H "Authorization: bearer $(gcloud auth print-identity-token)" -X GET $SERVICE_URL

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

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

# update the env var
BG_COLOR=tan

gcloud beta run deploy traffic-splitting-gcf \
      --source . \
      --function helloWorld \
      --region $REGION \
      --no-allow-unauthenticated \
      --update-env-vars BG_COLOR=$BG_COLOR

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

# update the env var
BG_COLOR=tan

gcloud functions deploy traffic-splitting-gcf \
  --gen2 \
  --runtime nodejs20 \
  --entry-point helloHttp \
  --source . \
  --region $REGION \
  --trigger-http \
  --no-allow-unauthenticated \
  --update-env-vars BG_COLOR=$BG_COLOR

עכשיו, כשמבצעים curl לנקודת הקצה, רואים את צבע הרקע החום.

curl -H "Authorization: bearer $(gcloud auth print-identity-token)" -X GET $SERVICE_URL

חלוקת התנועה 50-50

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

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

אתם אמורים לראות תוצאות דומות לאלה שמופיעות למטה

traffic-splitting-gcf-00003-qoq
traffic-splitting-gcf-00002-zag

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

gcloud run services update-traffic traffic-splitting-gcf \
  --region $REGION \
  --to-revisions <REVISION1>=50,<REVISION2>=50

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

כדי לבדוק את הפונקציה, אפשר להיכנס לכתובת ה-URL הציבורית שלה (באמצעות curl או ישירות בדפדפן).

curl -H "Authorization: bearer $(gcloud auth print-identity-token)" $SERVICE_URL

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

<html><body style="background-color:tan;"><div><p>Hello traffic-splitting-gcf-00006-qoq</p></div></body></html>

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

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

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

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

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

# update the env var
BG_COLOR=beige

gcloud beta run deploy gradual-rollouts-gcf \
      --source . \
      --function helloWorld \
      --region $REGION \
      --no-allow-unauthenticated \
      --update-env-vars BG_COLOR=$BG_COLOR

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

# update the env var
BG_COLOR=beige

# deploy the function
gcloud functions deploy gradual-rollouts-gcf \
  --gen2 \
  --runtime nodejs20 \
  --entry-point helloHttp \
  --source . \
  --region $REGION \
  --trigger-http \
  --no-allow-unauthenticated \
  --update-env-vars BG_COLOR=$BG_COLOR

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

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

# get the revision name

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

# now set 100% traffic to that revision

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

יוצג פלט דומה לזה: Traffic: 100% gradual-rollouts-gcf2-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-gcf \
      --source . \
      --function helloWorld \
      --region $REGION \
      --no-allow-unauthenticated \
      --update-env-vars BG_COLOR=$BG_COLOR

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

# update color

BG_COLOR=lavender

# deploy the function that will not receive any traffic
gcloud functions deploy gradual-rollouts-gcf \
  --gen2 \
  --runtime nodejs20 \
  --entry-point helloHttp \
  --source . \
  --region $REGION \
  --trigger-http \
  --no-allow-unauthenticated \
  --update-env-vars BG_COLOR=$BG_COLOR \
  --tag $BG_COLOR

עכשיו מעדכנים את משתנה הסביבה SERVICE_URL כדי להשתמש בפונקציה gradual-rollouts-gcf

SERVICE_URL=$(gcloud run services describe gradual-rollouts-gcf --platform managed --region $REGION --format 'value(status.url)')

ועכשיו כשמבצעים curl לשירות

curl -H "Authorization: bearer $(gcloud auth print-identity-token)" -X GET $SERVICE_URL

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

<html><body style="background-color:beige;"><div><p>Hello from gradual-rollouts-gcf-24jan16-staging-2-00001-kop using color beige</p></div></body></html>

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

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

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

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

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

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

gcloud run deploy gradual-rollouts-gcf --image $IMAGE_URL --no-traffic --tag $BG_COLOR --region $REGION --no-allow-unauthenticated

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

The revision can be reached directly at https://lavender---gradual-rollouts-gcf-k6msmyp47q-lz.a.run.app

עכשיו אפשר להשתמש ב-curl ישירות לגרסה הזו

curl -H "Authorization: bearer $(gcloud auth print-identity-token)" -X GET <DIRECT_REVISION_URL>

והצבע סגול לבנדר יופיע בתוצאות:

<html><body style="background-color:lavender;"><div><p>Hello from gradual-rollouts-gcf-24jan16-00003-xik using color lavender</p></div></body></html>

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

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

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

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

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

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

Traffic:
  50% gradual-rollouts-gcf-00001-hos
  50% gradual-rollouts-gcf-00004-mum
        lavender: https://lavender---gradual-rollouts-gcf-k6msmyp47q-uc.a.run.app

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

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

ועכשיו כשנכנסים לכתובת ה-URL של שירות הפונקציה gradual-rollouts-gcf או מריצים curl,

curl -H "Authorization: bearer $(gcloud auth print-identity-token)" -X GET $SERVICE_URL

יוצג רק צבע לבנדר.

<html><body style="background-color:lavender;"><div><p>Hello gradual-rollouts-gcf-00004-mum</p></div></body></html>

5. רולבק

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

כדי לחזור לגרסה הקודמת (בז'):

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

ועכשיו, כשמבצעים curl או כשנכנסים לנקודת הקצה של כתובת ה-URL של הפונקציה,

curl -H "Authorization: bearer $(gcloud auth print-identity-token)" -X GET $SERVICE_URL

יוחזר הצבע בז'.

<html><body style="background-color:beige;"><div><p>Hello gradual-rollouts-gcf-00001-hos</p></div></body></html>

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

6. מעולה!

כל הכבוד, סיימתם את ה-Codelab!

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

מה נכלל

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

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

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

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

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

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