Ambassador

Um proxy ao lado da aplicação cuida das chamadas de saída para um serviço externo: a aplicação chama 127.0.0.1:6050 como se fosse o provedor, e o ambassador (Envoy) injeta a credencial do parceiro, aplica timeout por tentativa, retenta com backoff, tira do ar um provedor que só falha e registra cada chamada. Nada disso fica no código da aplicação — e vale igual para qualquer aplicação, em qualquer linguagem, que use o mesmo ambassador.

passos: 6
arquivos: 7
testes: 0
tecnologias: 5

Infraestrutura realTypeScriptBunElysiaEnvoyDocker

Cenário Relações Comparar

Baixar cartão

Cenário

Antes de liquidar cada PIX, o serviço de pagamentos consulta um provedor externo de antifraude que exige chave de parceiro e às vezes responde 503 sob carga. A aplicação não tem a chave nem lógica de retry: chama o ambassador. Duas falhas seguidas do provedor viram uma resposta 200 para a aplicação; com o provedor fora do ar, cinco falhas seguidas o ejetam, e as consultas seguintes falham na hora, sem esperar nem martelar o provedor.

Planta

Sequência

8/8

8 passos — reproduza para seguir o fluxo

chamada
resposta ou assíncrono
falha
passo
toque num participante para focar
Outras plantas de sequência

Como funciona

6 passos

Proxy local fala com o mundo externo.

Esconde cada passo: lembre antes de tocar para revelar.

Vocabulário compartilhado

request_headers_to_add+1

Ambassador

retry_policy+1

Ambassador

per_try_timeout+1

Service Mesh

outlier_detection+1

Ambassador

/stats/prometheus+1

Sidecar

01
A aplicação só conhece AMBASSADOR_URL; o envoy.yaml aponta o cluster antifraud_provider para o endereço real
02
request_headers_to_add injeta x-api-key em toda chamada de saída — a credencial fica no proxy
03
retry_policy: até 2 retentativas em 5xx, reset ou falha de conexão, com per_try_timeout de 300 ms e backoff de 25 a 100 ms; a chamada inteira tem teto de 1 s
04
outlier_detection ejeta o provedor após 5 respostas 5xx seguidas; healthy_panic_threshold: 0 impede o Envoy de mandar tráfego para o host ejetado
05
O access log em JSON traz status, flags e número de tentativas de cada chamada
06
ambassadorMetrics lê em /stats/prometheus o total de chamadas, retentativas e ejeções

Trade-offs

O que se ganha, o que se paga

4 vantagenscada ganho tem um preço4 custos

Vantagens

Retry, timeout e credencial iguais para toda aplicação, em qualquer linguagem
A aplicação nunca vê a chave do parceiro
Ejeção corta chamadas a um provedor fora do ar
Métricas e logs de saída sem código na aplicação

Custos

Um salto a mais, em localhost, por chamada
A chave no envoy.yaml é só para desenvolvimento; em produção vem de um secret (SDS)
Um processo extra para operar e monitorar por instância
Retry no proxy exige que o provedor seja idempotente na operação retentada

apps/observability/ambassador

7 arquivos

envoy/

envoy.yamlinfraListener de saída, chave do parceiro, retry, timeout, ejeção e access log

src/

client_payments.tsA chamada da aplicação: um fetch simples para o ambassador
antifraud_provider.tsProvedor externo em ElysiaJS que exige a chave, com falhas em runtime
metrics_ambassador.tsChamadas, retentativas e ejeções lidas das métricas do Envoy
config_ambassador.tsConfiguração validada do ambiente
demo.tsdemoChave injetada, falhas absorvidas e provedor ejetado