Design de Pipeline de Implantação

Padrões de arquitetura para pipelines CI/CD multi-estágio com portões de aprovação, estratégias de implantação e fluxos de trabalho de promoção de ambiente.

Propósito

Projetar pipelines de implantação robustos e seguros que equilibrem velocidade com segurança através da organização adequada de estágios, portões de qualidade automatizados e estratégias de entrega progressiva. Esta habilidade abrange tanto o design estrutural da arquitetura do pipeline quanto os padrões operacionais para implantações de produção confiáveis.

Entrada / Saída

O Que Você Fornece

• Tipo de Aplicação: Linguagem/runtime, conteinerizada ou bare-metal, monolito ou microsserviços
• Destino de Implantação: Kubernetes, ECS, VMs, serverless ou plataforma-como-serviço
• Topologia de Ambiente: Número de ambientes (dev/staging/prod), layout de região, requisitos de air-gap
• Requisitos de Rollout: Tempo de inatividade aceitável, SLA de rollback, necessidades de divisão de tráfego, preferência por canary vs blue-green
• Restrições de Portão: Equipes de aprovação, limiares de cobertura de teste exigidos, verificações de conformidade (SAST, DAST, SCA)
• Stack de Monitoramento: Prometheus, Datadog, CloudWatch ou outras fontes de métricas usadas para decisões de promoção automatizadas

O Que Esta Habilidade Produz

• Configuração do Pipeline: Definições de estágio, dependências de job, paralelismo e estratégia de cache
• Estratégia de Implantação: Padrão de rollout escolhido com configuração anotada (pesos canary, switchover blue-green, parâmetros de rolling)
• Configuração de Verificação de Saúde: Probes de prontidão rasas vs. profundas, scripts de teste de fumaça pós-implantação
• Definições de Portão: Limiares de métricas automatizados e fluxos de trabalho de aprovação manual
• Plano de Rollback: Gatilhos de rollback automatizados e etapas manuais do runbook

Quando Usar

• Projetar arquitetura CI/CD para um novo serviço ou migração de plataforma
• Implementar portões de implantação entre ambientes
• Configurar pipelines multi-ambiente com escaneamento de segurança obrigatório
• Estabelecer entrega progressiva com estratégias canary ou blue-green
• Depurar pipelines onde os estágios são bem-sucedidos, mas o comportamento de produção está incorreto
• Reduzir o tempo médio de recuperação automatizando o rollback em caso de degradação de métricas

Padrões Detalhados e Exemplos Trabalhados

A documentação detalhada dos padrões reside em references/details.md. Leia esse arquivo quando o nível de navegação acima for insuficiente.

Solução de Problemas

Verificação de saúde passa no pipeline, mas o serviço está com a saúde comprometida em produção

A verificação de saúde do pipeline está atingindo um endpoint /ping superficial que retorna 200 mesmo quando o banco de dados está inacessível. Use uma verificação de prontidão profunda que verifica as dependências reais (veja a seção Verificações de Saúde acima).

Implantação canary nunca promove para 100%

Argo Rollouts requer uma AnalysisTemplate válida para auto-promoção. Se a consulta Prometheus não retornar dados (por exemplo, o nome da métrica mudou), a análise permanece inconclusiva e a promoção estagna. Adicione inconclusiveLimit para que o rollout falhe rapidamente em vez de travar:

spec:
  metrics:
  - name: error-rate
    failureCondition: "result[0] > 0.05"
    inconclusiveLimit: 2   # fail after 2 inconclusive results, not hang indefinitely
    provider:
      prometheus:
        query: |
          sum(rate(http_requests_total{status=~"5.."}[2m]))
          / sum(rate(http_requests_total[2m]))

Implantação staging é bem-sucedida, mas o job de produção nunca inicia

Verifique se as regras de proteção do ambiente de produção estão configuradas — uma atribuição de revisor ausente significa que o portão de aprovação espera indefinidamente sem notificação. No GitHub Actions, certifique-se de que Required reviewers esteja definido para um usuário ou equipe existente em Settings → Environments → production.

Cache de camada Docker corrompido a cada execução, causando builds lentos

Se COPY . . aparecer antes da instalação de dependências, qualquer alteração no arquivo de origem invalida a camada de dependências. Reordene para copiar os manifestos de dependência primeiro:

# Good: dependencies cached separately from source code
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

Rollback deixa migrações de banco de dados aplicadas ao código antigo

Um rollback de serviço sem rollback de migração causa erros de incompatibilidade de esquema/código. Sempre torne as migrações retrocompatíveis (apenas aditivas) por pelo menos um ciclo de lançamento e mantenha os scripts de desfazer versionados junto com a migração:

# migrations/V20240315__add_nullable_column.sql       (forward)
# migrations/V20240315__add_nullable_column.undo.sql  (backward)

…