Como fazer um deploy canário no Cloud Run

O deploy termina com status verde, mas a nova versão ainda não recebeu uma requisição real. Quando ela recebe todo o tráfego de uma vez, um erro de configuração, uma migração incompatível ou uma dependência lenta aparece para todos os usuários.

Um deploy canário no Cloud Run reduz esse salto. Você cria uma nova revisão, testa sem tráfego, envia uma parcela pequena para ela, observa o comportamento e aumenta a participação somente quando os sinais sustentam a decisão. Se algo sair errado, o rollback é uma mudança de tráfego para a revisão estável, não um novo build feito às pressas.

O guia geral do Google Cloud Run explica o modelo da plataforma. Este artigo trata da mudança de revisão: como fazer o rollout, o que observar e qual estado precisa estar pronto antes de promover.

Resposta curta

• Publique a revisão nova com --no-traffic e dê a ela uma tag quando precisar testar uma URL direta.
• Comece com uma parcela pequena de tráfego somente depois de verificar o caminho principal.
• Compare erros, latência, logs e efeitos no downstream durante cada etapa.
• Mantenha uma revisão estável identificável e pratique o comando de rollback antes da mudança.
• Trate o canário como uma decisão de compatibilidade, não apenas como uma divisão de porcentagens.

O que um deploy canário precisa provar?

O canário precisa provar que a nova revisão atende o contrato que muda o risco do deploy. Um build e uma probe de startup mostram que o container iniciou. Eles não mostram que uma requisição autenticada, uma gravação, uma consulta crítica ou uma integração externa continuam funcionando sob tráfego real.

Antes de publicar, escreva a decisão em termos observáveis:

• Entrada: qual revisão, imagem ou commit está sendo testado.
• Caminho principal: qual fluxo precisa responder corretamente.
• Sinais de falha: quais erros, timeouts, logs ou métricas interrompem a promoção.
• Condição de promoção: que evidência permite aumentar o tráfego.
• Condição de rollback: que evidência manda voltar para a revisão estável.

Essa lista evita transformar “não apareceu alerta” em aprovação. Um canário pode não receber volume suficiente para revelar um problema. Se a mudança altera schema, sessão, fila ou contrato de API, teste também a compatibilidade entre a revisão antiga e a nova.

Como publicar a nova revisão sem tráfego?

Comece separando deploy de exposição. A documentação do Google Cloud sobre lançamentos graduais, reversões e migração de tráfego mostra o uso de --no-traffic para criar a revisão sem enviá-la aos usuários.

gcloud run deploy SERVICE \
  --image IMAGE_URL \
  --no-traffic \
  --tag canary

Troque SERVICE e IMAGE_URL pelos valores do seu projeto. O comando é um exemplo de configuração, não uma receita que foi executada neste repositório. A tag cria uma URL direta para testar a revisão sem colocar tráfego normal nela. Use essa URL com uma conta de teste e dados que não causem efeitos irreversíveis.

A revisão ainda precisa de uma verificação mínima: imagem correta, variáveis esperadas, permissões, porta, health check e caminho principal. Se a aplicação usa dados compartilhados, uma chamada de teste pode alterar o mesmo banco usado pela revisão estável. Separe dados de teste ou faça a operação ser reversível antes de chamar isso de aprovação.

Cápsula citável: No Cloud Run, uma revisão pode ser publicada sem tráfego e receber uma tag para teste direto. Isso separa a verificação da versão nova da exposição dos usuários. A etapa seguinte só deve mover tráfego quando a revisão, suas dependências e o fluxo principal tiverem evidência suficiente para o risco da mudança.

Quando uma tag é melhor que uma divisão de tráfego?

Use uma tag quando você precisa testar uma revisão isoladamente. Use uma divisão de tráfego quando a pergunta depende de comportamento com usuários reais, carga real ou integrações que só aparecem no caminho público. As duas etapas respondem a perguntas diferentes.

Uma URL marcada é útil para smoke tests, testes de contrato, verificação manual e validação de uma operação específica. Ela também evita que o primeiro teste de uma revisão aconteça por acaso para um usuário escolhido pelo roteador. O resultado, porém, pode não revelar problemas que dependem da distribuição de tráfego ou de sessões existentes.

O Google Cloud alerta que tags e instâncias mínimas podem ter implicações de cobrança dependendo de onde o mínimo está configurado. Remova tags que não têm mais função e confira o efeito da sua configuração antes de deixar uma revisão de teste ativa por tempo indefinido (Google Cloud, “Rollouts, rollbacks, and traffic migration”, consultado em 14/10/2026).

Não trate uma resposta correta na URL marcada como prova de rollout seguro. A revisão antiga e a nova podem executar ao mesmo tempo. Por isso, mudanças de banco e de formato precisam ser compatíveis durante a transição, inclusive quando o rollback volta a servir o código anterior.

Como mover uma pequena parcela de tráfego?

Depois do teste sem tráfego, mova uma parcela pequena e explícita para a revisão. A documentação do Cloud Run usa 5 por cento como exemplo de lançamento gradual. O valor adequado ao seu serviço depende de volume, risco, capacidade de observação e custo de uma falha.

gcloud run services update-traffic SERVICE \
  --to-revisions REVISION=5,STABLE_REVISION=95

Confirme o estado retornado pela CLI e registre qual revisão recebeu cada porcentagem. Não use LATEST sem saber qual artefato o nome representa no seu fluxo. A identificação precisa permitir que outra pessoa repita a mudança ou faça o rollback sem procurar no console.

Os ajustes de roteamento não são instantâneos. O Google Cloud explica que requisições em andamento continuam até terminar e podem ser direcionadas para a revisão anterior ou para a nova durante a transição. Não use o instante do comando como fronteira exata para comparar dados. Espere a mudança estabilizar no seu ambiente e registre a janela usada na análise.

Se o serviço usa afinidade de sessão, a divisão também pode não se comportar como uma amostra independente por requisição. Verifique essa interação antes de concluir que o percentual configurado equivale ao percentual de usuários distintos.

O que observar antes de aumentar o tráfego?

Observe sinais que respondem ao risco da mudança, não uma lista fixa de dashboards. O mínimo costuma incluir erros por revisão, latência do caminho principal, logs de falha, saturação de recursos e respostas das dependências que podem recusar a nova carga.

Uma revisão pode parecer saudável em uma URL marcada e falhar quando recebe autenticação real, cache diferente, payloads maiores ou chamadas downstream concorrentes. Inclua pelo menos um fluxo representativo e uma verificação de efeitos: registro criado uma vez, mensagem confirmada no momento certo ou resposta compatível com o cliente anterior.

Use uma tabela de decisão curta:

Esse quadro não fornece um limite universal de erro. O limite precisa vir do contrato do serviço e do impacto da falha. Sem um limite escrito, cada pessoa interpreta o mesmo gráfico de um jeito e a promoção vira uma discussão depois do incidente.

Como fazer rollback para a revisão estável?

Rollback no Cloud Run é devolver o tráfego para uma revisão que você consegue identificar. A documentação oficial mostra gcloud run services update-traffic SERVICE --to-revisions REVISION=100 para enviar todo o tráfego a uma revisão anterior.

gcloud run services update-traffic SERVICE \
  --to-revisions STABLE_REVISION=100

O nome STABLE_REVISION é um marcador do exemplo. Substitua-o pelo nome real retornado quando você listou ou promoveu a revisão estável. Depois do comando, confirme o roteamento, os erros e as requisições em andamento. Um rollback de tráfego não desfaz uma escrita que a revisão nova já realizou.

Esse detalhe muda a ordem da resposta. Se a versão nova alterou dados, enviou mensagens ou chamou um serviço externo, voltar o tráfego não desfaz esses efeitos. Prepare uma estratégia de compatibilidade, compensação ou roll-forward antes do canário. Rollback rápido reduz exposição, mas não substitui uma política para efeitos já confirmados.

Pratique o comando com uma revisão sem risco e registre quem pode executá-lo. A documentação sobre gerenciamento de revisões confirma que revisões são imutáveis e podem receber todo, nenhum ou parte do tráfego. O procedimento de emergência deve depender desse estado conhecido, não de reconstruir a imagem no momento da falha.

Quando vale usar o Cloud Deploy?

Use o Cloud Deploy quando você precisa repetir fases, registrar aprovações e automatizar a mudança entre percentuais. O Cloud Run permite uma divisão manual. O Cloud Deploy acrescenta uma estratégia de canário com etapas, tarefas de verificação e controle de avanço.

Na configuração oficial, o canário do Cloud Deploy define percentuais progressivos, pode executar tarefas de predeploy, verify e postdeploy e deixa a gestão automática do tráfego para a integração com o Cloud Run (Google Cloud, “Canary Deployments to Cloud Run”, consultado em 14/10/2026).

canary:
  runtimeConfig:
    cloudRun:
      automaticTrafficControl: true
  canaryDeployment:
    percentages: [25, 50, 75]
    verify:
      tasks: [verify-service]

Esse trecho é uma ilustração reduzida. Os nomes de pipeline, target e tasks precisam existir na sua configuração do Cloud Deploy. As porcentagens mostram etapas de exemplo, não um padrão recomendado para qualquer serviço.

Se o time ainda não tem critérios de promoção, automatizar o botão não resolve a decisão. Comece registrando o canário manualmente. Depois transforme em tarefa aquilo que já tem entrada, saída e condição de falha clara.

Quais mudanças quebram um canário?

O canário perde valor quando as duas revisões não conseguem conviver. As falhas mais difíceis aparecem quando a versão nova assume que todos os consumidores já foram atualizados, mas parte do tráfego ainda executa o código antigo.

Revise estes pontos antes de dividir o tráfego:

• migração que remove uma coluna antes de a revisão antiga parar;
• resposta que troca um campo obrigatório sem manter compatibilidade;
• cookie ou sessão que muda de formato;
• mensagem de fila que o consumidor anterior não entende;
• cache compartilhado que mistura versões sem uma chave de versão;
• comando de rollback que não foi testado com os efeitos já escritos.

O artigo sobre concorrência no Cloud Run ajuda a escolher a pressão por instância depois que a revisão começa a receber tráfego. O diagnóstico de cold start com min instances e CPU boost cobre outra parte da latência. Nenhum dos dois substitui a compatibilidade entre revisões.

Checklist para o próximo deploy

Antes de liberar uma revisão, confira:

• a imagem e o identificador da revisão estão registrados;
• o teste sem tráfego passou em uma URL marcada ou ambiente isolado;
• o fluxo principal usa dados de teste seguros e reproduzíveis;
• erros, latência, logs e dependências têm sinais visíveis por revisão;
• o critério de promoção e o critério de rollback estão escritos;
• a revisão antiga continua compatível com os dados e mensagens novos;
• a equipe sabe qual comando devolve o tráfego à versão estável;
• o rollback foi exercitado sem depender de um novo build;
• tags e instâncias de teste serão removidas quando perderem a função.

Um canário bom não é o que permanece em 5 por cento. É o que torna a decisão de aumentar, parar ou voltar uma operação explícita. A porcentagem é só o mecanismo de exposição. A confiança vem do fluxo testado, dos sinais que podem falhar e da revisão estável que continua disponível.

Perguntas frequentes

Deploy canário e blue-green são a mesma coisa no Cloud Run?

Não exatamente. Os dois mantêm versões que podem receber tráfego, mas um canário costuma aumentar a parcela gradualmente. Um blue-green pode manter uma versão pronta e fazer uma troca mais ampla. No Cloud Run, tags, revisões e divisão de tráfego permitem montar os dois padrões, desde que o contrato entre versões seja compatível.

Posso testar uma revisão sem enviar tráfego?

Sim. Publique com --no-traffic e use uma tag para obter uma URL de teste direto. A revisão continua fora do tráfego normal, mas pode consumir recursos ou gerar custo conforme a configuração de instâncias mínimas. Confirme os efeitos da tag e remova-a quando o teste terminar.

Qual porcentagem devo usar no primeiro canário?

Não existe uma porcentagem universal. O exemplo de 5 por cento na documentação do Cloud Run é uma etapa possível, não um limite de segurança. Escolha a menor exposição que ainda produza sinais úteis para o seu serviço. Se o volume for baixo, aumente a qualidade do teste antes de aumentar o percentual.

O rollback desfaz as mudanças feitas pela nova revisão?

Não. O rollback de tráfego muda qual revisão recebe requisições. Ele não apaga registros, desfaz mensagens, reverte chamadas externas nem corrige um schema já alterado. Para esses efeitos, o deploy precisa de compatibilidade, operação compensatória ou uma estratégia de roll-forward documentada.

Conclusão

Um deploy canário no Cloud Run começa antes da primeira divisão de tráfego. Identifique a revisão, teste-a sem exposição, defina sinais de falha e confirme que a versão antiga consegue conviver com a nova. Depois aumente o tráfego em etapas que alguém consegue explicar.

Se a revisão falhar, devolva o tráfego para a versão estável e preserve a evidência do que já aconteceu. Essa separação entre exposição, observação e rollback torna o deploy reversível no ponto certo. Ela também mostra quando o problema não é o roteamento, mas a compatibilidade da mudança.

Como este artigo foi produzido

Samuel Fajreldines é o autor responsável por este artigo. A pesquisa comparou a documentação atual do Google Cloud sobre revisões, lançamentos graduais, tags, migração de tráfego e canários do Cloud Deploy, além de resultados atuais em português, inglês e espanhol. Os comandos e o YAML são exemplos ilustrativos. Não houve deploy, medição de produção ou caso de cliente usado como prova.

Usei assistência de IA para descoberta de fontes, organização, redação, geração da imagem, tradução e revisão de consistência. A assistência não executou um rollout real, não mediu impacto de tráfego e não substituiu a verificação da documentação oficial.

Fontes consultadas

• Google Cloud, “Rollouts, rollbacks, and traffic migration”, consultado em 2026-10-14
• Google Cloud, “Manage revisions”, consultado em 2026-10-14
• Google Cloud, “Canary Deployments to Cloud Run”, consultado em 2026-10-14
• Google Cloud, “What is Cloud Run?”, consultado em 2026-10-14