1. Introdução
Visão geral
Com as revisões do Cloud Run, é possível especificar quais revisões vão receber tráfego e qual porcentagem de tráfego será enviada para cada uma delas. Com as revisões, é possível fazer reversão para uma revisão anterior, lançar gradualmente uma revisão e dividir o tráfego entre várias revisões.
Neste codelab, mostramos 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 implementar 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 as etapas para implantar um serviço do Cloud Run e começar.
Definir variáveis de ambiente
Você pode definir variáveis de ambiente que serão usadas ao longo deste 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 segundo plano.
Embora este codelab use Python, é possível usar qualquer ambiente de execução.
Definir variáveis de ambiente
Você pode definir variáveis de ambiente que serão usadas ao longo deste 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 use cd para acessar esse diretório.
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 Buildpacks com o Cloud Build:
gcloud builds submit \
--tag $REGION-docker.pkg.dev/$PROJECT_ID/$AR_REPO/$SERVICE_NAME
Implante a primeira revisão no Cloud Run com a cor 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
Para testar o serviço, abra o endpoint diretamente no navegador da Web e confira a cor de plano de fundo como verde-mar escuro.
Agora implante uma segunda revisão com uma cor de plano de fundo marrom-claro.
# 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, quando você atualizar o site, vai ver a cor de fundo marrom-claro.
Dividir o tráfego em 50/50
Para dividir o tráfego entre as revisões verde-marinho e marrom, encontre os IDs de revisão dos serviços do Cloud Run subjacentes. Para ver os IDs de revisão, execute este comando:
gcloud run revisions list --service $SERVICE_NAME \ --region $REGION --format 'value(REVISION)'
Os resultados serão semelhantes aos exibidos abaixo:
traffic-revisions-color-00003-qoq traffic-revisions-color-00002-zag
É possível dividir o tráfego 50/50 entre as duas revisões executando o seguinte comando 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.
Metade do tempo, você vai ver a revisão verde-marinho escuro e, na outra metade, a revisão 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 gradualmente as mudanças em uma nova revisão do Cloud Service. Saiba mais sobre os lançamentos 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
Agora, digamos que queremos lançar gradualmente uma nova revisão com a cor de fundo lavanda.
Primeiro, vamos definir a revisão atual 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 a revisão atual bege deve 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ê acessar o site no navegador, a cor bege vai aparecer, mesmo que a revisão mais recente tenha sido a lavanda.
Testar uma revisão que atende a 0% do tráfego
Suponha que você tenha verificado que a revisão foi implantada com sucesso e está veiculando 0% do tráfego. Mesmo que ela tenha passado nas verificações de integridade, ainda é preciso verificar se essa revisão está usando a cor de fundo lavanda.
Para testar a revisão 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, pegue o URL da imagem da revisão mais recente (que é lavanda).
IMAGE_URL_LAVENDER=$(gcloud run services describe gradual-rollouts-colors --region $REGION --format 'value(IMAGE)')
Agora marque essa 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.
Aumento gradual do tráfego
Agora você pode começar a enviar tráfego para a revisão "lavender". O exemplo abaixo mostra como enviar 1% do tráfego para o lavanda.
gcloud run services update-traffic gradual-rollouts-colors --region $REGION --to-tags lavender=1
Para enviar 50% do tráfego para a cor lavanda, use o mesmo comando, mas especifique 50% em vez de 100%.
gcloud run services update-traffic gradual-rollouts-colors --region $REGION --to-tags lavender=50
Você vai ver uma lista de quanto tráfego 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 a porcentagem dela como 100% para substituir o bege.
gcloud run services update-traffic gradual-rollouts-colors --region $REGION --to-tags lavender=100
Agora, quando você acessar o site, só vai ver a cor lavanda.
5. Reversões
Suponha que você tenha recebido feedback antecipado sobre a UX indicando que os clientes preferem bege a lavanda e que você precisa reverter para bege.
É possível 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, quando você acessar o site, vai ver o bege como cor de plano de fundo.
Saiba mais sobre reversões na documentação.
6. Parabéns!
Parabéns por concluir o codelab!
Recomendamos consultar a documentação sobre lançamentos, reversões 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 implementar 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 mais vezes do que sua alocação mensal de invocações 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 todo o projeto, 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 de projeto no SDK Cloud. Para conferir a lista de todos os projetos disponíveis, execute gcloud projects list.