1. Introdução
Visão geral
As funções do Cloud Run permitem especificar quais revisões devem receber tráfego e as porcentagens de tráfego recebidas por uma 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.
Este codelab mostra como usar revisões para gerenciar o tráfego para suas funções do Cloud Run. Saiba mais sobre as 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 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 uma função do Cloud Run. Por exemplo, siga a implantação de uma função do Cloud Run para começar.
Ativar o Cloud Shell
- No Console do Cloud, clique em Ativar o Cloud Shell
.
Se você estiver iniciando o Cloud Shell pela primeira vez, verá uma tela intermediária com a descrição dele. Se aparecer uma tela intermediária, 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. Grande parte do trabalho neste codelab, se não todo, pode ser feito em um navegador.
Depois de se conectar ao Cloud Shell, você verá sua autenticação e o projeto estará 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 seguinte comando no Cloud Shell para confirmar que 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 plano de fundo.
Embora este codelab use node.js, 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
Criar a função
Primeiro, crie um diretório para o código-fonte e entre nele.
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 você preferir implantar como um Cloud Functions de 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, você pode fazer o curl do endpoint atual para ver a cor verde-escuro no html ou usar o navegador para acessar o endpoint diretamente e conferir a cor de plano 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 bege.
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 você preferir implantar como um Cloud Functions de 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ê enrolar o endpoint, a cor de fundo marrom é mostrada.
curl -H "Authorization: bearer $(gcloud auth print-identity-token)" -X GET $SERVICE_URL
Dividir o tráfego de 50 a 50
Para dividir o tráfego entre as revisões em verde-marinho e marrom-claro, é preciso encontrar os IDs de revisão dos serviços subjacentes do Cloud Run. Para conferir os IDs de revisão, execute este comando:
gcloud run revisions list --service traffic-splitting-gcf \ --region $REGION --format 'value(REVISION)'
Você vai encontrar resultados semelhantes aos 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
Você pode testar a função visitando seu URL público (seja por curl ou diretamente no navegador).
curl -H "Authorization: bearer $(gcloud auth print-identity-token)" $SERVICE_URL
Metade do tempo, deve aparecer a revisão verde-mar-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 alterações gradualmente para uma nova revisão de função do Cloud. Saiba mais sobre 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 você preferir implantar como um Cloud Functions de 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 como bege para receber 100% do tráfego. Isso garante que as implantações futuras do Cloud Functions 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 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-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 um resultado semelhante a Traffic: 100% gradual-rollouts-gcf2-00001-yox
Agora é possível implantar uma nova revisão que não receberá tráfego. Em vez de fazer alterações de código, você pode atualizar a variável de ambiente BG_COLOR para esta 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 você preferir implantar como um Cloud Functions de 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
vai notar a cor bege, embora lavanda tenha sido a revisão implantada mais recentemente.
<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 exibe 0% do tráfego
Suponha que você tenha verificado que sua revisão foi implantada com sucesso e que está atendendo a 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 Lavanda, aplique uma tag a ela. Com a inclusão de 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 para essa revisão.
IMAGE_URL=$(gcloud run services describe gradual-rollouts-gcf --region $REGION --format 'value(IMAGE)')
Agora marcamos essa imagem com a cor associada a ela.
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 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 de lavanda. O exemplo abaixo mostra como enviar 1% do tráfego para a cor lavanda.
gcloud run services update-traffic gradual-rollouts-gcf --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-gcf --region $REGION --to-tags lavender=50
Você 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 o valor dela como 100% para substituir o bege.
gcloud run services update-traffic gradual-rollouts-gcf --region $REGION --to-tags lavender=100
e agora, ao 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 a cor lavanda.
<html><body style="background-color:lavender;"><div><p>Hello gradual-rollouts-gcf-00004-mum</p></div></body></html>
5. Reversões
Suponha que tenha recebido feedback antecipado de UX, indicando que os clientes preferem bege ao lavanda, e você precisa reverter para bege.
Para reverter para a revisão anterior (bege), execute este comando.
gcloud run services update-traffic gradual-rollouts-gcf --region $REGION --to-revisions $BEIGE_REVISION=100
e agora quando "curl" ou "visitar o endpoint do URL da função",
curl -H "Authorization: bearer $(gcloud auth print-identity-token)" -X GET $SERVICE_URL
você verá bege retornado.
<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 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 uma funçã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 mais vezes do que sua alocação mensal de invocação de função do Cloud 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 implantada no Cloud Run, acesse o console do Cloud Run em https://console.cloud.google.com/functions/ e exclua as funções que você criou neste codelab.
Para excluir as funções do Cloud Run implantadas como funções de 2a geração, acesse o Cloud Functions no console do Cloud em https://console.cloud.google.com/functions/ e exclua as funções que você criou 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.