Ambassador

Ambassador can be used as a "jumper" to connect remote services within a cluster that have dynmically changing hosts/ports. It assumes services are registering their host and port with an available DNS service using SRV records.

For example, you might have a mongodb container running somewhere in your cluster. It registers its own host and port to a DNS service under an SRV entry such as _mongodb._tcp.domain.local when it starts/restarts.

As a sidekick container

Say you have an api-server that wants to talk to _mongodb._tcp.domain.local. You can link this API server to mongodb using a sidekick:

docker run -d -name dns-server jkingyens/helixdns
docker run -d -link dns-server:dns -name db-amb jkingyens/ambassador _mongodb._tcp.domain.local
docker run -d -link db-amb:db api-server

HelixDNS provides a DNS service on top of etcd. If you already have DNS service at a particular ip:port, then:

docker run -d -dns <ip:port> -name db-amb jkingyens/ambassador _mongodb._tcp.domain.local
docker run -d -link db-amb:db api-server

In either case, api-server only needs to be concerned with connecting to the jumper defined by the enviornment variables:

DB_PORT_3000_TCP_ADDR
DB_PORT_3000_TCP_PORT

Ambassador takes care of ensuring this socket connection routes to wherever _mongodb._tcp.domain.local is running. api-server should be designed to handle network failures. This way, if your monogdb instance is scheduled onto a different host or port, the ambassador should properly route traffic to its new location when api-server attempts to reconnect.

As a node module

You can use the ambassador directly as a node.js module if you want to build this dynmically linking behaviour into your application. You define the name of the service (as advertised in your DNS) and a local port you want to talk to the service on:

var amb = require('amb-dns');
amb(3000, '_mongodb._tcp.required.local', function (err) {
  // mongo is now available at localhost:3000
});