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

۱. مقدمه

نمای کلی

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

این آزمایشگاه کد به شما نشان می‌دهد که چگونه از بازبینی‌ها برای مدیریت ترافیک سرویس Cloud Run خود استفاده کنید. می‌توانید در مستندات Cloud Run درباره بازبینی‌ها اطلاعات بیشتری کسب کنید.

آنچه یاد خواهید گرفت

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

۲. تنظیمات و الزامات

پیش‌نیازها

  • شما وارد کنسول ابری شده‌اید.
  • شما قبلاً یک سرویس 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

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

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

اگرچه این آزمایشگاه کد از پایتون استفاده می‌کند، شما می‌توانید از هر محیط اجرایی (runtime) استفاده کنید.

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

شما می‌توانید متغیرهای محیطی که در سراسر این آزمایشگاه کد استفاده خواهند شد را تنظیم کنید.

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

با استفاده از Cloud Build، تصویر را در رجیستری Artifact با استفاده از 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

برای آزمایش سرویس، می‌توانید نقطه پایانی را مستقیماً در مرورگر وب خود باز کنید تا رنگ پس‌زمینه را به رنگ سبز دریایی تیره ببینید.

حالا یک نسخه دوم با رنگ پس‌زمینه قهوه‌ای مایل به زرد (tan) ایجاد کنید. 

# 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

حالا وقتی وب‌سایت را رفرش می‌کنید، رنگ پس‌زمینه‌ی قهوه‌ای مایل به زرد را خواهید دید.

ترافیک را ۵۰-۵۰ تقسیم کنید

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

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

شما باید نتایجی مشابه نتایج زیر را ببینید 

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

شما می‌توانید با اجرای دستور زیر به همراه نسخه‌های خود، ترافیک را به صورت ۵۰/۵۰ بین دو نسخه تقسیم کنید: 

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>

۴. عرضه تدریجی

در این بخش، یاد خواهید گرفت که چگونه تغییرات را به تدریج در یک نسخه جدید سرویس ابری اعمال کنید. می‌توانید اطلاعات بیشتری در مورد اعمال تدریجی تغییرات را در مستندات کسب کنید.

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

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

ابتدا، بیایید نسخه فعلی بژ را طوری تنظیم کنیم که ۱۰۰٪ ترافیک را دریافت کند. این کار تضمین می‌کند که نسخه‌های آینده شما هیچ ترافیکی دریافت نکنند. به طور پیش‌فرض، Cloud Run 100٪ ترافیک را به نسخه‌ای با latest پرچم اختصاص می‌دهد. با تعیین دستی اینکه این نسخه فعلی بژ باید تمام ترافیک را دریافت کند، نسخه‌ای با latest پرچم دیگر ۱۰۰٪ ترافیک دریافت نخواهد کرد. به مستندات مراجعه کنید. 

# 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٪ است. حتی اگر بررسی‌های سلامت را پشت سر گذاشته باشد، هنوز می‌خواهید تأیید کنید که این نسخه از رنگ پس‌زمینه بنفش کمرنگ استفاده می‌کند.

برای آزمایش نسخه بنفش، می‌توانید یک برچسب به آن نسخه اعمال کنید . برچسب‌گذاری به شما امکان می‌دهد نسخه جدید را مستقیماً در یک URL خاص، بدون ایجاد ترافیک، آزمایش کنید.

ابتدا، آدرس اینترنتی تصویر مربوط به آخرین نسخه (که lavender است) را دریافت کنید. 

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 را شروع کنید. مثال زیر نحوه ارسال ۱٪ از ترافیک به lavender را نشان می‌دهد. 

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

برای ارسال ۵۰٪ ترافیک به lavender، می‌توانید از همان دستور استفاده کنید، اما به جای آن ۵۰٪ را مشخص کنید. 

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

وقتی آماده شدید که رنگ اسطوخودوس را به طور کامل استفاده کنید، می‌توانید اسطوخودوس را روی ۱۰۰٪ تنظیم کنید تا جایگزین رنگ بژ شود. 

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

و حالا وقتی از وب‌سایت بازدید می‌کنید، فقط اسطوخودوس خواهید دید.

۵. عقبگردها

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

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

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

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

می‌توانید در مورد rollbackها در مستندات بیشتر بیاموزید.

۶. تبریک می‌گویم!

تبریک می‌گویم که آزمایشگاه کد را تمام کردید!

توصیه می‌کنیم مستندات مربوط به انتشارهای جدید، بازگرداندن‌ها و مهاجرت ترافیک را بررسی کنید.

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

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

۷. تمیز کردن

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

برای حذف یک سرویس Cloud Run، به Cloud Run در کنسول ابری به آدرس https://console.cloud.google.com/run/ بروید و توابعی را که در این آزمایشگاه کد ایجاد کرده‌اید، حذف کنید.

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