Um canary deployment manda uma versão nova pra uma fatia pequena do tráfego antes do resto. A ideia é que, se algo está errado, está errado pra 5% dos usuários, não todos. Essa contenção só se paga se algo de fato observa o canary e decide se avança ou recua. Um canary que ninguém está observando é só uma forma mais lenta de descobrir que a mesma coisa quebrou todo mundo.
As duas formas que um estágio canary termina
Todo estágio canary se resolve de uma de duas formas: ele avança (o tráfego sobe pro próximo estágio, eventualmente 100%) ou é recuado. Fazer essa decisão manualmente significa alguém observando um painel durante a janela do canary, pronto pra intervir; isso funciona até a regressão acontecer num estágio que ninguém estava encarando.
Rollback automático substitui "alguém observando" por "um guardrail avaliando". O estágio canary carrega uma política baseada em métrica: um limite, uma janela de avaliação, e um abort automático se ela é violada. Não é um mecanismo diferente de qualquer outro rollout em estágios, mas a moldura de canary deixa o risco concreto: essa fatia pequena e específica de tráfego é o raio de explosão que você está limitando de propósito, e o guardrail é o que mantém esse limite real em vez de aspiracional.
Construindo os estágios
Um canary é, na prática, só o primeiro estágio de um rollout em estágios: 5%, depois 25%, depois 50%, depois 100%, cada um programado pra ativar num horário específico, com percentuais-alvo estritamente crescentes e um estágio final que precisa cair em exatamente 100.
POST /v1/environment-flag-configs/{environment_flag_config_id}/rollouts
{
"target_variation_id": "...",
"stages": [
{ "target_percentage": 5, "activate_at": "2026-08-26T14:00:00Z" },
{ "target_percentage": 25, "activate_at": "2026-08-26T14:10:00Z" },
{ "target_percentage": 50, "activate_at": "2026-08-26T14:25:00Z" },
{ "target_percentage": 100, "activate_at": "2026-08-26T14:40:00Z" }
]
}
O guardrail se anexa ao rollout como um todo, não a um estágio individual. Ele avalia continuamente conforme o rollout avança, então uma regressão que só aparece quando o tráfego cruza de 5% pra 25% (um formato comum, já que alguns modos de falha só se manifestam sob concorrência real) ainda é pega, não só as visíveis nos primeiros minutos.
O que "raio de explosão pequeno" realmente exige
O estágio canary de 5% só limita o raio de explosão se a métrica sendo avaliada consegue de fato enxergar um problema em 5% do tráfego. Uma métrica agregada pela frota inteira, diluída pelos outros 95% ainda na versão antiga, pode esconder uma regressão de estágio canary que seria óbvia se escopada corretamente. Se o seu pipeline de métrica consegue fatiar por estágio de rollout ou versão de deploy, vale a pena confirmar antes de confiar num canary de 5% pra de fato pegar o que ele deveria pegar. Um estágio canary com uma métrica que não enxerga isso não está contendo risco, só está atrasando a descoberta pelo tempo que o próximo estágio demorar pra ativar.