استفاده از ویرایش‌ها در Cloud Run برای تقسیم ترافیک، انتشار تدریجی و بازگشت

استفاده از ویرایش‌ها در Cloud Run برای تقسیم ترافیک، انتشار تدریجی و بازگشت

درباره این codelab

subjectآخرین به‌روزرسانی: آوریل ۵, ۲۰۲۵
account_circleنویسنده: یکی از کارمندان Google

1. مقدمه

ویرایش‌های Cloud Run به شما این امکان را می‌دهد که مشخص کنید کدام نسخه‌ها باید ترافیک دریافت کنند و چه درصدی از ترافیک برای هر نسخه ارسال شود. Revisions به شما امکان می‌دهد به یک نسخه قبلی برگردید، به تدریج یک ویرایش را منتشر کنید و ترافیک را بین چندین ویرایش تقسیم کنید.

این کدها به شما نشان می‌دهند که چگونه از ویرایش‌ها برای مدیریت ترافیک سرویس 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

یک مخزن رجیستری مصنوع برای سرویس ایجاد کنید

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

3. تقسیم ترافیک

این نمونه به شما نشان می دهد که چگونه یک سرویس Cloud Run ایجاد کنید که یک متغیر محیط رنگی را می خواند و با استفاده از آن رنگ پس زمینه با نام ویرایش پاسخ می دهد.

اگرچه این کد لبه از پایتون استفاده می کند، اما می توانید از هر زمان اجرا استفاده کنید.

تنظیم متغیرهای محیطی

می توانید متغیرهای محیطی را تنظیم کنید که در سراسر این کد لبه مورد استفاده قرار می گیرند.

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

سرویس را ایجاد کنید

ابتدا یک دایرکتوری برای کد منبع و سی دی در آن دایرکتوری ایجاد کنید.

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

با استفاده از Cloud Build تصویر را در Artifact Registry با استفاده از Buildpacks ایجاد کنید:

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

و اولین نسخه را با رنگ سبز تیره در Cloud Run اجرا کنید:

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

حال فرض کنید می خواهیم به تدریج یک ویرایش جدید با رنگ پس زمینه اسطوخودوس ارائه کنیم.

ابتدا، اجازه دهید نسخه فعلی بژ را برای دریافت ترافیک 100٪ تنظیم کنیم. این اطمینان حاصل می کند که ویرایش های بعدی شما هیچ ترافیکی دریافت نمی کند. به‌طور پیش‌فرض، Cloud Run ترافیک 100% را روی نسخه با latest پرچم تنظیم می‌کند. با تعیین دستی اینکه این نسخه بژ نسخه فعلی باید تمام ترافیک را دریافت کند، نسخه با 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٪ را ارائه می دهد. حتی اگر بررسی‌های سلامتی را پشت سر گذاشته باشد، همچنان می‌خواهید تأیید کنید که این نسخه از رنگ پس‌زمینه اسطوخودوس استفاده می‌کند.

برای آزمایش بازبینی اسطوخودوس، می‌توانید یک برچسب روی آن نسخه اعمال کنید . برچسب‌گذاری به شما امکان می‌دهد تا نسخه جدید را مستقیماً در یک 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 نسخه خاص بازدید می کنید، رنگ اسطوخودوس را خواهید دید.

به تدریج افزایش ترافیک

اکنون، می توانید شروع به ارسال ترافیک به نسخه اسطوخودوس کنید. مثال زیر نحوه ارسال 1% ترافیک را به اسطوخودوس نشان می دهد. 

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

برای ارسال 50 درصد ترافیک به اسطوخودوس، می توانید از همین دستور استفاده کنید، اما به جای آن 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. بازگشت به عقب

فرض کنید بازخورد اولیه UX وارد شده است که نشان می دهد مشتریان رنگ بژ را به اسطوخودوس ترجیح می دهند و شما باید به رنگ بژ برگردید.

با اجرای این دستور می توانید به نسخه قبلی (بژ) برگردید: 

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

و اکنون وقتی از وب سایت بازدید می کنید، رنگ بژ را به عنوان رنگ پس زمینه خواهید دید.

می‌توانید در اسناد اطلاعات بیشتری درباره بازگشت به عقب بیاموزید.

6. تبریک می گویم!

برای تکمیل کد لبه تبریک می گویم!

توصیه می‌کنیم اسناد مربوط به عرضه‌ها، بازگشت‌ها و انتقال ترافیک را مرور کنید

آنچه را پوشش داده ایم

  • نحوه تقسیم ترافیک بین دو یا چند نسخه برای یک سرویس Cloud Run
  • چگونه یک ویرایش جدید را به تدریج ارائه کنیم
  • نحوه بازگشت به نسخه قبلی

7. پاک کن

برای جلوگیری از هزینه‌های غیرعمدی، (به عنوان مثال، اگر این تابع Cloud Run به طور ناخواسته بیشتر از تخصیص فراخوانی ماهانه Cloud Run در ردیف رایگان فراخوانی شود)، می‌توانید سرویس Cloud Run را حذف کنید یا پروژه‌ای را که در مرحله 2 ایجاد کرده‌اید حذف کنید.

برای حذف یک سرویس Cloud Run، به Cloud Run در Cloud Console در https://console.cloud.google.com/run/ بروید و توابعی را که در این Codelab ایجاد کرده اید حذف کنید.

اگر تصمیم به حذف کل پروژه دارید، می‌توانید به https://console.cloud.google.com/cloud-resource-manager بروید، پروژه‌ای را که در مرحله ۲ ایجاد کرده‌اید انتخاب کنید و حذف را انتخاب کنید. اگر پروژه را حذف کنید، باید پروژه ها را در Cloud SDK خود تغییر دهید. با اجرای gcloud projects list می توانید لیست تمام پروژه های موجود را مشاهده کنید.

bug_report گزارش اشتباه