ambassador.js·5 scenarios
Ambassador pattern: outgoing-only sidecar proxy. App emits plain HTTP/TCP to localhost; ambassador (Envoy/PgBouncer) adds mTLS, retries with jitter, circuit breaker, connection pooling, canary routing, and read/write splitting. Five scenarios: outbound retry, circuit breaker trip, mTLS upgrade with canary, Postgres pool multiplexing, and ambassador-vs-sidecar comparison. ADRs cover ambassador vs library vs full service mesh, and connection pool ownership.
Ambassador нужен там, где приложение должно вызывать внешние сервисы, базы или API, но команда не хочет размазывать сетевую надежность по каждому языку и каждому репозиторию. Типичная проблема выглядит так: один сервис на Go, другой на Node.js, третий на Python, у каждого свой HTTP-клиент, свои retry, свои timeouts, свои TLS-настройки и свои баги. Через год оказывается, что одинаковая политика mTLS, circuit breaker и connection pooling реализована пятью разными способами.
Паттерн выносит исходящие сетевые обязанности в локальный proxy рядом с приложением. App говорит с localhost простым HTTP, TCP или Postgres protocol, а ambassador уже ходит наружу: добавляет mTLS, ретраи с jitter, таймауты, circuit breaker, трассировку, canary routing, read/write splitting или пул соединений. Это особенно полезно в polyglot-среде, где library-based подход быстро превращается в набор несовместимых SDK.
Важно не путать Ambassador с любым sidecar. Sidecar — общий способ положить вспомогательный контейнер рядом с приложением. Ambassador — конкретный sidecar для outgoing-трафика. Он представляет приложение во внешнем мире и делает исходящую связь управляемой.
Представьте, что сервис не знает дипломатический протокол удаленного мира. Он говорит на простом локальном языке: POST localhost:8080 или connect localhost:6432. Ambassador принимает этот локальный разговор, добавляет сертификаты, правила маршрутизации, retry budget, метрики и уже от имени приложения идет к удаленному сервису.
Модель полезна тем, что ответственность становится явной. Приложение отвечает за бизнес-логику и корректные запросы. Ambassador отвечает за транспортную политику: как долго ждать, когда повторять, как ломать цепочку при сбое, какие сертификаты использовать, куда отправить 5 процентов canary-трафика, сколько реальных соединений держать к базе.
ADR-решение обычно формулируется так: если reliability-политика одинакова для многих сервисов и языков, переносим ее в локальный outgoing proxy. Если стек одноязычный и уже есть зрелая клиентская библиотека, библиотека может быть проще. Если нужен и inbound, и outbound контроль с централизованным control plane, стоит смотреть в сторону service mesh.
Диаграмма строит pod с двумя участниками: App (plain client) и Ambassador (Envoy/PgBouncer). Снаружи находятся удаленные сервисы и Postgres-узлы: primary, canary, write primary и read replica. Физические связи показывают только реальные зависимости: app соединяется с ambassador через localhost, ambassador соединяется с внешними системами. Ответы в анимации идут по тем же ребрам в обратную сторону, без добавления ложных reverse edge.
На диаграмме видно несколько важных идей:
Capacity-hint на ambassador показывает, что это не бесплатная абстракция: proxy сам должен выдерживать большой RPS, CPU на TLS и память на соединения. Поэтому ambassador требует sizing, лимитов и observability так же, как любой продакшен-компонент.
Outbound retry with jitter показывает невидимый для приложения retry. App отправляет один запрос на localhost, первая попытка к upstream получает 503, ambassador ждет с decorrelated jitter и делает вторую попытку. Урок: retry должен быть ограничен бюджетом, иначе локальный proxy превратится в усилитель аварии. Хороший ADR здесь фиксирует max attempts, total timeout и какие ошибки считаются retryable.
Circuit breaker trips показывает, что после серии timeout ambassador перестает дергать сломанный upstream и возвращает fail fast. Это снижает latency для caller, не держит threads и дает remote-сервису восстановиться. Trade-off: часть запросов будет падать даже если upstream уже начал оживать, поэтому нужны half-open probes и понятные пороги.
Plain to mTLS upgrade + canary routing объясняет главную операционную ценность паттерна: приложение не знает про сертификаты и canary-логику. Ambassador забирает свежий сертификат, выбирает маршрут по hash от user id и отправляет малую долю трафика в v3. Это decouple deploy/release на сетевом уровне.
Postgres connection pool multiplexing показывает PgBouncer-style ambassador. Много клиентских соединений к localhost мультиплексируются в малый pool реальных backend connections. Для Postgres это критично: база плохо живет с тысячами соединений от десятков реплик приложения. ADR должен явно выбрать transaction или session pooling, потому что prepared statements и session state ведут себя по-разному.
Ambassador vs general sidecar закрепляет терминологию: sidecar — зонтик, ambassador — outbound proxy, adapter — inbound translation, full mesh — двусторонний контроль и control plane.
ADR: Ambassador vs library client. Library client проще по инфраструктуре, не добавляет hop и легче дебажится в одном процессе. Но она привязана к языку и должна быть обновлена во всех сервисах. Ambassador добавляет около одного локального hop, потребляет CPU/RAM и может усложнить трассировку, зато дает polyglot-политику и rollout без пересборки приложений.
ADR: Ambassador vs service mesh. Mesh мощнее: mTLS, policy, tracing и traffic shaping для входящих и исходящих потоков, общий control plane, sidecar injection. Но mesh дороже в эксплуатации и добавляет больше moving parts. Ambassador лучше, когда проблема локальная: только outbound, конкретная база, конкретный внешний API, конкретный retry/circuit breaker policy.
ADR: Pool в приложении vs pool в ambassador. App-side pool понятен разработчикам и лучше поддерживает session semantics. Но 50 реплик с pool size 20 легко дают 1000 соединений к Postgres. Ambassador или PgBouncer сокращает реальные backend connections, но заставляет внимательно работать с prepared statements, transactions, idle timeouts и observability pool saturation.
ADR: Retry в proxy vs retry в бизнес-коде. Proxy хорошо повторяет transport-level ошибки: reset, timeout до отправки тела, 503 от transient overload. Бизнес-код лучше понимает idempotency и semantic retry. Для платежей, заказов и write-операций нельзя просто включить generic retry без idempotency key.
PgBouncer часто работает именно как ambassador для Postgres: приложение подключается к локальному или близкому proxy, а proxy держит контролируемое число backend connections. Envoy в outbound mode добавляет mTLS, retries, circuit breakers, outlier detection и маршрутизацию. Linkerd2-proxy и sidecar-часть Istio решают близкие задачи, но обычно в рамках mesh. Emissary-Ingress исторически связан с названием Ambassador, хотя как продукт чаще воспринимается как ingress/API gateway.
В крупных компаниях аналогичный подход встречается для внешних SaaS API: один локальный proxy стандартизирует auth headers, timeout policy, request signing и audit logging. Это снижает вероятность, что один сервис забудет правильный timeout и повесит worker pool на медленном внешнем провайдере.
Самая частая ошибка — считать ambassador магической надежностью. Если retry budget не ограничен, proxy может умножить нагрузку на уже сломанный upstream. Если timeout приложения больше timeout proxy или наоборот, поведение становится непредсказуемым. Если circuit breaker настроен без метрик и алертов, команда узнает о проблеме только по жалобам пользователей.
Вторая ошибка — скрыть слишком много логики. Ambassador должен заниматься transport и routing policy, а не бизнес-решениями. Если в proxy начинают жить правила скидок, статусы заказов или сложная авторизация предметной области, система получает новый невидимый backend.
Третья ошибка — забыть про observability. Нужны метрики retry count, retry exhausted, circuit state, upstream latency, pool wait time, active connections, TLS errors, route split и error rate по каждому upstream. Без этого ambassador ухудшает debuggability.
Четвертая ошибка — поставить ambassador в каждый pod без capacity-плана. На тысячах pod даже небольшой sidecar overhead превращается в заметную стоимость. Иногда DaemonSet или shared local proxy лучше, но тогда меняются fault isolation и blast radius.
Не используйте Ambassador, если сервисов мало, стек одноязычный и надежный client SDK уже решает timeout, retry, tracing и auth. Не используйте его для простой внутренней функции, где дополнительный proxy усложнит локальную разработку сильнее, чем поможет эксплуатации.
Не стоит вводить ambassador как замену service mesh, если уже нужны inbound policies, zero-trust между всеми сервисами, централизованный control plane и единая telemetry-сетка. В такой ситуации отдельные ambassadors могут стать временным переходным решением, но не целевой архитектурой.
Не используйте generic proxy retry для неидемпотентных операций без idempotency key. Для платежей, бронирований и создания заказов повтор на transport layer должен быть явно согласован с бизнес-семантикой.
sidecar — базовый паттерн контейнера-помощника.adapter — inbound-переводчик протоколов и форматов.service-mesh — когда outbound-only уже недостаточно.back-pressure — как не превратить retries в перегрузку downstream.circuit-breaker — отдельная модель fail fast и half-open recovery.capacity-planning — sizing для proxy, pool и upstream-лимитов.