# O que é canary deployment? Um guia prático para SREs

URL: https://upstreamapi.com/pt/journal/o-que-e-canary-deployment
Type: blog
Locale: pt
Published: 2026-10-24
Updated: 2026-10-26

---

> Um canary deployment envia uma mudança para uma pequena fatia do tráfego e só a amplia se as métricas se mantiverem. Etapas, métricas de gate e armadilhas que cegam as equipes.

O que é canary deployment? É uma técnica de release que envia uma nova versão para uma pequena fatia do tráfego de produção, compara essa versão com a que já está rodando e só amplia o rollout se os números se sustentarem. Na prática, é um deploy com um ponto de decisão embutido: a mudança chega primeiro a 1 a 5% dos usuários, e uma checagem de métricas decide se ela continua ou se é revertida.

O resto deste guia cobre como funciona, onde falha e o que vale automatizar.

## A página das 3h que um canary teria transformado em mensagem no Slack

Um deploy sai às 16h40 de uma quinta-feira. A taxa de erro do serviço de checkout sobe de 0.2% para 4%. Ninguém percebe até um chamado de suporte aparecer duas horas depois, e nessa altura todos os usuários já rodam o build novo. O rollback leva 25 minutos porque a migração ficou meio aplicada.

Rode a mesma mudança como canary em 5% do tráfego e o dano fica limitado. Cerca de 1 em cada 20 usuários vê o bug, a comparação com o controle falha em minutos, e o pipeline para. O post-mortem diria o que o canary pegou, não o que deixou passar.

![Pequeno canário amarelo empoleirado num gancho de lanterna num túnel escuro de mina](https://fdzlnqpwsaniezitwiuw.supabase.co/storage/v1/object/public/cms-media/upstreamapi/2026-10/ac107f-img1.webp)

O nome vem das minas de carvão, onde o canário parava de cantar antes que o ar ficasse letal. Sua coorte pequena faz o mesmo papel. Ela não impede o release ruim. Ela limita quem respira o problema.

## O que um canary deployment faz, passo a passo

A [Google SRE Workbook](https://sre.google/workbook/canarying-releases/) define canarying como um deploy parcial e com tempo limitado da mudança, somado a uma avaliação que decide se o rollout continua. O subconjunto que roda a mudança é o canary. O resto da frota é o controle. Essa definição importa porque transforma o canary num teste A/B da sua confiabilidade, e não num deploy lento.

Uma sequência típica fica assim:

- 
Implante a nova versão ao lado da estável, ainda sem tráfego.

- 
Direcione uma pequena porcentagem para ela (o exemplo do Workbook usa 5%).

- 
Segure uma janela fixa (o mesmo exemplo usa 30 minutos) enquanto compara canary e controle.

- 
Avance para a próxima etapa, como 25%, 50% e 100%, ou aborte e devolva o tráfego à versão estável.

O loop é simples. A parte difícil é a comparação, que a maioria das equipes implementa como "alguém olha um dashboard".

## Canary, blue-green ou rolling: qual combina com o seu modo de falha

Esses três modelos vivem sendo confundidos, então vale a distinção que importa na hora de escolher.

- 
**Rolling update:** substitui instâncias aos poucos. É barato e vem embutido em todo orquestrador, mas não há comparação com um controle nem divisão de tráfego limpa. Versões antiga e nova dividem a carga até o fim.

- 
**Blue-green:** dois ambientes completos, com a troca de todo o tráfego de uma vez. O rollback é instantâneo, mas o raio de impacto no momento da troca é 100% dos usuários. Você paga capacidade dobrada.

- 
**Canary:** uma fração controlada do tráfego real na versão nova, julgada contra a antiga. Menor raio de impacto, maior complexidade operacional.

Escolha blue-green quando o risco é um deploy quebrado que um smoke test detecta e que você reverte em segundos. Escolha canary quando o risco é uma regressão sutil, que só o tráfego real expõe: uma subida de p99, um vazamento lento de memória, um query plan que quebra com os formatos de dados de produção.

Pule o canary se o seu serviço tem pouco tráfego. Com algumas centenas de requisições por hora, uma fatia de 5% dá um punhado de amostras e nenhum sinal. O Workbook diz isso diretamente: consultas muito poucas não fornecem um sinal útil para cargas diversas.

## Por que o seu canary de 1% provavelmente está mentindo

Eis a falha que atinge as equipes nos primeiros três meses. O canary recebe 5% do tráfego e falha em 20% das requisições. A taxa de erro do serviço inteiro vai de 0.2% para cerca de 1.2%. O seu limite de alerta é 2%. Nada dispara.

O monitoramento agregado esconde as falhas do canary. A mesma aritmética aparece no SRE Workbook: um canary que falha em 20% das requisições com 5% do tráfego mostra apenas 1% de erro global. Você precisa quebrar as métricas por população, canary versus controle, ou o sinal desaparece no denominador.

![Vista aérea de uma rodovia em que uma faixa está isolada por cones laranja enquanto as outras seguem fluindo normalmente](https://fdzlnqpwsaniezitwiuw.supabase.co/storage/v1/object/public/cms-media/upstreamapi/2026-10/f7c98f-img2.webp)

Três outras armadilhas merecem atenção:

- 
**Comparações antes e depois.** Comparar a janela do canary com a hora anterior confunde a mudança com o tempo. Só a diferença entre tráfego de dia útil e de fim de semana pode encobrir uma regressão real. Compare com um controle concorrente.

- 
**Dependências compartilhadas.** Se canary e controle acessam o mesmo cache ou o mesmo banco, um canary ruim pode degradar os dois, e a comparação não mostra nada. Verifique seus domínios de falha.

- 
**Métricas ruidosas.** O uso de CPU é um gate ruim. Códigos de erro e latência acompanham o que o usuário sente. O Workbook recomenda ranquear as métricas candidatas pelo quanto refletem problemas visíveis ao usuário e manter só as principais, talvez no máximo uma dúzia.

## Escolha as métricas de gate antes do deploy, não durante o incidente

Comece pelos seus SLIs. Se o serviço já tem um SLI de disponibilidade e outro de latência, esses são os seus dois primeiros gates. Um conjunto inicial razoável para um serviço orientado a requisições:

- 
Taxa de erro (5xx) no canary versus controle, durante a janela de observação

- 
Latência p99 no canary versus controle

- 
Um sinal de saturação atribuível à mudança, como crescimento de memória por pod

- 
Uma métrica de negócio próxima, por exemplo a conclusão do checkout, se você conseguir isolá-la por coorte

Os limites são onde as equipes perdem semanas. Se forem apertados demais, todo canary aborta por ruído, e os engenheiros aprendem a ignorar o gate. Se forem frouxos demais, um build ruim passa. Revise-os periodicamente. Um gate que não abortou nada em seis meses é perfeito ou decorativo, e vale descobrir qual dos dois.

Mantenha também o intervalo de agregação não maior que a janela do canary. Um rollup de 10 minutos sobre um canary de 5 minutos embaça tudo.

## Um canary em configuração: os passos no Argo Rollouts

No Kubernetes, a [especificação de canary do Argo Rollouts](https://argo-rollouts.readthedocs.io/en/stable/features/canary/) expressa a sequência como uma lista de passos. Segue uma versão condensada, no formato descrito na documentação:

`strategy:
  canary:
    steps:
      - setWeight: 5
      - pause: { duration: 30m }
      - analysis:
          templates:
            - templateName: error-rate-vs-baseline
      - setWeight: 25
      - pause: { duration: 30m }
      - setWeight: 50
      - pause: {}`Dois detalhes da documentação merecem atenção. Sem um roteador de tráfego, o peso é aproximado pela contagem de pods, em base de melhor esforço: 10 réplicas com 10% significam um pod canary e nove estáveis. É matemática de réplicas, não de requisições. E um `pause: {}` sem duração espera indefinidamente até alguém rodar `kubectl argo rollouts promote`, um gate humano que você pode ou não querer.

Se a etapa de análise falhar, o rollout aborta. É essa parte que vale o investimento.

![Painel de controle industrial com uma chave vermelha de reversão protegida e fileiras de luzes indicadoras verdes](https://fdzlnqpwsaniezitwiuw.supabase.co/storage/v1/object/public/cms-media/upstreamapi/2026-10/5eb655-img4.webp)

## Feature flags e fonte de comparação: a outra metade de um canary seguro

Canaries de infraestrutura dividem o tráfego por instância ou por pod. Canaries com flags dividem por usuário, conta ou qualquer atributo que você consiga direcionar. As duas abordagens respondem perguntas diferentes. A primeira pergunta se o build novo está saudável. A segunda pergunta se o comportamento novo é aceitável, e permite desligá-lo sem um novo deploy.

Para rollouts guiados por flags, a ferramenta importa. O LaunchDarkly tem as regras de targeting mais maduras e um trilho de auditoria forte, e vence em amplitude de ecossistema. O preço em escala empresarial é a reclamação mais comum entre líderes de plataforma.

O Statsig une experimentação e flags, o que serve a equipes que querem julgamento baseado em métricas na mesma plataforma. É menos adequado se você só precisa de um kill switch.

O trade-off é honesto: uma plataforma de flags entrega rollouts percentuais, mas a maioria não lê seus SLOs sozinha. Alguém ainda precisa conectar a métrica à decisão.

Qualquer que seja o motor do rollout, o veredito vem da sua telemetria. Isso significa que cada métrica precisa de um rótulo de versão ou de coorte, e o seu backend precisa consultar por esse rótulo sem um atraso de 10 minutos.

O Datadog faz isso bem com quebras por tags, e o rastreamento de deploys correlaciona releases com picos de erro. O custo em alta cardinalidade é o que vale modelar antes de taguear tudo.

O Grafana com Prometheus funciona se você já o roda e rotula as métricas pela revisão do rollout. Você ganha controle total, e a manutenção fica com você.

## Automatizar o abort, sem magia

A análise manual de canary escala mal. Com dez deploys por dia, ninguém fica olhando um dashboard por 30 minutos a cada vez, e o gate vira silenciosamente um "parece ok". O padrão que se sustenta é um juiz automatizado: defina o SLO, defina a comparação, e deixe um controlador abortar e reverter quando o canary consumir o orçamento de erro mais rápido que o controle.

É esse o problema que o AI Pilot da upstreamapi ataca: ele lê o sinal de SLO durante o rollout e dispara um auto-rollback quando a taxa de erro cruza o limite que você definiu. Ele mede taxa de erro e latência contra a coorte estável, nada além disso. Se você já roda templates de análise do Argo Rollouts com uma boa query no Prometheus, tem a maior parte da mesma capacidade, e deve dizer isso a quem tentar vender magia. Onde um piloto hospedado se paga é em stacks heterogêneas, em que cada time manteria os próprios templates de análise.

Um padrão de falha comum: as equipes automatizam o promote e nunca automatizam o abort. Um pipeline que só sabe ir para a frente é uma esteira.

Um programa de canary tem métricas próprias. Acompanhe estas ao longo de um trimestre:

- 
**Taxa de abort do canary:** parcela de canaries interrompidos pelo gate. Zero significa que o gate é cego. Acima de 20 a 30% geralmente indica limites instáveis ou testes pré-merge fracos.

- 
**Tempo para detectar no canary:** minutos entre a primeira requisição ruim e o abort. Esse é o seu MTTD real para releases.

- 
**Regressões que escaparam:** incidentes rastreados até um release que passou pelo canary. Cada um deve mudar um gate.

- 
**Tempo médio para reverter:** da decisão de abortar até 100% do tráfego na versão estável.

Rode apenas um canary por vez por serviço. O Workbook recomenda com força, e o motivo é prático: duas mudanças sobrepostas tornam a atribuição impossível, e você não saberá qual delas causou o dano.

Para começar esta semana, escolha um serviço stateless com tráfego suficiente para produzir sinal em 15 minutos. Adicione uma label de versão às métricas de erro e de latência. Escreva uma única consulta de comparação, canary versus controle. Rode um canary de 5% com promote manual e registre o que teria pego nos últimos três incidentes.

Depois, faça a pergunta incômoda: se o canary tivesse falhado às 2h da manhã, algo o teria parado sem um humano acordado?

## FAQ

### O que é canary deployment, em termos simples?

É um método de release em que uma nova versão atende primeiro uma pequena porcentagem do tráfego real, enquanto a versão antiga atende o restante. Você compara as métricas de saúde entre os dois grupos. Se a nova versão se sustenta, aumenta-se a fatia até ela atender tudo. Se não, você reverte.

### Em que o canary deployment difere do blue-green deployment?

O blue-green mantém dois ambientes completos e troca todo o tráfego de uma vez, então o rollback é instantâneo, mas a troca expõe 100% dos usuários. O canary expõe primeiro uma fração pequena e julga a versão nova contra a antiga com tráfego real. Tem raio de impacto menor e complexidade operacional maior.

### Que porcentagem de tráfego um canary deve receber?

Não existe um número universal. O SRE Workbook do Google usa 5% por 30 minutos como exemplo. A fatia precisa ser grande o bastante e durar o bastante para produzir um sinal estatisticamente útil, o que depende do volume de tráfego e de quão uniformes são as suas requisições.

### Quais métricas devem controlar um canary deployment?

Comece pelos seus SLIs: taxa de erro e latência, comparadas entre canary e controle. Acrescente um sinal de saturação atribuível à mudança e uma métrica de negócio, se você conseguir isolá-la por coorte. Evite métricas ruidosas como o uso bruto de CPU, e mantenha a lista curta.

### Qual a diferença entre canary release e canary deployment?

Algumas equipes usam canary release para a exposição de uma funcionalidade ao usuário e canary deployment para o rollout mais amplo da infraestrutura. Muitas tratam os termos como intercambiáveis. O que importa é que um grupo limitado receba a mudança primeiro e uma checagem de métricas decida o que acontece depois.

### Dá para fazer canary deployment sem Kubernetes?

Sim. Qualquer mecanismo que divida o tráfego por versão funciona: um load balancer com roteamento ponderado, um service mesh, uma regra de CDN ou uma feature flag que direcione uma porcentagem de usuários. Ferramentas do Kubernetes como o Argo Rollouts automatizam as etapas, mas o padrão não depende delas.