Migrando um endpoint específico para Docker e usando CloudFront como camada de transição

Quando uma API pública tem vários paths, a migração não precisa acontecer como uma unidade indivisível.

Em uma operação real de ECS para Docker, um dos padrões usados foi tratar cada endpoint/path como uma peça migrável e validar a nova origem atrás de um CloudFront de homologação antes de mexer na distribuição de produção.

A arquitetura de teste ficou conceitualmente assim:

1
2
3
4
5
6
7
8
9
https://hmg-api.example.com/<path>/...
                ↓
          CloudFront HMG
                ↓
           origin Docker
                ↓
             Traefik
                ↓
               API

Enquanto isso, a origem antiga continuava atendendo produção.

O CloudFront não era só “uma CDN na frente”. Ele virou uma forma de testar a mesma ideia de roteamento público sem usar o tráfego real como laboratório.

O contrato a preservar era o path #

Os serviços migrados tinham URLs finais planejadas em um mesmo domínio de API, diferenciadas por paths.

Algo como:

1
2
3
/api-a
/api-b
/api-c

No ambiente de homologação, cada behavior podia apontar o path correspondente para o Docker host correto.

Isso permitia provar uma pergunta por vez:

“o endpoint X funciona na nova origem quando passa pela camada HTTP que se parece com a produção?”

Sem precisar trocar todos os endpoints juntos.

Primeiro, a API precisava funcionar sem CloudFront #

Antes de criar ou ajustar behavior, a aplicação era validada diretamente.

Exemplo:

1
2
curl -i http://<container-ip>:8080/health
curl -i http://<container-ip>:8080/<path>/health

Depois entrava o Traefik local:

1
2
3
curl -i \
  -H 'Host: hmg-api.example.com' \
  http://127.0.0.1/<path>/health

E só então o origin externo.

Se essa sequência falha antes do CloudFront, não faz sentido começar a alterar behavior para tentar “consertar” a aplicação.

Behavior específico é uma ferramenta de migração #

No CloudFront HMG, o roteamento foi organizado por behaviors de path.

Conceitualmente:

1
2
3
/<path-a>* → origin Docker A
/<path-b>* → origin Docker B
/<path-c>* → origin Docker C

Isso oferece uma propriedade operacional muito útil: cada rota pode ser validada de forma independente.

A migração deixa de ser:

1
CloudFront inteiro → origem nova

para virar:

1
path específico → origem nova

O blast radius do teste cai bastante.

API não deveria depender de cache acidental #

Na fonte desse caso, a policy de API usava cache desabilitado e permitia os métodos necessários além de GET/HEAD.

Esse ponto é importante porque um behavior reaproveitado de conteúdo estático pode introduzir efeitos que nada têm a ver com a aplicação:

cache de resposta que deveria ser dinâmica;
método HTTP bloqueado;
headers não encaminhados;
query strings tratadas de forma diferente;
cookies ausentes;
redirects inesperados.

Quando CloudFront participa da migração, a pergunta não é só “o origin está certo?”.

É também:

“o behavior preserva o contrato HTTP que essa API precisa?”

O hostname do origin e o certificado importam #

Em alguns dos hosts Docker, o Traefik terminava TLS.

Se o CloudFront conecta em HTTPS ao origin usando um hostname que não combina com o certificado apresentado, o teste pode falhar antes mesmo de chegar à API.

Por isso foi usado, quando necessário, um domínio técnico de origin com certificado válido.

A ideia é evitar um cenário como:

1
2
3
CloudFront chama origin por nome A
Traefik apresenta certificado/default cert de nome B
TLS falha

Isso é diferente de a aplicação estar fora.

O teste de origin direto com o Host correto ajuda a separar as duas coisas.

A validação pela borda vinha por último #

Depois de container, path, Traefik e origin:

1
2
curl -Ik https://hmg-api.example.com/<path>/health
curl -i  https://hmg-api.example.com/<path>/health

O primeiro ajuda a enxergar TLS/headers e o segundo confirma o corpo/status esperado.

Na operação que originou esta pauta, múltiplos paths chegaram ao estado HTTP 200 Healthy no CloudFront HMG.

Esse resultado provava a cadeia de homologação.

Não provava ainda que a virada de produção havia sido executada.

A fonte operacional mantinha essa distinção explícita: HMG validado; cutover final ainda dependente de mudança coordenada e aceite.

Por que isso é melhor que apontar produção “só para testar” #

Porque teste e cutover deixam de ser o mesmo evento.

Com uma distribuição de HMG:

1
2
3
4
5
erro de container      → produção intacta
erro de Traefik        → produção intacta
erro de certificado    → produção intacta
erro de behavior       → produção intacta
erro funcional da API  → produção intacta

Quando tudo passa, a virada de produção ainda merece plano e rollback, mas já não carrega as incertezas básicas do novo ambiente.

O que eu registraria antes da virada #

Para cada path:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
path público esperado
origin atual
origin novo
health direto no container
health pelo reverse proxy
health no origin externo
health pelo CloudFront HMG
métodos HTTP necessários
cache policy
headers/query/cookies relevantes
certificado do origin
responsável pela validação funcional
rollback da virada final

Sem esse mapa, vários endpoints no mesmo domínio viram uma massa única e difícil de migrar de forma controlada.

O ponto principal #

CloudFront pode ser mais que a camada que você altera no fim da migração.

Usado com uma distribuição de homologação e behaviors por path, ele pode virar parte da própria estratégia de validação.

Nesse caso, o endpoint novo foi exercitado pela cadeia:

1
CloudFront HMG → origin Docker → Traefik → API

antes de a produção antiga ser desligada ou o CloudFront de produção ser alterado.

A mudança final ainda existia.

Mas ela passou a acontecer depois de o caminho novo já ter acumulado evidência de que funcionava.

E isso é uma diferença enorme entre migrar e apostar.