Como implementar implantações canário do Cloud Run com ramificações Git e Cloud Build

Last reviewed 2023-05-26 UTC

Neste documento, mostramos como implementar um pipeline de implantação para o Cloud Run que implementa a progressão do código de ramificações do desenvolvedor para produção com testes canário automatizados e gerenciamento de tráfego baseado em porcentagem. Ele é destinado a administradores de plataforma responsáveis por criar e gerenciar pipelines de CI/CD. Neste documento, presumimos que você tenha uma compreensão básica dos conceitos de pipeline do Git, Cloud Run e CI/CD.

O Cloud Run permite implantar e executar seus aplicativos com pouca sobrecarga ou esforço. Muitas organizações usam pipelines de lançamento robustos para mover o código para a produção. O Cloud Run oferece recursos exclusivos de gerenciamento de tráfego que permitem implementar técnicas avançadas de gerenciamento de versões com pouco esforço.

Objetivos

Criar o serviço do Cloud Run
Ativar uma ramificação para desenvolvedores
Implementar testes canário
Implantar com segurança para produção

Custos

Neste documento, você usará os seguintes componentes faturáveis do Google Cloud:

Para gerar uma estimativa de custo baseada na projeção de uso deste tutorial, use a calculadora de preços. Novos usuários do Google Cloud podem estar qualificados para uma avaliação gratuita.

Antes de começar

No console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

Acessar o seletor de projetos
Verifique se a cobrança está ativada para o seu projeto do Google Cloud.
No Console do Google Cloud, ative o Cloud Shell.

Ativar o Cloud Shell

Na parte inferior do Console do Google Cloud, uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.

Como preparar o ambiente

No Cloud Shell, crie variáveis de ambiente para usar neste tutorial:

export PROJECT_ID=$(gcloud config get-value project)
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')

Ative as APIs a seguir:

Resource Manager
GKE
Cloud Build
Container Registry
Cloud Run

gcloud services enable \
    cloudresourcemanager.googleapis.com \
    container.googleapis.com \
    secretmanager.googleapis.com \
    cloudbuild.googleapis.com \
    containerregistry.googleapis.com \
    run.googleapis.com

Conceda o papel roles/run.adminAdministrador do Cloud Run à conta de serviço do Cloud Build

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member=serviceAccount:$PROJECT_NUMBER@cloudbuild.gserviceaccount.com \
  --role=roles/run.admin

Conceda o papel de usuário da conta de serviço do IAM (roles/iam.serviceAccountUser) à conta de serviço do Cloud Build para a conta de serviço do ambiente de execução do Cloud Run

gcloud iam service-accounts add-iam-policy-binding \
$PROJECT_NUMBER-compute@developer.gserviceaccount.com \
  --member=serviceAccount:$PROJECT_NUMBER@cloudbuild.gserviceaccount.com \
  --role=roles/iam.serviceAccountUser

Definir valores Git

Se você nunca usou o Git no Cloud Shell, defina os valores user.name e user.email que quer usar:

    git config --global user.email YOUR_EMAIL_ADDRESS
    git config --global user.name YOUR_USERNAME
    git config --global credential.helper store

YOUR_EMAIL_ADDRESS: o e-mail usado com sua conta do GitHub
YOUR_USERNAME: seu ID de usuário do GitHub

Se você estiver usando a MFA com o GitHub, crie um token de acesso pessoal e use-o como sua senha ao interagir com o GitHub por meio da linha de comando.

Siga este link para criar um token de acesso.
Deixe a página do GitHub aberta.

Armazene seu ID de usuário do GitHub em uma variável de ambiente para facilitar o acesso:

export GH_USER=YOUR_GITHUB_ID

Bifurcar o repositório do projeto

Para criar sua própria versão gravável do repositório do laboratório, divida o repositório de amostra na sua conta do GitHub por meio da interface do GitHub.

Clone o repositório de exemplo

Clone e prepare o repositório de amostra:

git clone https://github.com/$GH_USER/software-delivery-workshop.git cloudrun-progression

cd cloudrun-progression/labs/cloudrun-progression

Conecte seu repositório Git.

O Cloud Build permite criar e gerenciar conexões com repositórios de código-fonte usando o console do Google Cloud. É possível criar e gerenciar conexões usando a primeira ou a segunda geração de repositórios do Cloud Build. Neste tutorial, usamos repositórios do Cloud Build de segunda geração.

Conceder as permissões necessárias

Para conectar seu host do GitHub, conceda o papel de Administrador de conexão do Cloud Build (roles/cloudbuild.connectionAdmin) à sua conta de usuário:

PN=$(gcloud projects describe ${PROJECT_ID} --format="value(projectNumber)")
CLOUD_BUILD_SERVICE_AGENT="service-${PN}@gcp-sa-cloudbuild.iam.gserviceaccount.com"
gcloud projects add-iam-policy-binding ${PROJECT_ID} \
 --member="serviceAccount:${CLOUD_BUILD_SERVICE_AGENT}" \
 --role="roles/secretmanager.admin"

Criar a conexão de host

Configure a conexão do repositório do Cloud Build:

gcloud alpha builds connections create github $GH_USER --region=us-central1

Clique no link fornecido na saída e siga as instruções na tela para concluir a conexão.

Verifique a instalação da conexão do GitHub:

gcloud alpha builds connections describe $GH_USER --region=us-central1

Vincular o repositório de amostra

Usando a conexão do host que você acabou de configurar, vincule no repositório de amostra que você bifurcou:

 gcloud alpha builds repositories create cloudrun-progression \
     --remote-uri=https://github.com/$GH_USER/software-delivery-workshop.git \
     --connection=$GH_USER \
     --region=us-central1

Definir variável de nome do repositório

Armazene o nome do repositório para uso posterior:

export REPO_NAME=projects/$PROJECT_ID/locations/us-central1/connections/$GH_USER/repositories/cloudrun-progression

Implantar o serviço do Cloud Run

Nesta seção, você criará e implantará o aplicativo de produção inicial usado ao longo deste tutorial.

Implante o serviço

No Cloud Shell, crie e implante o aplicativo, incluindo um serviço que exija autenticação. Para tornar um serviço público, use a sinalização --allow-unauthenticated.

    gcloud builds submit --tag gcr.io/$PROJECT_ID/hello-cloudrun

    gcloud run deploy hello-cloudrun \
      --image gcr.io/$PROJECT_ID/hello-cloudrun \
      --platform managed \
      --region us-central1 \
      --tag=prod -q

A saída será assim:

Deploying container to Cloud Run service [hello-cloudrun] in project [sdw-mvp6] region [us-central1]
✓ Deploying new service... Done.
  ✓ Creating Revision...
  ✓ Routing traffic...
Done.
Service [hello-cloudrun] revision [hello-cloudrun-00001-tar] has been deployed and is serving 100 percent of traffic.
Service URL: https://hello-cloudrun-apwaaxltma-uc.a.run.app
The revision can be reached directly at https://prod---hello-cloudrun-apwaaxltma-uc.a.run.app

A saída inclui o URL do serviço e um URL exclusivo para a revisão. Os valores serão um pouco diferentes dos indicados aqui.

Validar a implantação

Após a conclusão da implantação, veja o serviço recém-implantado na página "Revisões" no Console do Cloud.

No Cloud Shell, veja a resposta do serviço autenticado:

PROD_URL=$(gcloud run services describe hello-cloudrun --platform managed --region us-central1 --format=json | jq --raw-output ".status.url")

echo $PROD_URL

curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" $PROD_URL

Como ativar implantações de ramificação

Nesta seção, você ativa um URL exclusivo para ramificações de desenvolvimento no Git.

Configurar gatilho da ramificação

Cada ramificação é representada por um URL identificado pelo nome da ramificação. As confirmações da ramificação acionam uma implantação, e as atualizações podem ser acessadas nesse mesmo URL.

No Cloud Shell, configure o gatilho:

gcloud alpha builds triggers create github \
--name=branchtrigger \
--repository=$REPO_NAME \
--branch-pattern='[^(?!.*main)].*' \
--build-config=labs/cloudrun-progression/branch-cloudbuild.yaml \
--region=us-central1

Para analisar o gatilho, acesse a página Gatilhos do Cloud Build no Console do Cloud.

Criar alterações em uma ramificação

No Cloud Shell, crie uma nova ramificação:
```
git checkout -b new-feature-1
```
Abra o aplicativo de amostra usando seu editor favorito ou o ambiente de desenvolvimento integrado do Cloud Shell:
```
edit app.py
```
No aplicativo de exemplo, modifique a linha 24 para indicar v1.1 em vez de v1.0:
```
@app.route('/')

def hello_world():
    return 'Hello World v1.1'
```
Para voltar ao terminal, clique em Abrir terminal.

Executar o gatilho da ramificação

No Cloud Shell, confirme a alteração e a envie ao repositório remoto:
```
git add . && git commit -m "updated" && git push origin new-feature-1
```
Observação: use o token de acesso pessoal criado anteriormente para a senha se a autenticação de dois fatores estiver ativada no GitHub.
Para revisar a versão em andamento, acesse a tela de histórico da versão do Cloud Build.
Para revisar a nova revisão, depois que a compilação for concluída, acesse a página de revisões do Cloud Run no Console do Cloud:

No Cloud Shell, consiga o URL exclusivo dessa ramificação:

BRANCH_URL=$(gcloud run services describe hello-cloudrun --platform managed --region us-central1 --format=json | jq --raw-output ".status.traffic[] | select (.tag==\"new-feature-1\")|.url")

echo $BRANCH_URL

Acesse o URL autenticado:

curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" $BRANCH_URL

A resposta de resposta atualizada tem esta aparência:

Hello World v1.1

Automatizar teste canário

Quando o código é liberado para produção, é comum liberar o código para um pequeno subconjunto de tráfego ativo antes de migrar todo o tráfego para a nova base de código.

Nesta seção, você implementará um acionador que será ativado quando o código for confirmado na ramificação principal. O gatilho implanta o código em um URL canário exclusivo e roteia 10% de todo o tráfego ativo para a nova revisão.

No Cloud Shell, configure o acionador de ramificação:

gcloud alpha builds triggers create github \
  --name=maintrigger \
  --repository=$REPO_NAME \
  --branch-pattern=main \
  --build-config=labs/cloudrun-progression/main-cloudbuild.yaml \
  --region=us-central1

Para analisar o novo gatilho, acesse a página Gatilhos do Cloud Build no Console do Cloud.
No Cloud Shell, mescle a ramificação à linha principal e a envie ao repositório remoto:
```
git checkout main
git merge new-feature-1
git push origin main
```
Para revisar a versão em andamento, acesse a página de versões do Cloud Build.
Após a conclusão da compilação, para revisar a nova revisão, acesse a página Revisões do Cloud Run no Console do Cloud. Observe que 90% do tráfego é encaminhado para prod, 10% para canário e 0% para as revisões de ramificação.

Revise as linhas-chave de main-cloudbuild.yaml que implementam a lógica para a implantação canário.

As linhas de 39 a 45 implantam a nova revisão e usam a sinalização de tag para rotear o tráfego a partir do URL Canary exclusivo:

gcloud run deploy ${_SERVICE_NAME} \
--platform managed \
--region ${_REGION} \
--image gcr.io/${PROJECT_ID}/${_SERVICE_NAME} \
--tag=canary \
--no-traffic

A linha 61 adiciona uma tag estática à revisão que anota o SHA abreviado do Git da implantação:

gcloud beta run services update-traffic ${_SERVICE_NAME} --update-tags=sha-$SHORT_SHA=$${CANARY} --platform managed --region ${_REGION}

A linha 62 atualiza o tráfego para rotear 90% para a produção e 10% para o canário:

gcloud run services update-traffic ${_SERVICE_NAME} --to-revisions=$${PROD}=90,$${CANARY}=10 --platform managed --region ${_REGION}

No Cloud Shell, consiga o URL exclusivo da revisão canário:

CANARY_URL=$(gcloud run services describe hello-cloudrun --platform managed --region us-central1 --format=json | jq --raw-output ".status.traffic[] | select (.tag==\"canary\")|.url")

echo $CANARY_URL

Analise o endpoint canário diretamente:

curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" $CANARY_URL

Para ver as respostas baseadas em porcentagem, faça uma série de solicitações:

LIVE_URL=$(gcloud run services describe hello-cloudrun --platform managed --region us-central1 --format=json | jq --raw-output ".status.url")
for i in {0..20};do
  curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" $LIVE_URL; echo \n
done

Liberar para produção

Depois que a implantação canário é validada com um pequeno subconjunto de tráfego, você libera a implantação para o restante do tráfego ativo.

Nesta seção, você configurará um gatilho que é ativado quando você cria uma tag no repositório. O gatilho migra 100% do tráfego para a revisão já implantada com base no commit SHA da tag. O uso da confirmação de SHA garante que a revisão validada com o tráfego canário seja a revisão usada para o restante do tráfego de produção.

No Cloud Shell, configure o acionador de tags:

gcloud alpha builds triggers create github \
  --name=tagtrigger \
  --repository=$REPO_NAME \
  --tag-pattern=. \
  --build-config=labs/cloudrun-progression/tag-cloudbuild.yaml \
  --region=us-central1

Para analisar o novo gatilho, acesse a página Gatilhos do Cloud Build no Console do Cloud.
No Cloud Shell, crie uma tag e envie-a para o repositório remoto:
```
git tag 1.1
git push origin 1.1
```
Para revisar a versão em andamento, acesse a tela de histórico da versão do Cloud Build no Console do Cloud.
Após a conclusão da compilação, para revisar a nova revisão, acesse a página Revisões do Cloud Run no Console do Cloud. A revisão é atualizada para indicar a tag prod e está veiculando 100% do tráfego ativo.

No Cloud Shell, para ver as respostas baseadas em porcentagem, faça uma série de solicitações:

LIVE_URL=$(gCloud Run services describe hello-cloudrun --platform managed --region us-central1 --format=json | jq --raw-output ".status.url")

for i in {0..20};do
  curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" $LIVE_URL; echo \n
done

Revise as linhas de tag-cloudbuild.yaml que implementam a lógica de implantação de produção.

A linha 37 atualiza a revisão de canário adicionando a tag prod. A revisão implantada agora está marcada para prod e canary:
```
gcloud beta run services update-traffic ${_SERVICE_NAME} --update-tags=prod=$${CANARY} --platform managed --region ${_REGION}
```
A linha 39 atualiza o tráfego do URL de serviço base para rotear 100% do tráfego para a revisão marcada como "prod":
```
gcloud run services update-traffic ${_SERVICE_NAME} --to-revisions=$${NEW_PROD}=100 --platform managed --region ${_REGION}
```

Limpeza

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados no tutorial, exclua o projeto que os contém ou mantenha o projeto e exclua os recursos individuais.

Cuidado: excluir um projeto tem os seguintes efeitos:

Tudo no projeto é excluído. Se você tiver usado um projeto existente para as tarefas neste documento, a exclusão dele incluirá a exclusão de quaisquer outros trabalhos feitos no projeto.
Os IDs do projeto personalizados são perdidos. Ao criar o projeto, você pode ter criado um código do projeto personalizado para ser usado no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, exclua recursos específicos do projeto, em vez de excluir o projeto inteiro.

Se você planeja passar por várias arquiteturas, tutoriais ou guias de início rápido, a reutilização de projetos pode evitar que você exceda os limites da cota do projeto.

No Console do Google Cloud, acesse a página Gerenciar recursos.
Acessar "Gerenciar recursos"
Na lista de projetos, selecione o projeto que você quer excluir e clique em Excluir .
Na caixa de diálogo, digite o ID do projeto e clique em Encerrar para excluí-lo.

A seguir

Consulte Como gerenciar revisões com o Cloud Run.
Analise os reversões, lançamentos graduais e migração de tráfego do Cloud Run.
Leia Como usar tags para acessar revisões.
Consulte Como criar e gerenciar gatilhos de compilação no Cloud Build.
Para mais arquiteturas de referência, diagramas e práticas recomendadas, confira a Central de arquitetura do Cloud.