Ambassador pattern in Microservices - System Design Guide

Problem Statement

When microservices need to communicate with external systems or other services, direct calls can cause duplicated code, inconsistent configurations, and difficulty managing cross-cutting concerns like retries, logging, or security. This leads to fragile services that are hard to maintain and scale.

Solution

The Ambassador pattern introduces a helper service (the ambassador) that sits alongside the main service. It handles all communication with external systems, managing retries, logging, and security consistently. The main service interacts only with the ambassador, simplifying its code and centralizing communication logic.

Architecture

┌─────────────┐       ┌─────────────┐       ┌───────────────┐
│  Service A  │──────▶│ Ambassador  │──────▶│ External API  │
└─────────────┘       └─────────────┘       └───────────────┘

Description:
Service A sends requests to the Ambassador, which manages all external communication with the External API, handling retries, logging, and security.

Trade-offs

✓ Pros

→

Centralizes communication logic, reducing duplication across services.

→

Improves maintainability by isolating cross-cutting concerns like retries and logging.

→

Enables independent scaling and updating of communication logic without changing the main service.

✗ Cons

→

Adds an extra network hop, potentially increasing latency.

→

Increases system complexity by introducing additional components to manage.

→

Requires deployment and monitoring of ambassador services alongside main services.

Use when multiple services need consistent communication handling with external systems, especially at scale above hundreds of requests per second or when cross-cutting concerns are complex.

Avoid when the system is small with simple communication needs under a few dozen requests per second, as the added complexity and latency outweigh benefits.

Real World Examples

Netflix

Uses the Ambassador pattern to manage communication between microservices and external APIs, centralizing retries and security policies.

Uber

Implements ambassadors to handle service-to-service communication, ensuring consistent logging and fault tolerance.

Google

Uses ambassador proxies in Kubernetes environments to manage external traffic and service mesh integration.

Code Example

Before applying the Ambassador pattern, each service implements its own retry logic, causing code duplication and inconsistent behavior. After applying the pattern, the main service calls the Ambassador service, which centralizes retries and error handling, simplifying the main service code.

Microservices

### Before Ambassador pattern (direct call with duplicated retry logic)
import requests

def call_external_api():
    for _ in range(3):
        try:
            response = requests.get('https://external.api/data')
            if response.status_code == 200:
                return response.json()
        except requests.exceptions.RequestException:
            pass
    raise Exception('Failed after retries')


### After Ambassador pattern (service calls ambassador, ambassador handles retries)

# In Service A
import requests

def call_ambassador():
    response = requests.get('http://localhost:9000/api/data')
    response.raise_for_status()
    return response.json()

# In Ambassador service
import requests
from flask import Flask, jsonify

app = Flask(__name__)

@app.route('/api/data')
def proxy_data():
    for _ in range(3):
        try:
            response = requests.get('https://external.api/data')
            if response.status_code == 200:
                return jsonify(response.json())
        except requests.exceptions.RequestException:
            pass
    return jsonify({'error': 'Failed after retries'}), 500

if __name__ == '__main__':
    app.run(port=9000)

Alternatives

Sidecar pattern

Sidecar runs alongside the main service in the same host or container, managing auxiliary tasks beyond communication, while Ambassador focuses specifically on external communication.

Use when: Choose Sidecar when you need broader support like configuration, logging, and monitoring alongside communication.

API Gateway

API Gateway acts as a single entry point for clients to access multiple services, whereas Ambassador is a helper for individual services to communicate externally.

Use when: Choose API Gateway when you need centralized client request routing and aggregation.

Summary

The Ambassador pattern prevents duplicated communication logic by introducing a helper service that manages external calls.

It centralizes retries, logging, and security, simplifying the main service and improving maintainability.

This pattern is best for systems with complex communication needs and multiple services interacting with external APIs.

Practice

1. What is the main purpose of the Ambassador pattern in microservices architecture?

easy

A. To directly expose services to the internet without any proxy

B. To replace the main service with a new version

C. To store data in a centralized database

D. To add a helper component that manages communication between services

Solution

1. Step 1: Understand the role of the Ambassador pattern

   The Ambassador pattern introduces a helper component that acts as a proxy or sidecar to handle communication tasks for a service.

2. Step 2: Compare options with the pattern's purpose

   Replacing services, storing data centrally, or exposing services directly do not describe the Ambassador pattern's role.

3. Final Answer:

   To add a helper component that manages communication between services -> Option D

4. Quick Check:

   Ambassador pattern = helper component for communication [OK]

Hint: Ambassador adds a helper proxy for communication [OK]

Common Mistakes:

• Confusing Ambassador with database or service replacement
• Thinking it exposes services directly without proxy
• Assuming it stores data centrally

2. Which of the following is the correct way to describe the Ambassador pattern's deployment style?

easy

A. A sidecar proxy deployed alongside the main service

B. A centralized database for service communication

C. A standalone service that replaces the main service

D. A load balancer that distributes traffic among services

Solution

1. Step 1: Identify deployment style of Ambassador pattern

   The Ambassador pattern is typically deployed as a sidecar proxy next to the main service to handle communication.

2. Step 2: Eliminate incorrect deployment types

   It is not a standalone replacement, centralized database, or load balancer.

3. Final Answer:

   A sidecar proxy deployed alongside the main service -> Option A

4. Quick Check:

   Ambassador deployment = sidecar proxy [OK]

Hint: Ambassador runs as a sidecar proxy next to service [OK]

Common Mistakes:

• Thinking Ambassador replaces the main service
• Confusing it with load balancer or database
• Assuming it is a standalone service

3. Consider this simplified pseudo-code for an Ambassador proxy handling requests:

class AmbassadorProxy {
  sendRequest(request) {
    if (this.isServiceAvailable()) {
      return this.forward(request);
    } else {
      return this.retry(request);
    }
  }
}

What will happen if the main service is temporarily down?

medium

A. The proxy forwards the request without checking availability

B. The proxy retries sending the request until the service is available

C. The proxy immediately returns an error without retrying

D. The proxy stores the request permanently without forwarding

Solution

1. Step 1: Analyze the sendRequest method logic

   The method checks if the service is available. If yes, it forwards the request; otherwise, it retries.

2. Step 2: Determine behavior when service is down

   If the service is down, isServiceAvailable() returns false, so retry(request) is called to resend the request.

3. Final Answer:

   The proxy retries sending the request until the service is available -> Option B

4. Quick Check:

   Service down triggers retry in Ambassador proxy [OK]

Hint: Ambassador retries requests if service unavailable [OK]

Common Mistakes:

• Assuming proxy forwards without checking
• Thinking proxy returns error immediately
• Believing proxy stores requests permanently

4. A developer wrote this Ambassador proxy code snippet:

class Ambassador {
  send(request) {
    if (this.checkService()) {
      this.forward(request);
    } else {
      this.retry(request);
    }
  }
}

But requests are never retried even when the service is down. What is the likely bug?

medium

A. The send method does not return the result of retry or forward

B. The method forward does not return the response

C. The checkService method always returns true

D. The retry method is not implemented

Solution

1. Step 1: Review send method behavior

   The send method calls forward or retry but does not return their results, so caller never sees retries.

2. Step 2: Understand impact on retry behavior

   Without returning retry's result, retries may happen but caller ignores them, appearing as if no retry occurs.

3. Final Answer:

   The send method does not return the result of retry or forward -> Option A

4. Quick Check:

   Missing return in send causes retry to be ignored [OK]

Hint: Always return retry/forward results in proxy methods [OK]

Common Mistakes:

• Assuming checkService always true without checking
• Thinking retry method is missing
• Ignoring return values in send method

5. You want to improve observability and security for a microservice without changing its code. How does the Ambassador pattern help achieve this?

hard

A. By replacing the microservice with a new secure version

B. By modifying the service code to include security and logging libraries

C. By adding a sidecar proxy that handles logging, retries, and TLS encryption transparently

D. By deploying a centralized monitoring service that polls the microservice directly

Solution

1. Step 1: Identify how Ambassador pattern enhances observability and security

   The Ambassador pattern uses a sidecar proxy to add features like logging, retries, and TLS without changing the main service code.

2. Step 2: Compare with other options

   Modifying service code, polling directly, or replacing service do not align with Ambassador pattern benefits.

3. Final Answer:

   By adding a sidecar proxy that handles logging, retries, and TLS encryption transparently -> Option C

4. Quick Check:

   Ambassador adds security and observability via sidecar proxy [OK]

Hint: Ambassador adds features without changing service code [OK]

Common Mistakes:

• Thinking service code must be changed
• Confusing Ambassador with centralized monitoring
• Assuming service replacement is needed