Canary Deploy no Node.js

O Canary Deploy no Node.js libera uma nova versão para uma pequena parte do tráfego antes de promovê-la para todos. A equipe observa erros, latência, recursos e métricas de negócio em produção real, limitando o impacto de uma regressão.

Diferentemente de Blue-Green, que troca todo o tráfego entre dois ambientes, canary altera o peso gradualmente: 1%, 5%, 25%, 50% e 100%, por exemplo. A estratégia exige roteamento confiável, métricas separadas por versão e compatibilidade de dados entre versões antigas e novas.

Neste guia, você aprenderá a configurar pesos, escolher grupos, usar Kubernetes e Nginx, definir critérios de promoção, controlar sessões, banco, workers, feature flags, rollback, observabilidade e automação.

O que é Canary Deploy?

Canary deployment expõe a nova versão a uma amostra controlada. A documentação oficial de Deployments do Kubernetes explica rollouts básicos. A documentação oficial do Argo Rollouts sobre Canary apresenta passos, análises e controle de tráfego.

Para uma troca integral de ambientes, consulte Blue-Green Deploy no Node.js. Para controlar comportamento dentro da mesma versão, veja Feature Flags no Node.js.

Fluxo gradual

1. Implantar a versão canary.
2. Esperar readiness.
3. Enviar pequena fração do tráfego.
4. Observar métricas por um período.
5. Aumentar o peso.
6. Repetir a análise.
7. Promover para 100% ou abortar.

Por que começar pequeno?

Uma falha que afeta 1% dos usuários é mais fácil de conter que uma falha global. O primeiro passo deve ser grande o suficiente para gerar sinal, mas pequeno o suficiente para limitar impacto.

Peso no Nginx

upstream node_backend {
    server 127.0.0.1:3001 weight=99;
    server 127.0.0.1:3002 weight=1;
}

O balanceamento por requisição é aproximado e depende de conexões, keep-alive e algoritmo.

Peso com Kubernetes

Um Service comum distribui tráfego entre pods conforme endpoints, mas não oferece porcentagem precisa por versão. Se houver 9 pods estáveis e 1 canary, a divisão tende a aproximadamente 10%, embora conexões e topologia influenciem.

Ingress e service mesh

Ingress controllers e meshes podem dividir tráfego por peso, header, cookie ou usuário. Verifique a implementação e sua consistência.

Argo Rollouts

strategy:
  canary:
    steps:
      - setWeight: 5
      - pause:
          duration: 10m
      - setWeight: 25
      - pause:
          duration: 20m
      - setWeight: 50
      - pause:
          duration: 30m

O controlador pode integrar análises e abortar automaticamente.

Readiness antes do tráfego

A versão canary precisa validar configuração, conexão, cache e servidor antes de entrar no roteamento.

Consulte Probes Kubernetes em Node.js.

Smoke tests

Antes de liberar tráfego real, execute testes internos contra a versão canary:

• health endpoint;
• autenticação;
• leitura de recurso;
• escrita idempotente;
• integração crítica;
• versão do artefato.

Roteamento aleatório

Dividir cada requisição aleatoriamente funciona para operações sem estado, mas o mesmo usuário pode alternar entre versões.

Roteamento consistente

Para manter um usuário na mesma versão, use hash de cookie, usuário ou organização. O identificador não deve permitir falsificação que conceda acesso indevido.

Header de canary

X-Canary: true

Um header pode liberar a equipe interna. O proxy deve removê-lo ou validar origem para impedir que qualquer cliente force a versão.

Cookie de afinidade

Um cookie assinado pode manter a variante. Evite cookies permanentes após a promoção.

Usuários internos

Comece com contas de teste e equipe antes do percentual público. Isso aumenta sinal qualitativo sem expor clientes.

Canary por região

Uma região pode receber a versão primeiro. Considere diferenças de tráfego, legislação e dependências; uma região pequena pode não representar o restante.

Canary por tenant

Em B2B, selecione organizações que aceitaram participar. Não divida membros do mesmo tenant se o comportamento compartilhado precisa ser consistente.

Métricas por versão

Adicione label de baixa cardinalidade:

release="1.9.0"
deployment_track="canary"

Compare com a versão estável no mesmo período.

Métricas técnicas

• taxa de erro;
• latência p50, p95 e p99;
• CPU;
• memória;
• event loop delay;
• pool de banco;
• timeouts;
• retries;
• fila.

Consulte Métricas Prometheus no Node.js.

Métricas de negócio

• conversão;
• pagamentos aprovados;
• pedidos concluídos;
• cancelamentos;
• tempo de checkout;
• abandono;
• tickets de suporte.

Uma versão tecnicamente saudável pode prejudicar resultado de negócio.

Amostra pequena

Em 1% de baixo tráfego, alguns erros não aparecem. Defina tempo mínimo e quantidade mínima de requisições antes da promoção.

Intervalo de análise

Um intervalo de cinco minutos pode detectar crash, mas não vazamento lento ou job diário. Ajuste janela ao risco da mudança.

Critérios de promoção

Exemplos:

• taxa de erro não superior à estável mais margem;
• p95 dentro do SLO;
• sem nova issue crítica;
• memória sem crescimento anormal;
• métrica de negócio preservada;
• mínimo de requisições atingido.

Critérios de aborto

Defina antes do deploy. Durante incidente, decisões improvisadas demoram e aumentam impacto.

Análise automática

Um controlador pode consultar Prometheus:

sum(rate(http_requests_total{
  release="canary",
  status_class="5xx"
}[5m]))
/
sum(rate(http_requests_total{
  release="canary"
}[5m]))

A query precisa tratar ausência de tráfego e séries incompletas.

Logs por release

Inclua release e track em logs. Consulte Logs com Pino no Node.js.

Sentry por release

Uma nova issue apenas na canary é um sinal de aborto. Consulte Sentry no Node.js.

Traces

Compare spans de banco, HTTP e filas entre versões. Mantenha sampling suficiente na canary para obter sinal.

Banco compartilhado

Versões estável e canary usam o mesmo banco. Migrations precisam ser retrocompatíveis.

Expand and contract

1. Adicionar estrutura nova.
2. Implantar código capaz de usar estrutura antiga e nova.
3. Liberar canary.
4. Migrar dados.
5. Promover.
6. Remover compatibilidade em deploy posterior.
7. Eliminar estrutura antiga por último.

Escrita em formatos diferentes

Se a canary grava dados que a estável não entende, uma requisição futura roteada à estável pode falhar. Mantenha formato compatível ou afinidade.

Schema de eventos

Mensagens publicadas pela canary podem ser consumidas por versões antigas. Adicione campos opcionais e preserve semântica.

Filas e workers

Tráfego HTTP de 5% não significa 5% dos jobs. Se a canary também consome a mesma fila, pode processar proporção imprevisível.

Crie fila canary, limite consumidores ou faça rollout separado de workers.

Cron jobs

Não execute cron duplicado na canary sem lock ou desenho idempotente.

Idempotência

Retries e processamento paralelo exigem proteção. Consulte Idempotência em APIs Node.js.

Sessões

Sessão em memória quebra ao alternar versão. Use armazenamento compartilhado ou cookies assinados.

Cache

Cache compartilhado deve aceitar dados de ambas as versões. Inclua versão na chave apenas se a separação for necessária e o custo estiver previsto.

Feature flags e canary

Canary controla quem recebe o binário novo. Feature flag controla qual comportamento executa. Uma canary pode iniciar com a flag desligada e ativá-la gradualmente.

Configuração

Não altere simultaneamente código, configuração e infraestrutura sem separar sinais. Use configuração versionada e auditada.

Secrets

A canary pode exigir outra credencial. Mantenha compatibilidade e não revogue o segredo da versão estável durante o rollout.

Rollback

Abortar significa remover tráfego e escalar a canary para zero ou versão anterior. A ação deve ser automática e rápida.

Rollback de dados

Retirar tráfego não desfaz dados, eventos ou chamadas externas. O desenho precisa permitir que a versão estável continue operando.

Drenagem

Ao abortar, marque pods canary como not ready, aguarde conexões e encerre com SIGTERM.

Consulte Graceful Shutdown no Node.js.

WebSocket

Uma conexão permanece na versão escolhida. Métricas por requisição podem não representar sessões longas. Planeje reconexão e drenagem.

Capacidade

A versão estável precisa suportar 100% caso a canary seja abortada. Não reduza capacidade estável cedo demais.

Autoscaling

Uma canary pequena pode não escalar como produção e esconder problemas de concorrência. Inclua teste de carga antes e aumente réplicas durante etapas maiores.

Cold start

O primeiro tráfego pode sofrer cache frio ou compilação. Aqueça endpoints controladamente antes de medir.

Pipeline

1. Construir imagem por digest.
2. Executar testes.
3. Implantar canary.
4. Esperar readiness.
5. Executar smoke test.
6. Definir peso inicial.
7. Analisar métricas.
8. Promover em etapas.
9. Finalizar ou abortar.

Aprovação manual

Mudanças críticas podem exigir aprovação entre etapas. A pessoa deve ver métricas e diferenças, não apenas um botão.

Tempo máximo

Defina prazo para rollout. Uma canary pausada indefinidamente mantém duas versões e aumenta complexidade.

Auditoria

Registre pesos, horários, responsável, critérios, métricas e decisão final.

Testes de estratégia

Em homologação:

• gere erro na canary;
• confirme detecção;
• aborte automaticamente;
• verifique drenagem;
• confirme que estável assume tráfego;
• valide dados criados.

Erros comuns

• Sem labels por versão: métricas são misturadas.
• Promover por tempo apenas: regressão não é avaliada.
• Amostra pequena demais: não há sinal.
• Migration incompatível: versão estável quebra.
• Worker não controlado: canary processa muitos jobs.
• Sessão local: usuários alternam e perdem estado.
• Rollback não testado: impacto continua.

Boas práticas

• Use artefato imutável.
• Comece com usuários internos.
• Separe métricas por release.
• Defina mínimo de tráfego.
• Automatize critérios.
• Mantenha dados compatíveis.
• Controle workers e cron.
• Preserve capacidade estável.
• Automatize aborto.
• Registre todo o rollout.

Conclusão

O Canary Deploy no Node.js reduz risco ao expor a nova versão gradualmente e comparar seu comportamento com a versão estável. Pesos, targeting e pausas controlam a progressão.

O sucesso depende de métricas por release, amostra suficiente, banco compatível e rollback automático. Quando workers, sessões e dados também são considerados, canary transforma produção em uma etapa observável de validação sem tratar usuários como um teste descontrolado.