This service watches Docker for containers starting and stopping to publish any advertised services out to Etcd. At this time, consumption of the published services can be done by querying Etcd directly. There are however plans to develop client libraries making this trivial.

The discovery of services is done by inspecting a custom ENV variable defined in the Dockerfile of the container. The ENV variable describes the service names and local ports they can be found on. Discover translates these to the public IP / Port assigned by Docker.

Discover uses Etcd, a REST based highly-available key/value store, as it's service registry. The best way to understand what Discover does is by walking through the lifecycle of a Docker container start/stop event. Note: This example assumes you already have Etcd and Discover running and properly configured.

Upon starting the container using docker run -d -p 8080 static-web-server, Docker will emit a start event for this container. Discover will listen for this event. Upon receiving the event, Discover will inspect the started container looking for a ENV variable matching the value of the discover:serviceVariable configuration variable. By default, this value will be DISCOVER.

In the case of our example, this ENV variable is set to static-web-server:8080. Discover will read this value and determine that the container that just started is exposing a service named static-web-server and it can be found on the private container port of 8080. Note: by default tcp is assumed, however you can explcitly specify if the port is expecting tcp or udp.

Now that Discover knows the service name and port, it will register the service with Etcd at the following location:

/<prefix>/service/static-web-server/<realm>/<host>/<container-id>

Where:

<prefix>: Defined in the configuration of Discover. By default this is /discover.

<realm>: Defined in the configuration of Discover. Used to segment services into logical groups.

<host>: Identifier of the host this service was deployed on. This is determined using a strategy of a custom configuration value, then the AWS instance-id if availalbe, and lastly falling back to the hostname of the machine.

<container-id>: This is the short 12 byte Docker container ID hosting the service.

The value stored at the above path will look like:

<protocol>://<public-ip-address>:<public-port>

Where:

<protocol>: The protocol expected at the IP/Port. Valid values are tcp or udp.

<public-ip-address>: The publicly routable IP address for the host machine.

<public-port>: The port assigned by Docker that maps to the internal port defined by the service.

Since multiple services can be publicized under the same name, you can lookup all available services by broadaining the path you query. For example, a GET /discover/service/static-web-server/my-realm?recursive=true will return a list of all services with the name static-web-server that have been published in the realm my-realm.

Publishing services from a Docker container using Discover is simple. Simply define each service in the appropriate ENV variable, seperated by commas.

For example, to publish two services from a single container where service1 is listening on 8080/tcp and service2 is listening on 8125/udp you would specify the following ENV variable in your Dockerfile:

Discover has dependencies on Docker and Etcd. It's designed to run one instance of Discover per instance of Docker, and idealy on the same machine that Docker is running on. Etcd does not need to be running on the same machine as Discover.

The setup of Docker and Etcd are outside of the scope of this document.

Once Docker and Etcd are setup, installing and running Discover is as simple as: