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
.