Ambassador Pattern
A cloud design pattern that deploys a helper service (the ambassador) as a proxy alongside an application or service to offload common client-side connectivity tasks — such as logging outbound calls, handling retries, circuit breaking, and routing — without modifying the application’s own code.
Problem
Applications that call external services need to implement cross-cutting networking concerns: retry logic, circuit breaking, connection pooling, SSL termination, observability (tracing outbound calls). Implementing these in every application, in every language, results in duplication and inconsistency.
Solution / Explanation
Deploy an ambassador as a sidecar or proxy that intercepts all outbound calls from the application. The application sends requests to localhost:port; the ambassador handles the call to the real destination and applies the necessary policies.
┌──────────────────────────────────────┐
│ Host │
│ ┌────────────────┐ ┌────────────┐ │
│ │ Application │──► Ambassador │──► Remote Service
│ │ (business │ │ (retry, │ │
│ │ logic only) │ │ logging, │ │
│ └────────────────┘ │ routing) │ │
│ └────────────┘ │
└──────────────────────────────────────┘
Ambassador vs. Sidecar
The Ambassador Pattern is a specific application of the Sidecar Pattern. All ambassadors are sidecars, but not all sidecars are ambassadors. Sidecars handle any peripheral concern; ambassadors specifically handle outbound call management.
Common Ambassador Responsibilities
- Retry with backoff — transparently retry failed calls.
- Circuit breaking — stop calls when the destination is failing.
- Connection pooling — manage a pool of persistent connections.
- Request/response logging — log all outbound calls for observability.
- Protocol translation — translate from application protocol to destination protocol.
- TLS termination — encrypt outbound calls transparently.
Envoy as Ambassador
Envoy proxy is frequently used as an ambassador. It can be configured as a sidecar that handles all outbound HTTP/gRPC traffic with retry policies, circuit breakers, and distributed tracing headers — without any code changes in the application.
When to Use
- Applications written in languages without good libraries for the needed networking features.
- Legacy applications that cannot be modified.
- When a team wants uniform networking policies across polyglot services.
- As part of a service mesh migration strategy.
Not suitable when:
- The networking overhead of an extra process outweighs the benefit.
- The application already handles its own connectivity well.
Trade-offs
| Benefit | Drawback |
|---|---|
| Application code stays focused on business logic | Additional process/container to manage |
| Language-agnostic — works with any language | Adds inter-process communication latency |
| Centralized, consistent outbound call policies | Configuration complexity |
| Enables infrastructure concerns to evolve independently | Debugging requires reasoning about both app and ambassador |
Related
- Sidecar Pattern — the general pattern; Ambassador is a specific use case
- Service Mesh — a service mesh implements ambassador concerns at the infrastructure level
- Circuit Breaker Pattern — often implemented in the ambassador
- Observability — ambassadors emit telemetry for outbound calls