Ambassador Container Pattern
Published on

Ambassador Container Pattern

Written by Peter Jausovec
The ambassador container pattern aims to hide the primary container's complexity and provide a unified interface through which the primary container can access services outside of the Pod.
Ambassador Pattern
Ambassador Pattern
These outside or external services might present different interfaces and have other APIs. Instead of writing the code inside the main container that can deal with these external services' multiple interfaces and APIs, you implement it in the ambassador container. The ambassador container knows how to talk to and interpret responses from different endpoints and pass them to the main container. The main container only needs to know how to talk to the ambassador container. You can then re-use the ambassador container with any other container that needs to talk to these services while maintaining the same internal interface.
Another example would be where your main containers need to make calls to a protected API. You could design your ambassador container to handle the authentication with the protected API. Your main container will make calls to the ambassador container. The ambassador will attach any needed authentication information to the request and make an authenticated request to the external service.
Calls through ambassador to TMDB
Calls through ambassador to TMDB
To demonstrate how the ambassador pattern works, we will use The Movie DB (TMBD). Head over to the website and register (it's free) to get an API key.
The Movie DB website offers a REST API where you can get information about the movies. We have implemented an ambassador container that listens on path /movies, and whenever it receives a request, it will make an authenticated request to the API of The Movie DB.
Here's the snippet from the code of the ambassador container:
func TheMovieDBServer(w http.ResponseWriter, r *http.Request) {
	apiKey := os.Getenv("API_KEY")
	resp, err := http.Get(fmt.Sprintf("", apiKey))
    // ...
    // Return the response
We will read the API_KEY environment variable and then make a GET request to the URL. Note if you try to request to URL without the API key, you'll get the following error:
$ curl
{"status_code":7,"status_message":"Invalid API key: You must be granted a valid key.","success":false}
I have pushed the ambassador's Docker image to startkubernetes/ambassador:0.1.0.
Just like with the sidecar container, the ambassador container is just another container that's running in the Pod. We will test the ambassador container by calling curl from the main container.
Here's how the YAML file looks like:
apiVersion: v1
kind: Pod
  name: themoviedb
    - name: main
      image: radial/busyboxplus:curl
        - sleep
        - '600'
    - name: ambassador
      image: startkubernetes/ambassador:0.1.0
        - name: API_KEY
              name: themoviedb
              key: apikey
        - name: http
          containerPort: 8080
Before we can create the Pod, we need to create a Secret with the API key. Let's do that first:
$ kubectl create secret generic themoviedb --from-literal=apikey=<INSERT YOUR API KEY HERE>
secret/themoviedb created
You can now store the Pod YAML in ambassador-container.yaml file and create it with kubectl apply -f ambassador-container.yaml.
When Kubernetes creates the Pod (you can use kubectl get po to see the status), you can use the exec command to run the curl command inside the main container:
$ kubectl exec -it themoviedb -c main -- curl localhost:8080/movies

Since containers within the same Pod share the network, we can make a request against localhost:8080, which corresponds to the port on the ambassador container.
You could imagine running an application or a web server in the main container, and instead of making requests to the directly, you are making requests to the ambassador container.
Similarly, if you had any other service that needed access to the you could add the ambassador container to the Pod and solve access like that.
Join the discussion
Peter Jausovec

Peter Jausovec

Peter Jausovec is a platform advocate at He has more than 15 years of experience in the field of software development and tech, in various roles such as QA (test), software engineering and leading tech teams. He's been working in the cloud-native space, focusing on Kubernetes and service meshes, and delivering talks and workshops around the world. He authored and co-authored a couple of books, latest being Cloud Native: Using Containers, Functions, and Data to Build Next-Generation Applications.

Related posts