Consul (or etcd) and Docker are fast becoming core primitives for orchestrating production systems. Docker for packaging and containerization of workloads; Consul makes it simple for services to register themselves and to discover other services via DNS or an HTTP API.

For example, etcd is involved in much of the Diego rewrite of Cloud Foundry [video]. Docker is also being added into Cloud Foundry to perhaps make CF the best orchestration tool for ephemeral Docker-based application.

See other blog posts on: docker | consul

A nice piece of glue is missing - automatically registering Docker containers (specifically their host IP and accessible ports) with Consul when they are running; and automatically deregistering them if they stop.

This piece of glue is called registrator, created by Jeff Lindsay (@progrium).

A quick demo of registrator in action:

The demo is running on my OS X machine using boot2docker. Docker does one thing very well - demo on your local machine!

In the examples below, is the default IP for boot2docker on the host machine and inside the boot2docker VM itself.

To run a single node Consul cluster (you would run 3+ Consul servers in production across several machines):

docker run -d -p 8400:8400 -p 8500:8500 -p 8600:53/udp -h node1 progrium/consul -server -bootstrap  

To run the registrator we need to configure it to look for a consul:// HTTP backend (which is port 8500 above). We also need to give it access to the Docker socket, which is the default /var/run/docker.sock within boot2docker.

docker run -d -h -v /var/run/docker.sock:/tmp/docker.sock progrium/registrator consul://  

Now we can run some normal Docker containers and watch them be automatically registered as services across our entire Consul universe (albeit a single boot2docker node in this example; but dream big!)

docker run -d --name redis.0 -p 10000:6379 \  
    -e "SERVICE_NAME=db" \
    -e "SERVICE_TAGS=master,backups" dockerfile/redis

Registrator will pick up the $SERVICE_NAME environment variable and register the container against that name (the very generic db name above).

Any client only needs to be given db as the name of the service and they can lookup all the available containers/ports that provide the service:

docker run frodenas/ubuntu curl -s  

The output is JSON and includes the single advertised host:port:


The demo video above, as well as Registrator's README, give more examples for expanding the service registry with more nodes, filtering them by tags, etc.

Registrator also supports etcd as the global key-value backend, and a simple register/deregister interface for extension.