在 Cloud Run 中使用修訂版本來拆分流量、逐步推出及復原

在 Cloud Run 中使用修訂版本來拆分流量、逐步推出及復原

程式碼研究室簡介

subject上次更新時間：4月 5, 2025
account_circle作者：Google 員工

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

建立服務

首先，請建立原始碼目錄，然後切換至該目錄。

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，並使用 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 服務的修訂版本 ID。您可以執行下列指令查看修訂版本 ID：

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 Service 修訂版本。如要進一步瞭解漸進式推出功能，請參閱說明文件。

您將使用與上一節相同的程式碼，但會將其部署為新的 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% 的流量。即使已通過健康狀態檢查，您仍應驗證此修訂版本是否使用薰衣草背景顏色。

如要測試薰衣草修訂版本，您可以將標記套用至該修訂版本。標記可讓您直接在特定網址中測試新修訂版本，而不提供流量。

首先，取得最新修訂版本 (即薰衣草) 的圖片網址。

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

如今，當您造訪該修訂版本網址時，就會看到淡紫色。

逐步增加流量

您現在可以開始將流量傳送至薰衣草修訂版本。以下範例說明如何將 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. 恭喜！

恭喜您完成程式碼研究室！

建議您參閱推出、回溯和流量遷移相關說明文件

涵蓋內容

  • 如何在 Cloud Run 服務的兩個或多個修訂版本之間拆分流量
  • 如何逐步推出新修訂版本
  • 如何復原為先前的修訂版本

7. 清除所用資源

為避免產生意外費用 (例如，如果這項 Cloud Run 函式不小心叫用次數超過 免費等級的 Cloud Run 叫用次數配額)，您可以刪除 Cloud Run 服務，或是刪除在步驟 2 中建立的專案。

如要刪除 Cloud Run 服務，請前往 Cloud 控制台中的 Cloud Run (網址：https://console.cloud.google.com/run/)，然後刪除您在本程式碼研究室中建立的函式。

如果您選擇刪除整個專案，可以前往 https://console.cloud.google.com/cloud-resource-manager，選取您在步驟 2 中建立的專案，然後選擇「Delete」(刪除)。如果您刪除專案，就必須在 Cloud SDK 中變更專案。您可以執行 gcloud projects list 來查看所有可用專案的清單。

bug_report 回報錯誤