Canary Deployment

Canary Deployment

O Canary Deployment fecha o gap entre release-manager (skill 24, que decide o que sai) e deploy (skill 07, que coloca em producao): assume um artefato ja aprovado, promove em fatias controladas e observa metricas em tempo real para decidir progredir ou reverter. O objetivo nao e empacotar — e limitar o impacto de uma regressao desconhecida.

Governanca Global

Esta skill segue GLOBAL.md, policies/execution.md, policies/handoffs.md, policies/quality-gates.md, policies/verification-before-completion.md (toda transicao de step exige output verificavel da metrica que liberou a passagem) e policies/stack-flexibility.md (sem amarrar a runtime especifico).

Gate contra constituicao

Quando memory/constitution.md existe:

• baseline de SLOs do eixo Performance precisa estar registrado antes do step 1%
• error budget restante precisa cobrir o experimento canary (caso quebre, consome budget)
• principios de Security: artefato precisa ter passado por skill 06 e 34 antes de qualquer step
• Observability: stack de monitoramento precisa expor as metricas listadas abaixo em tempo

proximo a real (lag aceitavel 22), framework major, schema de cache incompativel. Custo: dobra a infra temporariamente.

Metricas a Observar

Configurar dashboard unificado e thresholds antes de iniciar o step 1%. Comparar sempre canary vs stable lado a lado, nao canary vs baseline historico (variacao de carga confunde).

| Metrica | Default threshold | Janela de avaliacao | Acao se quebrar | |---|---|---|---| | Error rate (5xx/total) | canary = stable * 0.95 (perda max 5%) | janela conforme volume | alerta + decisao humana | | 5xx rate por endpoint | nenhum endpoint > 2% em canary | ultimos 5 min | rollback automatico | | Saturacao (CPU, memoria, conexoes) | canary 30 min em step pequeno) atrasa deteccao real

• ao subir o percentual, recalcular baseline do step anterior — variacao de carga muda referencia

Rollback Automatico

Gatilhos que disparam reversao sem intervencao humana:

1. Threshold quebrado em N samples consecutivos — N >= 2 evita flap de um pico isolado;

usar janela rolling para nao penalizar warmup

1. Alarme externo de paginacao — se o sistema de alertas (PagerDuty, OpsGenie, Alertmanager)

abrir incidente vinculado ao servico em rollout, abortar

1. Abort manual — botao/comando explicito (ex: kubectl rollout undo, flag kill switch,

switch blue-green) com permissao de qualquer on-call

1. Timeout de step — se um step nao converge (metrica oscila perto do threshold) por mais

que o dobro da janela esperada, abortar para evitar drift

Procedimento de rollback (deve estar testado em staging):

1. Acionar reversao do step (weighting volta para 100% stable, flag desligada,
   switch blue-green revertido)
2. Confirmar via dashboard que trafego retornou para versao anterior ( ] step 10% iniciado
- baseline: error 0.3%, p95 240ms
- canary atual: error 0.4%, p95 252ms (+5%)
- soak: 30 min, proxima decisao em ~15:42
- dashboard: 
- abort: 

Updates obrigatorios:

• inicio de cada step com baseline e thresholds
• promocao para proximo step (com snapshot das metricas)
• rollback (motivo + janela + link do postmortem)
• conclusao em 100% (release oficialmente cerrada)

Integracao com Pipeline

• vem depois de skill 24 (release-manager): release plan ja definido, changelog publicado,

on-call ciente. Canary executa o "como" do rollout que release-manager planejou

• vem depois de skill 07 (deploy-docker): artefato ja buildado e publicado no registry;

canary nao reconstroi nada, so manipula roteamento/flag

• integra com skill 20 (observability-sre): dashboards e SLOs sao pre-requisito; pos-rollout,

observability conduz analise de impacto

• integra com skill 34 (static-analysis): se rollback for disparado por classe de bug conhecida,

registrar para evolucao das regras de scan

• handoff de saida: se 100% ok, devolve para release-manager fechar a release; se rollback,

abre ciclo de postmortem com observability + reviewer

Evidencia de Conclusao

• rollout plan documentado com steps, percentuais, soak e thresholds
• dashboard de watch com metricas lado a lado (canary vs stable) acessivel
• rollback runbook testado em staging com tempo medido (< 5 min)
• registro cronologico de cada transicao (timestamp, metrica, decisao)
• se rollback: postmortem aberto e causa raiz identificada
• se sucesso: snapshot das metricas em 100% comparado ao baseline historico
• comunicacao registrada no canal acordado

Handoff

Seguir policies/handoffs.md. Devolver para skill 24 (release-manager) em caso de sucesso para encerrar release oficial, ou para skill 20 (observability-sre) em caso de rollback para conduzir analise de causa raiz.

Fontes Externas

Estrategia base e thresholds adaptados do slash command /canary do repositorio garrytan/gstack (licenca MIT). Conceitos de error budget e janela de soak alinhados com Google SRE Book (capitulos 4 e 8). Pattern de blue-green e canary documentado em Continuous Delivery (Humble & Farley, 2010).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: felvieira
• Source: felvieira/claude-skills-fv
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.