Używanie wersji w Cloud Run do podziału ruchu, wdrażania stopniowego i przywracania

Używanie wersji w Cloud Run do podziału ruchu, wdrażania stopniowego i przywracania

Informacje o tym ćwiczeniu (w Codelabs)

subjectOstatnia aktualizacja: kwi 5, 2025
account_circleDokument stworzony przez pracownika Google

1. Wprowadzenie

Wersje Cloud Run umożliwiają określenie, które wersje mają otrzymywać ruch i jaki odsetek ruchu ma być wysyłany do każdej z nich. W sekcji Wersje możesz przywrócić poprzednią wersję, stopniowo wdrażać nową wersję i dzielić ruch między wiele wersji.

Te laboratoria kodu pokazują, jak używać wersji do zarządzania ruchem w usłudze Cloud Run. Więcej informacji o wersjach znajdziesz w dokumentacji Cloud Run.

  • Jak podzielić ruch między co najmniej 2 wersje usługi Cloud Run
  • Jak stopniowo wdrażać nową wersję
  • Jak przywrócić poprzednią wersję

2. Konfiguracja i wymagania

Wymagania wstępne

  • Zaloguj się w konsoli Cloud.
  • Usługa Cloud Run została wcześniej wdrożona. Aby rozpocząć, możesz na przykład postępować zgodnie z instrukcjami wdrażania usługi Cloud Run.

Ustawianie zmiennych środowiskowych

Możesz ustawić zmienne środowiskowe, których będziesz używać w tym ćwiczeniu.

PROJECT_ID=YOUR-PROJECT-ID
REGION
=YOUR_REGION

BG_COLOR
=darkseagreen
SERVICE_NAME
=traffic-revisions-color
AR_REPO
=traffic-revisions-color-repo

Tworzenie repozytorium Artifact Registry dla usługi

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

3. Dzielenie ruchu

Ten przykład pokazuje, jak utworzyć usługę Cloud Run, która odczytuje zmienną środowiskową koloru i zwróci nazwę wersji, używając tego koloru tła.

Ten warsztat kodowania korzysta z języka Python, ale możesz użyć dowolnego środowiska wykonawczego.

Ustawianie zmiennych środowiskowych

Możesz ustawić zmienne środowiskowe, których będziesz używać w tym ćwiczeniu.

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

Tworzenie usługi

Najpierw utwórz katalog dla kodu źródłowego i przejdź do niego.

mkdir traffic-revisions-codelab && cd $_

Następnie utwórz plik main.py z tą treścią:

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)

Następnie utwórz plik requirements.txt z tą treścią:

Flask>=2.0.0
gunicorn>=20.0.0

Na koniec utwórz 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"]

Utwórz obraz w Artifact Registry za pomocą pakietów kompilacji za pomocą Cloud Build:

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

A pierwszą wersję wdróż do Cloud Run z kolorem 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

Aby przetestować usługę, otwórz punkt końcowy bezpośrednio w przeglądarce, aby zobaczyć kolor tła w ciemnozielonym odcieniu morza.

Teraz wprowadź drugą wersję z brązowym tłem.

# 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

Gdy odświeżysz stronę, zobaczysz brązowy kolor tła.

Podział ruchu 50–50

Aby podzielić ruch na wersje ciemnozielone i brązowe, musisz znaleźć identyfikatory wersji docelowych usług Cloud Run. Aby wyświetlić identyfikatory wersji, uruchom to polecenie:

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

Powinny pojawić się wyniki podobne do tych

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

Możesz podzielić ruch na 2 wersje po 50%, uruchamiając to polecenie:

gcloud run services update-traffic $SERVICE_NAME \
  --region $REGION \
  --to-revisions YOUR_REVISION_1=50,YOUR_REVISION_2=50

Testowanie podziału ruchu

Aby przetestować usługę, odśwież stronę w przeglądarce.

W połowie przypadków powinna się wyświetlać wersja w kolorze ciemnozielonym, a w drugiej połowie – w kolorze beżowym. W wyniku zobaczysz też nazwę poprawki, np.

<html><body style="background-color:tan;"><div><p>Hello traffic-revisions-color-00003-qoq</p></div></body></html>

4. Wdrożenia stopniowe

Z tej sekcji dowiesz się, jak stopniowo wdrażać zmiany w nowej wersji usługi Cloud. Więcej informacji o stopniowym wdrażaniu znajdziesz w dokumentacji.

Użyjesz tego samego kodu co w poprzedniej sekcji, ale wdrożysz go jako nową usługę Cloud Run.

Najpierw ustaw kolor tła na beige i wdróż funkcję o nazwie gradual-rollouts-colors.

Aby wdrożyć funkcję Cloud Run bezpośrednio w Cloud Run, uruchom to polecenie:

# 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

Załóżmy, że chcemy stopniowo wdrażać nową wersję z kolorem tła lawendowym.

Najpierw ustaw bieżącą wersję na beżowy, aby otrzymywała 100% ruchu. Dzięki temu przyszłe wersje nie będą generować ruchu. Domyślnie Cloud Run przypisuje 100% ruchu do wersji z flagą latest. Jeśli ręcznie określisz, że bieżąca wersja w kolorze beżowym ma otrzymywać cały ruch, wersja z flagą latest nie będzie już otrzymywać 100% ruchu. Zapoznaj się z dokumentacją.

# 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

Dane wyjściowe będą wyglądać podobnie do Traffic: 100% radual-rollouts-colors-00001-yox

Możesz teraz wdrożyć nową wersję, która nie będzie otrzymywać żadnego ruchu. Zamiast wprowadzać zmiany w kodzie, możesz zaktualizować zmienną środowiskową BG_COLOR w ramach tej wersji.

Aby wdrożyć funkcję Cloud Run bezpośrednio w Cloud Run, uruchom to polecenie:

# 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

Gdy teraz otworzysz witrynę w przeglądarce, zobaczysz kolor beżowy, mimo że ostatnio wdrożona wersja była w kolorze lawendowym.

Testowanie wersji, która obsługuje 0% ruchu

Załóżmy, że udało Ci się zweryfikować, że Twoja wersja została wdrożona i generuje 0% ruchu. Mimo że kontrola stanu się powiodła, chcesz sprawdzić, czy ta wersja używa koloru lawendy na tle.

Aby przetestować wersję lavender, możesz zastosować do niej tag. Tagowanie umożliwia bezpośrednie testowanie nowej wersji pod określonym adresem URL bez wysyłania do niej ruchu.

Najpierw pobierz adres URL obrazu z najnowszej wersji (w kolorze lawendowym).

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

Teraz oznacz obraz powiązanym kolorem.

gcloud run deploy gradual-rollouts-colors --image $IMAGE_URL_LAVENDER --no-traffic --tag $BG_COLOR --region $REGION

Dane wyjściowe będą wyglądać tak:

The revision can be reached directly at https://lavender---gradual-rollouts-colors-<hash>-<region>.a.run.app

Gdy otworzysz adres URL konkretnej wersji, zobaczysz kolor lawendowy.

Stopniowe zwiększanie ruchu

Teraz możesz zacząć wysyłać ruch do wersji o nazwie lavender. Przykład poniżej pokazuje, jak wysłać 1% ruchu do lavender.

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

Aby wysłać 50% ruchu do lavender, możesz użyć tego samego polecenia, ale z wartością 50%.

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

Powinna się wyświetlić lista z danymi o ruchu na poszczególnych wersjach.

Traffic:
  50% gradual-rollouts-colors-00001-hos
  50% gradual-rollouts-colors-00004-mum
        lavender: https://lavender---gradual-rollouts-colors-<hash>-<region>.a.run.app

Gdy będziesz gotowy do wdrożenia koloru lawendowego, możesz ustawić go na 100%, aby zastąpił kolor beżowy.

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

Gdy teraz otworzysz stronę, zobaczysz tylko lawendę.

5. Przywrócone

Załóżmy, że otrzymaliśmy wczesne opinie dotyczące UX, które wskazują, że klienci wolą beż niż lawendę, i musisz przywrócić beż.

Możesz przywrócić poprzednią wersję (beżową), wykonując to polecenie:

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

Gdy teraz otworzysz witrynę, zobaczysz, że kolor tła jest beżowy.

Więcej informacji o przywracaniu znajdziesz w dokumentacji.

6. Gratulacje!

Gratulujemy ukończenia ćwiczeń.

Zalecamy zapoznanie się z dokumentacją dotyczącą wdrażania, cofania zmian i przenoszenia ruchu.

Omówione zagadnienia

  • Jak podzielić ruch między co najmniej 2 wersje usługi Cloud Run
  • Jak stopniowo wdrażać nową wersję
  • Jak przywrócić poprzednią wersję

7. Czyszczenie danych

Aby uniknąć przypadkowych opłat (na przykład, jeśli ta funkcja Cloud Run zostanie przypadkowo wywołana więcej razy niż miesięczny limit wywołań funkcji Cloud Run w ramach bezpłatnego poziomu), możesz usunąć usługę Cloud Run lub projekt utworzony w kroku 2.

Aby usunąć usługę Cloud Run, otwórz Cloud Run w Cloud Console (https://console.cloud.google.com/run/) i usuń funkcje utworzone w tym samouczku.

Jeśli chcesz usunąć cały projekt, otwórz stronę https://console.cloud.google.com/cloud-resource-manager, wybierz projekt utworzony w kroku 2 i kliknij Usuń. Jeśli usuniesz projekt, musisz zmienić projekty w Cloud SDK. Aby wyświetlić listę wszystkich dostępnych projektów, uruchom gcloud projects list.