DEV Community

Cover image for Blue-Green Deployment para APIs: Como Testar Antes de Entrar em Produção
Lucas
Lucas

Posted on • Originally published at apidog.com

Blue-Green Deployment para APIs: Como Testar Antes de Entrar em Produção

A implantação blue-green promete releases sem downtime: você sobe uma nova cópia do serviço, valida essa cópia e só então muda o tráfego para ela. O ponto crítico é a validação. Um health check de load balancer normalmente chama um endpoint, espera 200 OK e conclui que o processo está vivo. Isso não prova que a nova versão preserva o contrato da API, retorna o JSON esperado, autentica tokens corretamente ou continua compatível com clientes existentes.

Experimente o Apidog hoje

Neste guia, você vai transformar a etapa “testar o verde” em um controle automatizado de release: executar testes reais de API contra o ambiente green antes de qualquer tráfego de produção chegar nele, bloquear a troca se houver falha e integrar isso ao pipeline. Usaremos o Apidog e o Apidog CLI para executar os mesmos cenários criados no desktop dentro do CI.

Se você já usa blue-green, mas valida a nova versão com “alguns cliques rápidos”, este fluxo troca verificação manual por um gate reproduzível. O objetivo é simples: o primeiro usuário real nunca deve ser o primeiro teste real.

TL;DR

Em uma implantação blue-green, você mantém dois ambientes de produção idênticos:

  • Blue: recebe o tráfego atual.
  • Green: recebe a nova versão, ainda sem tráfego público.

Antes de trocar o tráfego do blue para o green:

  1. Implante a nova versão no green.
  2. Execute smoke tests contra o green.
  3. Execute a suíte completa de testes de API contra o green.
  4. Bloqueie a troca se qualquer asserção falhar.
  5. Só então altere o roteador, load balancer, DNS ou service selector.

Health checks confirmam que o processo está vivo. Testes de API confirmam que o contrato continua válido.

O que é implantação blue-green

A implantação blue-green mantém dois ambientes de produção lado a lado. Um ambiente atende os usuários ativos; o outro fica pronto para receber a próxima versão.

O fluxo básico:

  1. O blue está servindo produção.
  2. Você implanta a nova versão no green.
  3. Você testa o green isoladamente.
  4. Se o green passar, troca o tráfego para ele.
  5. O blue fica disponível para rollback.

A vantagem é operacional:

  • Sem janela de manutenção.
  • Troca quase instantânea.
  • Rollback rápido, porque a versão anterior continua ativa e aquecida.
  • Menos risco do que uma rolling deployment, onde uma versão ruim pode começar a atender parte dos usuários antes de você perceber.

Mas o padrão só funciona bem se o green for validado de verdade antes da troca. Se você apenas confirma que /health responde 200, está validando uptime, não comportamento.

Para contextualizar blue-green dentro das práticas de entrega, veja também a comparação entre entrega contínua, implantação contínua e integração contínua.

Por que health check não é teste de API

Um health check típico faz algo assim:

# Load balancer health probe
GET /health -> 200 OK -> mark target healthy
Enter fullscreen mode Exit fullscreen mode

Esse endpoint costuma retornar algo como:

{
  "status": "ok"
}
Enter fullscreen mode Exit fullscreen mode

Isso não garante que:

  • o banco está acessível;
  • as migrations foram aplicadas;
  • a autenticação continua funcionando;
  • os schemas das respostas permanecem compatíveis;
  • os endpoints críticos respondem corretamente;
  • os clientes mobile ou integrações externas continuam compatíveis.

Exemplos de falhas que um /health pode deixar passar:

  • GET /orders/{id} quebra por causa de uma coluna ausente.
  • user_id foi renomeado para userId e quebrou consumidores.
  • Tokens emitidos por clientes antigos agora retornam 401.
  • Datas mudaram de ISO 8601 para timestamp Unix.
  • Um novo header obrigatório causa 400 em clientes existentes.

A solução não é transformar /health em uma suíte gigante. A solução é executar testes reais de API: status code, payload, schema, headers, autenticação, casos negativos e latência.

Essa é a mesma disciplina de teste de contrato de API: garantir que a API em execução continua respeitando o contrato esperado pelos consumidores.

Fluxo blue-green com teste automatizado

Use este fluxo como referência para o pipeline:

  1. Implantar no green Envie a nova build para o ambiente ocioso. Exemplo: 
   https://green.internal.example.com
Enter fullscreen mode Exit fullscreen mode

Nenhum tráfego público deve chegar nele ainda.

  1. Executar smoke test no green

    Rode um cenário curto: login, leitura de recurso crítico, criação simples e leitura de volta. Se falhar, pare.

  2. Executar suíte completa no green

    Rode os testes de API completos: happy paths, erros esperados, autenticação, schemas, headers e regras de negócio.

  3. Bloquear a troca se houver falha

    Se o CLI retornar código diferente de zero, o pipeline deve parar.

  4. Virar a chave

    Altere o load balancer, DNS, service selector ou roteador para enviar tráfego ao green.

  5. Executar smoke test em produção

    Rode o mesmo smoke test contra a URL pública após a troca.

  6. Manter o blue aquecido

    Não desligue o blue imediatamente. Mantenha-o disponível durante a janela de observabilidade e rollback.

A chave é reutilizar os mesmos cenários de teste, mudando apenas a URL base.

Criando os cenários de teste no Apidog

Primeiro, crie uma suíte que realmente valide o comportamento da API. Baixe o Apidog e crie um projeto para o serviço.

No Apidog, um cenário de teste é uma sequência de requisições com:

  • variáveis;
  • autenticação;
  • extração de valores de respostas;
  • asserções;
  • validação de schema;
  • dependência entre etapas.

Para uma API de pedidos, uma suíte inicial pode conter:

1. Fluxo de autenticação 

POST /auth/login
Enter fullscreen mode Exit fullscreen mode

Asserções:

  • status 200;
  • corpo contém access_token;
  • token é salvo em uma variável, por exemplo {{token}}.

2. Listagem de pedidos 

GET /orders
Authorization: Bearer {{token}}
Enter fullscreen mode Exit fullscreen mode

Asserções:

  • status 200;
  • resposta é um array;
  • cada item contém id, status e total.

3. Busca por pedido 

GET /orders/{{orderId}}
Authorization: Bearer {{token}}
Enter fullscreen mode Exit fullscreen mode

Asserções:

  • status 200;
  • schema compatível com a definição OpenAPI;
  • total é número;
  • status pertence a valores esperados.

4. Criação de pedido 

POST /orders
Authorization: Bearer {{token}}
Content-Type: application/json
Enter fullscreen mode Exit fullscreen mode

Payload:

{
  "items": [
    {
      "sku": "SKU-001",
      "quantity": 1
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Asserções:

  • status 201;
  • id retornado não está vazio;
  • o pedido criado pode ser recuperado com GET /orders/{id}.

5. Casos negativos

Token inválido:

GET /orders
Authorization: Bearer invalid-token
Enter fullscreen mode Exit fullscreen mode

Asserção:

status = 401
Enter fullscreen mode Exit fullscreen mode

Campo obrigatório ausente:

POST /orders
Authorization: Bearer {{token}}
Content-Type: application/json
Enter fullscreen mode Exit fullscreen mode

Payload inválido:

{
  "items": []
}
Enter fullscreen mode Exit fullscreen mode

Asserção:

status = 400
Enter fullscreen mode Exit fullscreen mode

Esses casos negativos são importantes. Uma API que aceita token inválido ou payload incompleto pode passar em happy paths, mas ainda assim estar quebrada.

Use variável para a URL base

Não coloque URLs fixas dentro das requisições:

https://blue.example.com/orders
Enter fullscreen mode Exit fullscreen mode

Prefira uma variável:

{{baseUrl}}/orders
Enter fullscreen mode Exit fullscreen mode

Depois, configure ambientes como:

Produção: https://api.example.com
Blue:     https://blue.internal.example.com
Green:    https://green.internal.example.com
Local:    http://localhost:3000
Enter fullscreen mode Exit fullscreen mode

Assim, a mesma suíte roda contra qualquer ambiente. Você só troca o alvo.

Esse padrão também ajuda a separar secrets, tokens e variáveis por ambiente. Veja mais no guia sobre cliente de API com gerenciamento de ambiente e segredos.

Para organizar vários cenários em um único gate executável, use suítes de teste.

Executando a suíte com Apidog CLI

O desktop é útil para criar e depurar os cenários. O CLI é o que roda no pipeline.

Instale com npm:

npm install -g apidog-cli
Enter fullscreen mode Exit fullscreen mode

Requisito: Node.js v16 ou superior.

No Apidog, gere uma configuração de CI para o cenário ou suíte. O comando terá este formato:

apidog run "https://api.apidog.com/api/v1/api-test/ci-config/<config-id>/detail?token=<token>" \
  -r html,cli \
  --out-file green-readiness
Enter fullscreen mode Exit fullscreen mode

As flags principais:

  • -r cli: imprime o resultado no terminal.
  • -r html: gera relatório HTML.
  • --out-file: define o nome do relatório.
  • código de saída diferente de zero: indica falha e deve bloquear o pipeline.

Para rodar contra o ambiente green:

apidog run "<ci-config-url>" \
  --environment "<greenEnvironmentId>" \
  -r cli,html \
  --out-file green-pre-switch
Enter fullscreen mode Exit fullscreen mode

Se você preferir versionar os testes no repositório, também pode executar dados exportados:

apidog run --exported-data ./tests/orders-readiness.json \
  --variables ./tests/green.variables.json \
  -r cli
Enter fullscreen mode Exit fullscreen mode

Para mais detalhes sobre execução em CI/CD, veja como automatizar testes de API em CI/CD.

O comportamento mais importante para blue-green é este: se qualquer asserção falhar, o CLI falha. Isso permite usar os testes como gate antes da troca de tráfego.

Exemplo com GitHub Actions

Este workflow assume que:

  • deploy-green implanta a build no ambiente green;
  • test-green executa a suíte contra o green;
  • switch-traffic só roda se test-green passar. 
name: deploy-blue-green

on:
  push:
    branches: [main]

jobs:
  deploy-green:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Deploy build to green environment
        run: ./scripts/deploy-green.sh

      # green is now reachable at https://green.internal.example.com

  test-green:
    needs: deploy-green
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Apidog CLI
        run: npm install -g apidog-cli

      - name: Run readiness suite against green
        run: |
          apidog run "${{ secrets.APIDOG_CI_CONFIG_URL }}" \
            --environment "${{ vars.GREEN_ENV_ID }}" \
            -r cli,html \
            --out-file green-readiness

      - name: Archive HTML report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: green-readiness-report
          path: ./green-readiness.html

  switch-traffic:
    needs: test-green
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Flip router from blue to green
        run: ./scripts/switch-to-green.sh

      - name: Smoke test production URL post-switch
        run: |
          npm install -g apidog-cli
          apidog run "${{ secrets.APIDOG_SMOKE_CONFIG_URL }}" \
            --environment "${{ vars.PROD_ENV_ID }}" \
            -r cli
Enter fullscreen mode Exit fullscreen mode

O controle acontece por dependência de jobs:

needs: test-green
Enter fullscreen mode Exit fullscreen mode

Se test-green falhar, switch-traffic não inicia.

Boas práticas:

  • salve a URL/token da configuração de CI em secrets;
  • salve IDs de ambiente em vars;
  • sempre publique o relatório HTML com if: always();
  • mantenha logs do CLI para depuração rápida.

O mesmo padrão vale para GitLab CI, Jenkins, CircleCI e Azure Pipelines: a etapa de teste precisa falhar o pipeline antes da etapa de troca.

Veja também o guia de automação de testes de API no GitHub Actions.

Smoke test primeiro, suíte completa depois

Não espere uma suíte de 12 minutos para descobrir que o login está quebrado. Divida em duas camadas.

Smoke test

Objetivo: falhar rápido.

Inclua 3 a 5 requisições críticas:

  1. login;
  2. leitura de recurso principal;
  3. criação simples;
  4. leitura do recurso criado;
  5. caso negativo básico, se fizer sentido.

Tempo ideal: menos de 30 segundos.

Suíte completa

Objetivo: cobertura.

Inclua:

  • todos os endpoints críticos;
  • happy paths;
  • casos de erro;
  • autenticação e autorização;
  • validação de schema;
  • paginação;
  • headers;
  • rate limit;
  • regras de negócio;
  • checagens de latência.

Essa divisão segue a lógica de cenário de teste vs. caso de teste: o smoke test dá sinal rápido; a suíte completa dá confiança de release.

Cuidado com dados de teste

O green pode estar conectado a dados reais ou quase reais. Então trate testes de escrita com cuidado.

Opções práticas:

  • usar uma conta de teste dedicada;
  • criar registros com prefixo rastreável, como test-bluegreen-*;
  • limpar dados criados ao final da execução;
  • rodar testes destrutivos apenas em staging;
  • separar testes de leitura em produção e testes de escrita em ambiente controlado.

O objetivo é validar comportamento sem poluir produção. Se estiver desenhando essa separação, vale entender a diferença entre sandbox e ambiente de teste.

Erros comuns em blue-green

1. Testar o blue em vez do green

Se a suíte aponta para a URL pública atual, você está testando a versão antiga.

Antes da troca, a URL alvo precisa ser explicitamente o green:

https://green.internal.example.com
Enter fullscreen mode Exit fullscreen mode

2. Validar apenas status code

Um 200 OK com payload errado ainda é uma falha.

Além do status, valide:

  • campos obrigatórios;
  • tipos;
  • formato de datas;
  • valores esperados;
  • headers;
  • schema OpenAPI/JSON Schema.

3. Ignorar casos negativos

Inclua testes como:

  • token inválido deve retornar 401;
  • usuário sem permissão deve retornar 403;
  • payload inválido deve retornar 400;
  • recurso inexistente deve retornar 404.

4. Desligar o blue cedo demais

Rollback rápido só existe se o blue continuar disponível. Mantenha-o durante a janela de monitoramento pós-release.

5. Hardcode de URLs

Evite isto:

GET https://blue.example.com/orders
Enter fullscreen mode Exit fullscreen mode

Use isto:

GET {{baseUrl}}/orders
Enter fullscreen mode Exit fullscreen mode

6. Tratar health check como gate de release

Health check responde: “o processo está vivo?”

Teste de API responde: “a API ainda funciona para os consumidores?”

Você precisa dos dois, mas eles não têm o mesmo papel.

Blue-green vs. canary vs. rolling

Estratégia Como o tráfego se move Onde o teste de API se encaixa
Blue-green Tudo de uma vez, do blue para o green Suíte completa contra o green antes da troca
Canary Gradualmente, pequena porcentagem para a nova versão Asserções e monitoramento contínuos na fatia canary
Rolling Instância por instância, no mesmo ambiente Verificações rápidas por instância; controle mais difícil porque a implantação já está em andamento
Recreate Para o antigo e inicia o novo Suíte roda durante a janela de downtime

O blue-green oferece um ponto de controle muito limpo: o green está totalmente implantado, isolado e acessível antes de receber usuários. Para APIs, isso torna a suíte pré-troca uma das formas mais simples de reduzir risco sem criar janela de manutenção.

Como isso aparece no mundo real

Uma equipe de fintech com API de pagamentos pode usar uma suíte de prontidão cobrindo:

  • autenticação;
  • chaves de idempotência;
  • arredondamento de moeda;
  • status de transações;
  • assinaturas de webhook;
  • casos negativos de autorização.

Nada vai para produção até que a suíte passe contra o green. O relatório HTML vira evidência da implantação.

Uma equipe SaaS com API pública pode priorizar:

  • validação de schema;
  • compatibilidade com integrações;
  • campos obrigatórios;
  • paginação;
  • formatos de data;
  • headers.

Nesse caso, a maior preocupação é evitar quebra para clientes externos que dependem do contrato da API.

Em ambos os casos, os cenários são criados uma vez no Apidog e executados automaticamente pelo CLI em cada release.

Checklist de implementação

Use este checklist para adaptar ao seu pipeline:

  • [ ] Criar cenários de teste no Apidog.
  • [ ] Cobrir autenticação, leitura, escrita e casos negativos.
  • [ ] Adicionar asserções de schema e payload.
  • [ ] Usar {{baseUrl}} em vez de URLs fixas.
  • [ ] Criar ambiente Green no Apidog.
  • [ ] Gerar configuração de CI.
  • [ ] Instalar apidog-cli no pipeline.
  • [ ] Rodar smoke test contra o green.
  • [ ] Rodar suíte completa contra o green.
  • [ ] Bloquear switch-traffic se o CLI falhar.
  • [ ] Rodar smoke test pós-troca contra produção.
  • [ ] Manter o blue disponível para rollback.

Conclusão

Blue-green dá a você uma cópia completa da produção antes do release. Não desperdice isso validando apenas /health.

O gate mínimo recomendado é:

  1. smoke test contra o green;
  2. suíte completa de API contra o green;
  3. troca de tráfego somente se tudo passar;
  4. smoke test pós-troca;
  5. blue mantido para rollback.

Configure isso uma vez e cada implantação passa pelo mesmo controle automaticamente. Crie a suíte no Apidog, gere a configuração de CI e adicione apidog run antes da etapa que muda o tráfego.

FAQ

O que é implantação blue-green em termos simples?

É manter dois ambientes de produção idênticos e alternar o tráfego entre eles. O blue atende usuários enquanto o green recebe a nova versão. Depois de testar o green, você troca o tráfego para ele. O blue fica como fallback para rollback.

Como testar o ambiente green antes de alternar o tráfego?

Aponte sua suíte de testes de API para a URL base do green e execute-a no pipeline antes da etapa de troca. Com o Apidog CLI, rode apidog run contra o ambiente green e bloqueie a implantação se qualquer asserção falhar.

Por que health check do load balancer não é suficiente?

Porque ele normalmente só confirma que um endpoint responde 200. Ele não valida schema, autenticação, migrations, payloads, regras de negócio ou compatibilidade com clientes.

Posso rodar no CI os testes criados no desktop?

Sim. Os cenários criados visualmente no Apidog podem ser executados pelo Apidog CLI em GitHub Actions, GitLab CI, Jenkins ou qualquer pipeline.

Qual a diferença entre blue-green e canary para testes?

No blue-green, você testa o ambiente completo antes de enviar tráfego. No canary, você envia uma pequena porcentagem de tráfego para a nova versão e depende mais de monitoramento em tempo real.

Devo executar testes de escrita no green de produção?

Com cuidado. Use contas de teste, dados rastreáveis e limpeza automática. Para testes destrutivos ou com risco de poluição de dados, prefira staging ou uma base isolada.

Qual deve ser a velocidade do gate pré-troca?

Rode um smoke test em menos de 30 segundos para falhar rápido. Depois, execute a suíte completa. Algumas dezenas de cenários levando poucos minutos costumam ser aceitáveis como gate de release.

Top comments (0)