1. Introdução
Visão geral
Com as funções do Cloud Run, é possível especificar quais revisões vão receber tráfego e as porcentagens de tráfego recebidas por uma revisão. 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, você vai aprender a usar revisões para gerenciar o tráfego das suas funções 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 uma funçã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 uma função do Cloud Run. Por exemplo, siga as etapas para implantar uma função do Cloud Run e começar.
Ativar o Cloud Shell
- No Console do Cloud, clique em Ativar o Cloud Shell
.
Se esta for a primeira vez que você inicia o Cloud Shell, uma tela intermediária vai aparecer com a descrição dele. Se isso acontecer, clique em Continuar.
Leva apenas alguns instantes para provisionar e se conectar ao Cloud Shell.
Essa máquina virtual contém todas as ferramentas de desenvolvimento necessárias. Ela oferece um diretório principal persistente de 5 GB, além de ser executada no Google Cloud. Isso aprimora o desempenho e a autenticação da rede. Neste codelab, quase todo o trabalho pode ser feito com um navegador.
Depois de se conectar ao Cloud Shell, você vai ver que sua conta já está autenticada e que o projeto está configurado com o ID do seu projeto.
- Execute o seguinte comando no Cloud Shell para confirmar se a conta está autenticada:
gcloud auth list
Resposta ao comando
Credentialed Accounts
ACTIVE ACCOUNT
* <my_account>@<my_domain.com>
To set the active account, run:
$ gcloud config set account `ACCOUNT`
- Execute o comando a seguir no Cloud Shell para confirmar se o comando gcloud sabe sobre seu projeto:
gcloud config list project
Resposta ao comando
[core] project = <PROJECT_ID>
Se o projeto não estiver configurado, configure-o usando este comando:
gcloud config set project <PROJECT_ID>
Resposta ao comando
Updated property [core/project].
3. Divisão de tráfego
Este exemplo mostra como criar uma função que lê uma variável de ambiente de cor e responde com o nome da revisão usando essa cor de fundo.
Embora este codelab use node.js, é 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
Criar a função
Primeiro, crie um diretório para o código-fonte e use cd para acessar esse diretório.
mkdir revisions-gcf-codelab && cd $_
Em seguida, crie um arquivo package.json com o seguinte conteúdo:
{
"dependencies": {
"@google-cloud/functions-framework": "^3.0.0"
}
}
Em seguida, crie um arquivo de origem index.js com o seguinte conteúdo:
const functions = require('@google-cloud/functions-framework');
const BG_COLOR = process.env.BG_COLOR;
const K_REVISION = process.env.K_REVISION;
functions.http('helloWorld', (req, res) => {
res.writeHead(200, { 'Content-Type': 'text/html' });
res.end('<html><body style="background-color:' + BG_COLOR + ';"' + '><div><p>' + 'Hello from ' + K_REVISION + ' using color ' + BG_COLOR + '</p></div></body>' + '</html>');
});
Para implantar uma função do Cloud Run diretamente no Cloud Run, execute o seguinte comando:
gcloud beta run deploy traffic-splitting-gcf \
--source . \
--function helloWorld \
--region $REGION \
--no-allow-unauthenticated \
--set-env-vars BG_COLOR=$BG_COLOR
Se preferir implantar como um Cloud Functions (2ª geração), use o seguinte comando:
gcloud functions deploy traffic-splitting-gcf \ --gen2 \ --runtime=nodejs20 \ --region=$REGION \ --source=. \ --entry-point=helloWorld \ --trigger-http \ --no-allow-unauthenticated \ --set-env-vars BG_COLOR=$BG_COLOR
Para testar a função, faça curl no endpoint atual para ver a cor "darkseagreen" no HTML ou use o navegador para acessar o endpoint diretamente e conferir a cor de fundo.
SERVICE_URL=$(gcloud run services describe traffic-splitting-gcf --platform managed --region $REGION --format 'value(status.url)') curl -H "Authorization: bearer $(gcloud auth print-identity-token)" -X GET $SERVICE_URL
Agora implante uma segunda revisão com uma cor de plano de fundo marrom-claro.
Para implantar uma função do Cloud Run diretamente no Cloud Run, execute o seguinte comando:
# update the env var
BG_COLOR=tan
gcloud beta run deploy traffic-splitting-gcf \
--source . \
--function helloWorld \
--region $REGION \
--no-allow-unauthenticated \
--update-env-vars BG_COLOR=$BG_COLOR
Se preferir implantar como um Cloud Functions (2ª geração), use o seguinte comando:
# update the env var BG_COLOR=tan gcloud functions deploy traffic-splitting-gcf \ --gen2 \ --runtime nodejs20 \ --entry-point helloHttp \ --source . \ --region $REGION \ --trigger-http \ --no-allow-unauthenticated \ --update-env-vars BG_COLOR=$BG_COLOR
Agora, quando você usar curl no endpoint, a cor de fundo marrom-claro vai aparecer.
curl -H "Authorization: bearer $(gcloud auth print-identity-token)" -X GET $SERVICE_URL
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 traffic-splitting-gcf \ --region $REGION --format 'value(REVISION)'
Os resultados serão semelhantes aos exibidos abaixo:
traffic-splitting-gcf-00003-qoq traffic-splitting-gcf-00002-zag
É possível dividir o tráfego 50/50 entre as duas revisões executando o seguinte comando:
gcloud run services update-traffic traffic-splitting-gcf \ --region $REGION \ --to-revisions <REVISION1>=50,<REVISION2>=50
Testar a divisão de tráfego
Teste a função acessando o URL público dela (com curl ou diretamente no navegador).
curl -H "Authorization: bearer $(gcloud auth print-identity-token)" $SERVICE_URL
Metade do tempo, você 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-splitting-gcf-00006-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 da função do Cloud. 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 uma nova Função do Cloud.
Primeiro, defina a cor de fundo como beige e implante a função com o nome gradual-rollouts-gcf.
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-gcf \
--source . \
--function helloWorld \
--region $REGION \
--no-allow-unauthenticated \
--update-env-vars BG_COLOR=$BG_COLOR
Se preferir implantar como um Cloud Functions (2ª geração), use o seguinte comando:
# update the env var BG_COLOR=beige # deploy the function gcloud functions deploy gradual-rollouts-gcf \ --gen2 \ --runtime nodejs20 \ --entry-point helloHttp \ --source . \ --region $REGION \ --trigger-http \ --no-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 futuras implantações de funções do Cloud não recebam tráfego. Por padrão, o Cloud Functions 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-gcf \ --region $REGION --format 'value(REVISION)') # now set 100% traffic to that revision gcloud run services update-traffic gradual-rollouts-gcf --to-revisions=$BEIGE_REVISION=100 --region $REGION
Você vai ver uma saída semelhante a Traffic: 100% gradual-rollouts-gcf2-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-gcf \
--source . \
--function helloWorld \
--region $REGION \
--no-allow-unauthenticated \
--update-env-vars BG_COLOR=$BG_COLOR
Se preferir implantar como um Cloud Functions (2ª geração), use o seguinte comando:
# update color BG_COLOR=lavender # deploy the function that will not receive any traffic gcloud functions deploy gradual-rollouts-gcf \ --gen2 \ --runtime nodejs20 \ --entry-point helloHttp \ --source . \ --region $REGION \ --trigger-http \ --no-allow-unauthenticated \ --update-env-vars BG_COLOR=$BG_COLOR \ --tag $BG_COLOR
Agora, atualize a variável de ambiente SERVICE_URL para usar a função gradual-rollouts-gcf.
SERVICE_URL=$(gcloud run services describe gradual-rollouts-gcf --platform managed --region $REGION --format 'value(status.url)')
e agora, quando você faz o curl do serviço
curl -H "Authorization: bearer $(gcloud auth print-identity-token)" -X GET $SERVICE_URL
A cor bege vai aparecer, mesmo que a revisão mais recente implantada seja a lavanda.
<html><body style="background-color:beige;"><div><p>Hello from gradual-rollouts-gcf-24jan16-staging-2-00001-kop using color beige</p></div></body></html>
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, extraia o URL da imagem para essa revisão.
IMAGE_URL=$(gcloud run services describe gradual-rollouts-gcf --region $REGION --format 'value(IMAGE)')
Agora marque essa imagem com a cor associada.
gcloud run deploy gradual-rollouts-gcf --image $IMAGE_URL --no-traffic --tag $BG_COLOR --region $REGION --no-allow-unauthenticated
Você verá um resultado semelhante a este:
The revision can be reached directly at https://lavender---gradual-rollouts-gcf-k6msmyp47q-lz.a.run.app
Agora você pode fazer o curl dessa revisão diretamente
curl -H "Authorization: bearer $(gcloud auth print-identity-token)" -X GET <DIRECT_REVISION_URL>
e confira a cor lavanda nos resultados:
<html><body style="background-color:lavender;"><div><p>Hello from gradual-rollouts-gcf-24jan16-00003-xik using color lavender</p></div></body></html>
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-gcf --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-gcf --region $REGION --to-tags lavender=50
Você vai ver uma lista de quanto tráfego cada revisão está recebendo.
Traffic:
50% gradual-rollouts-gcf-00001-hos
50% gradual-rollouts-gcf-00004-mum
lavender: https://lavender---gradual-rollouts-gcf-k6msmyp47q-uc.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-gcf --region $REGION --to-tags lavender=100
Agora, quando você acessar ou usar curl no URL do serviço da função gradual-rollouts-gcf,
curl -H "Authorization: bearer $(gcloud auth print-identity-token)" -X GET $SERVICE_URL
você só vai ver lavanda.
<html><body style="background-color:lavender;"><div><p>Hello gradual-rollouts-gcf-00004-mum</p></div></body></html>
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-gcf --region $REGION --to-revisions $BEIGE_REVISION=100
e agora, quando você usar curl ou acessar o endpoint do URL da função,
curl -H "Authorization: bearer $(gcloud auth print-identity-token)" -X GET $SERVICE_URL
você vai ver a cor bege retornada.
<html><body style="background-color:beige;"><div><p>Hello gradual-rollouts-gcf-00001-hos</p></div></body></html>
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 uma funçã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 Functions no nível sem custo financeiro, exclua a função do Cloud Run ou o projeto criado na etapa 2.
Para excluir uma função do Cloud Run implantada no Cloud Run, acesse o Cloud Run no console do Cloud em https://console.cloud.google.com/functions/ e exclua as funções criadas neste codelab.
Para excluir as funções do Cloud Run implantadas como funções de 2ª geração, acesse o Cloud Functions no console do Cloud em https://console.cloud.google.com/functions/ 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.