Public | Automated Build

Last pushed: 3 years ago
Short Description
Dynamic ambassador pattern based on etcd, confd, docker-gen and haproxy.
Full Description

Dynamic Ambassador

Dynamic ambassador pattern based on etcd,
confd, docker-gen and haproxy. This ambassador can be run on a single host but it' designed to be run on
a Docker cluster (like CoreOS or Docker Swarm)


  • Automated the registration of services and apps running on a Docker host
  • Automated the redirection of requests to the service or the app on the true Docker host

This ambassador distinct two kind of container. App and Service container:

An app is an HTTP app accessed with a specific domain name.
It could be a REST API, a web server, etc. Any app relying on HTTP.

A service is a TCP service listening on a specific port.
It could be a database, a queuing service, etc. Any TCP app listening on a dedicated PORT with a custom protocol.

This distinction is important, because the mechanism used to proxy requests depends on it.
In a case it is a HTTP proxy, in the other it is a TCP load balancer.


Before using this ambassador you need to have a running etcd service. If you don't use a CoreOS cluster you can create an etcd container like this:

docker run --rm -it -p 4001:4001 -p 7001:7001 microbox/etcd -name=test -addr=

See here how to set up a multi-machine cluster.

Start the ambassador container making sure:

  • to expose port 80 on the host machine
  • to configure the etcd host
  • to configure the host IP
docker run --rm --name dynamic-ambassador -h dynamic-ambassador-1 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -p 80:80 \

On a single host you can also use make start to start the container.
With CoreOS you can use the provided unit file:

fleetctl start ambassador@{1..3}.service

Once yours ambassador running you can start yours apps and services.

dynamic ambassador used environment variables into the container to configure apps and services:
An app is registered if the container has a DOMAIN_NAME environment variable.
A service is registered if the container has a SERVICE_PORT environment variable.

Note: The container must also publish a port to be registered by the ambassador


Run a MySQL database service:

docker run -d --name some-mysql \
  -e MYSQL_ROOT_PASSWORD=mysecretpassword \
  -e SERVICE_PORT=3306 \
  -P \

Run a Wordpress app (not necessary on the same host):

docker run -d --name some-wordpress \
  --link dynamic-ambassador:mysql \
  -e \
  -e WORDPRESS_DB_PASSWORD=mysecretpassword \
  -e WORDPRESS_DB_HOST='mysql' \

Acces the Wordpress app (from any host):

curl -H "Host:"

Under the hood

The registration process is done by setting keys into etcd.
An app is registered like this:

  • domain_name is the domain name gotten from the environment variable
  • id is the container id
  • ip is the host IP
  • pub-port is the published port

A service is registered like this:

  • name is the container name
  • port the service port
  • id is the container id
  • ip is the host IP
  • pub-port is the published port

Then the ambassador used confd for watching those keys and finally built the HAProxy configuration.
The apps keys are used to create a http reverse proxy configuration.
And the services keys are used to create a tcp load balancer.

Docker Pull Command
Source Repository