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

1. מבוא

סקירה כללית

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

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

מה תלמדו

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

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

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

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

הפעלת Cloud Shell

  1. במסוף Cloud, לוחצים על Activate Cloud Shell d1264ca30785e435.png.

cb81e7c8e34bc8d.png

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

d95252b003979716.png

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

7833d5e1c5d18f54.png

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

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

  1. מריצים את הפקודה הבאה ב-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`
  1. מריצים את הפקודה הבאה ב-Cloud Shell כדי לוודא שפקודת gcloud מכירה את הפרויקט:
gcloud config list project

פלט הפקודה

[core]
project = <PROJECT_ID>

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

gcloud config set project <PROJECT_ID>

פלט הפקודה

Updated property [core/project].

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

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

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

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

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

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

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

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

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

כדי לפצל את התנועה בין הגרסאות בצבע ירוק כהה ובצבע חום, צריך למצוא את מזהי הגרסאות של שירותי 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

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

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 Function. מידע נוסף על השקות הדרגתיות זמין במסמכי התיעוד.

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

קודם כול, מגדירים את צבע הרקע כ-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

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

קודם כול, נגדיר שהגרסה הנוכחית (beige) תקבל 100% מהתנועה. כך תוכלו לוודא שלא תהיה תנועה בפלטפורמות Cloud Functions שתפרסו בעתיד. כברירת מחדל, Cloud Functions מגדיר 100% מהתנועה לגרסה עם הדגל latest. אם מציינים ידנית שגרסת beige הנוכחית תקבל את כל התנועה, גרסת השגיאה עם הדגל 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% מהתנועה. למרות שהגרסה עברה את בדיקות התקינות, עדיין כדאי לוודא שבגרסה הזו נעשה שימוש בצבע הלבן-סגול של הרקע.

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

יופיע הערך beige.

<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/ ומוחקים את הפונקציות שיצרתם בקודלאב הזה.

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

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