Ambassador Pattern: Using an External Proxy Service for Client Network Calls

Background and Problem

Cloud‑native applications need features like circuit breaking, routing, metrics, and monitoring, as well as the ability to update network‑related configurations. Updating legacy code to add these capabilities is often difficult or impossible because the original development team no longer maintains the code.

Network calls also require extensive configuration for connection, authentication, and authorization. When the same calls are used across multiple applications written in different languages and frameworks, each instance must be configured separately, and central teams may need to manage security policies for many heterogeneous services.

Solution

Place the client framework and libraries in an external process that acts as a proxy between your application and external services. Deploy the proxy in the same host environment as the application so it can control routing, resilience, and security while avoiding host‑level access restrictions. The ambassador can also standardize detection, monitor performance metrics such as latency or resource usage, and perform these checks in the same host as the application.

Functions offloaded to the ambassador can be managed independently of the application, allowing updates or modifications without affecting existing functionality. Dedicated teams can implement and maintain security, networking, or authentication features that have been transferred to the ambassador.

The ambassador service can be deployed as a sidecar that follows the lifecycle of the consuming application or service, as a daemon/Windows service when shared across multiple processes on a host, or as a separate container when the consumer is containerized, with appropriate linking for communication.

Issues and Considerations

The proxy adds some latency overhead; evaluate whether a direct client library call might be more appropriate.

Assess the impact of including generic features in the proxy (e.g., retries may be unsafe unless all operations are idempotent).

Provide a mechanism for the client to pass context to the proxy and receive it back (e.g., HTTP headers to opt‑out of retries or set max retry count).

Plan how to package and deploy the proxy.

Decide whether to use a single shared instance for all clients or one instance per client.

When to Use This Pattern

Use the ambassador pattern when you need to:

Build a common set of client‑connection capabilities for multiple languages or frameworks.

Shift cross‑domain client‑connection concerns to infrastructure or specialized teams.

Support cloud or cluster connection requirements in legacy or hard‑to‑modify applications.

This pattern may not be suitable when network latency is critical, when the client‑connection functionality is used by a single language (in which case a language‑specific library is preferable), or when the connection logic cannot be generalized and requires deep integration with the client application.

Example

The diagram below shows an application sending a request to a remote service through an ambassador proxy, which provides routing, circuit breaking, and logging. The proxy forwards the request to the remote service and returns the response to the client application.

Related Guidance

Sidecar pattern