Como usar revisões no Cloud Run para divisão de tráfego, lançamentos graduais e reversões

1. Introdução

Visão geral

As revisões do Cloud Run permitem especificar quais revisões devem receber tráfego e qual porcentagem de tráfego enviar para cada revisão. Com as revisões, você pode reverter para uma revisão anterior, lançar gradualmente uma revisão e dividir o tráfego entre várias revisões.

Estes codelabs mostram como usar revisões para gerenciar o tráfego do seu serviço do Cloud Run. Saiba mais sobre revisões na documentação do Cloud Run.

O que você vai aprender

  • Como dividir o tráfego entre duas ou mais revisões de um serviço do Cloud Run
  • Como lançar uma nova revisão gradualmente
  • Como reverter para uma revisão anterior

2. Configuração e requisitos

Pré-requisitos

  • Você fez login no console do Cloud.
  • Você já implantou um serviço do Cloud Run. Por exemplo, siga o processo de implantação de um serviço do Cloud Run para começar.

Definir variáveis de ambiente

Você pode definir variáveis de ambiente que serão usadas neste codelab.

PROJECT_ID=YOUR-PROJECT-ID
REGION=YOUR_REGION

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

Criar um repositório do Artifact Registry para o serviço

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

3. Divisão de tráfego

Este exemplo mostra como criar um serviço do Cloud Run que lê uma variável de ambiente de cor e responde com o nome da revisão usando essa cor de plano de fundo.

Embora este codelab use Python, você pode usar qualquer ambiente de execução.

Definir variáveis de ambiente

Você pode definir variáveis de ambiente que serão usadas neste codelab.

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

Criar o serviço

Primeiro, crie um diretório para o código-fonte e entre nele.

mkdir traffic-revisions-codelab && cd $_

Em seguida, crie um arquivo main.py com o seguinte conteúdo:

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)

Em seguida, crie um arquivo requirements.txt com o seguinte conteúdo:

Flask>=2.0.0
gunicorn>=20.0.0

Por fim, crie um 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"]

Crie a imagem no Artifact Registry usando o Buildpacks com o Cloud Build:

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

E implante a primeira revisão no Cloud Run com uma cor verde-esverdeado-escuro:

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

Para testar o serviço, abra o endpoint diretamente no navegador da Web para ver a cor de fundo como verde-mar escuro.

Agora implante uma segunda revisão com uma cor de plano de fundo bege.

# 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

Agora, ao atualizar o site, você vai ver a cor de plano de fundo bege.

Dividir o tráfego em 50-50

Para dividir o tráfego entre as revisões verde-escuro e marrom claro, você precisa encontrar os IDs de revisão dos serviços do Cloud Run subjacentes. Para conferir os IDs de revisão, execute este comando:

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

Você vai encontrar resultados semelhantes aos abaixo:

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

Você pode dividir o tráfego 50/50 entre as duas revisões executando o comando a seguir com suas revisões:

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

Testar a divisão de tráfego

Para testar o serviço, atualize a página no navegador.

Na metade das vezes, você vai ver a revisão em verde-escuro e, na outra metade, a revisão em marrom claro. O nome da revisão também vai aparecer na saída, por exemplo:

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

4. Lançamentos graduais

Nesta seção, você vai aprender a lançar mudanças gradualmente em uma nova revisão do Cloud Service. Saiba mais sobre as implantações graduais na documentação.

Você vai usar o mesmo código da seção anterior, mas vai implantá-lo como um novo serviço do Cloud Run.

Primeiro, defina a cor de fundo como beige e implante a função com o nome gradual-rollouts-colors.

Para implantar uma função do Cloud Run diretamente no Cloud Run, execute o seguinte comando:

# 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

Digamos que queremos lançar gradualmente uma nova revisão com a cor de fundo lilás.

Primeiro, vamos definir a revisão atual como bege para receber 100% do tráfego. Isso garante que suas revisões futuras não recebam tráfego. Por padrão, o Cloud Run define 100% do tráfego para a revisão com a flag latest. Ao especificar manualmente que essa revisão atual precisa receber todo o tráfego, a revisão com a flag latest não vai mais receber 100% do tráfego. Consulte a documentação.

# 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

Você vai ver uma saída semelhante a Traffic: 100% radual-rollouts-colors-00001-yox

Agora você pode implantar uma nova revisão que não vai receber tráfego. Em vez de fazer mudanças no código, atualize a variável de ambiente BG_COLOR para essa revisão.

Para implantar uma função do Cloud Run diretamente no Cloud Run, execute o seguinte comando:

# 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

Agora, quando você visitar o site no navegador, vai aparecer a cor bege, mesmo que a lavanda tenha sido a revisão implantada mais recentemente.

Testar uma revisão que exibe 0% do tráfego

Suponha que você tenha verificado que a revisão foi implantada e que ela está veiculando 0% do tráfego. Mesmo que tenha passado nas verificações de integridade, você ainda precisa verificar se essa revisão está usando a cor de fundo lilás.

Para testar a revisão de lavanda, aplique uma tag a ela. Com as tags, é possível testar diretamente a nova revisão em um URL específico, sem veicular o tráfego.

Primeiro, acesse o URL da imagem da revisão mais recente (que é a cor lavanda).

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

Agora marque a imagem com a cor associada.

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

Você verá um resultado semelhante a este:

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

Agora, quando você acessar esse URL de revisão específico, a cor lavanda vai aparecer.

Aumentar o tráfego gradualmente

Agora, você pode começar a enviar tráfego para a revisão de lavanda. O exemplo abaixo mostra como enviar 1% do tráfego para a cor lavanda.

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

Para enviar 50% do tráfego para "lavanda", use o mesmo comando, mas especifique 50%.

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

Você vai encontrar uma lista com a quantidade de tráfego que cada revisão está recebendo.

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

Quando estiver tudo pronto para lançar a cor lavanda, defina o valor dela como 100% para substituir o bege.

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

e agora, quando você visitar o site, só vai aparecer a cor lavanda.

5. Reversões

Suponha que o feedback inicial de UX tenha indicado que os clientes preferem o bege ao lilás, e você precisa reverter para o bege.

Você pode reverter para a revisão anterior (bege) executando este comando:

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

e agora, ao acessar o site, você vai ver a cor bege como plano de fundo.

Saiba mais sobre reversões na documentação.

6. Parabéns!

Parabéns por concluir o codelab.

Recomendamos a leitura da documentação sobre lançamentos, reversão e migração de tráfego.

O que vimos

  • Como dividir o tráfego entre duas ou mais revisões de um serviço do Cloud Run
  • Como lançar uma nova revisão gradualmente
  • Como reverter para uma revisão anterior

7. Limpar

Para evitar cobranças acidentais (por exemplo, se essa função do Cloud Run for invocada acidentalmente mais vezes do que sua alocação mensal de invocação do Cloud Run no nível sem custo financeiro), exclua o serviço do Cloud Run ou o projeto criado na etapa 2.

Para excluir um serviço do Cloud Run, acesse o Cloud Run no Console do Cloud em https://console.cloud.google.com/run/ e exclua as funções criadas neste codelab.

Se você quiser excluir o projeto inteiro, acesse https://console.cloud.google.com/cloud-resource-manager, selecione o projeto criado na etapa 2 e escolha "Excluir". Se você excluir o projeto, vai precisar mudar os projetos no Cloud SDK. Para conferir a lista de todos os projetos disponíveis, execute gcloud projects list.