1. Introdução
Visão geral
O Cloud Run functions permite especificar quais revisões devem receber tráfego e especificar 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.
Nestes codelabs, mostramos como 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 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 o processo de 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 esta for a primeira vez que você iniciar o Cloud Shell, vai aparecer uma tela intermediária com a descrição dele. Se esse for o caso, 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 e é executada no Google Cloud. Isso aprimora o desempenho e a autenticação da rede. Praticamente todo o trabalho neste codelab pode ser feito em um navegador.
Depois de se conectar ao Cloud Shell, você vai notar que sua conta já está autenticada e que o projeto está configurado com seu ID do 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 plano de fundo.
Embora este codelab use o 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 será marrom claro.
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-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 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 comando a seguir:
gcloud run services update-traffic traffic-splitting-gcf \ --region $REGION \ --to-revisions <REVISION1>=50,<REVISION2>=50
Testar a divisão de tráfego
Para testar a função, acesse o URL público dela (com curl ou diretamente no navegador).
curl -H "Authorization: bearer $(gcloud auth print-identity-token)" $SERVICE_URL
Na metade do tempo, 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 será listado 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 do Cloud Function. 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 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
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 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 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 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
você vai ver a cor bege, mesmo que a 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 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 dessa revisão.
IMAGE_URL=$(gcloud run services describe gradual-rollouts-gcf --region $REGION --format 'value(IMAGE)')
Agora marque a 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 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>
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-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ê vai encontrar uma lista com a quantidade de tráfego que 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
Agora, quando você acessa ou usa o comando curl no URL do serviço de 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 o feedback inicial de UX tenha indicado que os clientes preferem o bege ao lilás, e você precisa reverter para o 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
Agora, quando você usar o 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 o retorno de bege.
<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 acidentalmente 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 Cloud Run no console do Google Cloud 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 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 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.