Reddie: Service Discovery for Docker

Reddie can automatically discover any Redis containers running on a Docker daemon. It looks for any running containers with a given label.

Set up

Two parts are required for Docker Service Discovery. Reddie needs to know which Docker daemon(s) to connect to and which label to look for to identify a Redis container.

Choosing the label

In order for Reddie to discover Redis containers, they need to be labeled. The label can be anything, but for most of the examples below we’ll use a simple label of redis.

Adding the label on docker run

Once you’ve selected a label, it needs to be attached to any Redis containers you wish to discover and passed to Reddie using DOCKER_DISCOVERY_LABEL.

Example - You would like Reddie to be able to discover a Redis container.

$ docker run --label redis redis

Discovery via Docker daemon unix socket

In a default docker installation, the docker daemon exposes a unix socket at /var/run/docker.sock for communication and control. When using the docker command line client it is usually this unix socket that it interacts with.

Reddie can query this socket and discover Redis instances, however this limits Reddie to a single Docker daemon for discovering Redis containers.

Example - You would like Reddie to discover containers labeled “redis” running on the local machine’s Docker daemon.

$ docker run -d -p 443:443 \
    -e DISCOVERY_DOCKER_LABEL=redis \
    -e DISCOVERY_DOCKER_UNIX_SOCKET=/var/run/docker.sock \ 
    -v /var/run/docker.sock:/var/run/docker.sock \
        get-reddie.com/reddie

Discovery via http & https

Using an http or https socket, Reddie can discover Redis containers on any number of hosts. Please refer to the official Docker daemon documentation for instructions to configure your Docker daemon to expose a port.

Please also familiarize yourself with the security implications of exposing the Docker daemon port.

Address selection

When discovering Redis containers on remote Docker daemons, the host and port to connect to are determined by:

The host address specified in DISCOVERY_DOCKER_HOSTS and:

the port specified in the discovery label or,
the corresponding publicly exposed port found for private port 6379 or,

the private IP address of the container and:

the private port 6379

Private IP addresses will only be connectable when Reddie is running on the same Docker daemon or an overlay network is present.

Example - Launching Reddie with DISCOVERY_DOCKER_LABEL=redis and DISCOVERY_DOCKER_HOSTS=127.0.0.1 and running Redis containers.

$ docker run -d -p 443:443 \
    -e DISCOVERY_DOCKER_LABEL=redis \
    -e DISCOVERY_DOCKER_HOSTS=127.0.0.1 \        
        get-reddie.com/reddie

$ docker run -d --label redis -P redis 
$ docker run -d --label redis -p 6379 redis 
$ docker run -d --label redis -p 6380:6379 redis
$ docker run -d --label redis -p 6381:6379 redis
$ docker run -d --net host --label redis="6379" redis
$ docker run -d --label redis redis

Each of the Redis containers would be discovered and connected as:

127.0.0.1:32768, where 32768 is a Docker randomly assigned port.
127.0.0.1:32769, where 32769 is a Docker randomly assigned port.
127.0.0.1:6380.
127.0.0.1:6381.
127.0.0.1:6379.
172.17.0.2:6379, where 172.17.0.2 is the Docker assigned private IP address.

Via http

This is probably only appropriate in a development, test or otherwise locked down environment. Please be aware of the security implications of exposing a Docker daemon on an unencrypted http socket.

Example - You want Reddie to discover containers labeled “redis” running on a set of test servers’ Docker daemons.

$ docker run -d -p 443:443 \
    -e DISCOVERY_DOCKER_LABEL=redis \
    -e DISCOVERY_DOCKER_HOSTS=192.168.1.100,192.168.1.101,192.168.1.102 \        
        get-reddie.com/reddie

Via https

Reddie can also connect to a TLS-secured Docker daemon. You must provide Reddie with a public certificate and password-less private key encoded in PEM format. The certificate must be signed by the same certificate authority as the certificate used by the Docker daemon. By default, Reddie validates that the Docker daemon’s hostname matches the server certificate. If the certificates used are self-signed, the certificate authority certificate must also be included.

Example - You want Reddie to discover containers labeled “redis” running on a set of TLS-secured servers using a client certificate stored in your home directory.

$ docker run -d -p 443:443 \
    -e DISCOVERY_DOCKER_LABEL=redis \
    -e DISCOVERY_DOCKER_HOSTS=redis.example.com \
    -e DISCOVERY_DOCKER_PORT=2376 \
    -e DISCOVERY_DOCKER_PROTOCOL=https:// \
    -v ~/ca.pem:/ca.pem     -e DISCOVERY_DOCKER_CERTIFICATE_AUTHORITY=/ca.crt  \
    -v ~/cert.pem:/cert.pem -e DISCOVERY_DOCKER_CLIENT_CERTIFICATE=/cert.pem \
    -v ~/key.pem:/key.pem   -e DISCOVERY_DOCKER_CLIENT_KEY=/key.pem  \
        get-reddie.com/reddie

Disabling server name validation

Server name validation can be disabled with DISCOVERY_DOCKER_VALIDATE_SERVER_IDENTITY.

This makes Reddie vulnerable to a MITM scenario.

Certificate pinning

A specific server certificate can be set as trusted by Reddie using DISCOVERY_DOCKER_PIN_SERVER_CERTIFICATE. It expects a fingerprint specified in colon-delimited hex.

For example, 3F:C0:3D:AA:5B:B8:48:94:52:61:59:0E:D8:8B:E4:E4:56:AA:98:27

Example - You want Reddie to discover containers labeled “redis” running on a set of TLS-secured servers using a client certificate, with a specific server certificate pinned.

$ docker run -d -p 443:443 \
    -e DISCOVERY_DOCKER_LABEL=redis \
    -e DISCOVERY_DOCKER_HOSTS=redis.example.com \
    -e DISCOVERY_DOCKER_PORT=2376 \
    -e DISCOVERY_DOCKER_PROTOCOL=https:// \
    -e DISCOVERY_DOCKER_PIN_SERVER_CERTIFICATE=3F:C0:3D:AA:5B:B8:48:94:52:61:59:0E:D8:8B:E4:E4:56:AA:98:27
    -v ~/ca.pem:/ca.pem     -e DISCOVERY_DOCKER_CERTIFICATE_AUTHORITY=/ca.crt  \
    -v ~/cert.pem:/cert.pem -e DISCOVERY_DOCKER_CLIENT_CERTIFICATE=/cert.pem \
    -v ~/key.pem:/key.pem   -e DISCOVERY_DOCKER_CLIENT_KEY=/key.pem  \
        get-reddie.com/reddie

Environment variables

All environment variables related to Docker Service Discovery.

DISCOVERY_DOCKER_LABEL

Docker containers with this label will be discovered. If the label has a numeric value, it is considered the discovered port.

DISCOVERY_DOCKER_INTERVAL

The interval in seconds between discovery checks against the specified Docker daemon(s).

DISCOVERY_DOCKER_UNIX_SOCKET

The path to the Docker daemon unix socket to connect to.

DISCOVERY_DOCKER_HOSTS

A list of remote Docker daemon(s) to discover Redis containers from.

DISCOVERY_DOCKER_PORT

The port to use when connecting to the Docker daemon(s). Default is 2375.

DISCOVERY_DOCKER_PROTOCOL

The protocol to use when connecting to the Docker daemon(s). http:// or https://.

DISCOVERY_DOCKER_CLIENT_CERTIFICATE

The path to a client certificate to use when connecting to the Docker daemon(s).

DISCOVERY_DOCKER_CLIENT_KEY

The path to a client key to use when connecting to the Docker daemon(s).

DISCOVERY_DOCKER_CERTIFICATE_AUTHORITY

The path to the public certificate of the certificate authority that was used to sign the client and server certificates.

DISCOVERY_DOCKER_VALIDATE_SERVER_IDENTITY

Any server certificate validation errors will be ignored. true or false.

DISCOVERY_DOCKER_PIN_SERVER_CERTIFICATE

Server certificate validation will only pass if the certificate thumbprint matches this thumbprint. In colon-separated hex format.

Documentation

Service Discovery for Docker