Docker Service Discovery & Loadbalancing Strategies

A common question that arises is how does service discovery in docker work. And how does docker route the traffic.

This project showcases some strategies for service discovery with docker and docker-compose. You can find the working examples and this post also in the github repo.

Before we dive into more advanced strategies, lets review some of the basics.

Dockers built-in Nameserver & Loadbalancer

Docker comes with a built-in nameserver. The server is, by default, reachable via

Every container has by default a nameserver entry in /etc/resolve.conf, so it is not required to specify the address of the nameserver from within the container. That is why you can find your service from within the network with service or task_service_n.

If you do task_service_n then you will get the address of the corresponding service replica.

If you only ask for the service docker will perform internal load balancing between container in the same network and external load balancing to handle requests from outside.

When swarm is used, docker will additionally use two special networks.

  1. The ingress network, which is actually an overlay network and handles incoming traffic to the swarm. It allows to query any service from any node in the swarm.
  2. The docker_gwbridge, a bridge network, which connects the overlay networks of the individual hosts to an their physical network. (including ingress)

When using swarm to deploy services, the behavior as described in the examples below will not work unless endpointmode is set to dns roundrobin instead of vip.

endpoint_mode: vip - Docker assigns the service a virtual IP (VIP) that acts as the front end for clients to reach the service on a network. Docker routes requests between the client and available worker nodes for the service, without client knowledge of how many nodes are participating in the service or their IP addresses or ports. (This is the default.) endpoint_mode: dnsrr - DNS round-robin (DNSRR) service discovery does not use a single virtual IP. Docker sets up DNS entries for the service such that a DNS query for the service name returns a list of IP addresses, and the client connects directly to one of these. DNS round-robin is useful in cases where you want to use your own load balancer, or for Hybrid Windows and Linux applications.


For example deploy three replicas from dig/docker-compose.yml

version: '3.8'
image: "traefik/whoami"
replicas: 3

DNS Lookup

You can use tools such as dig or nslookup to do a DNS lookup against the nameserver in the same network.

docker run --rm --network dig_default tutum/dnsutils dig whoami
; <<>> DiG 9.9.5-3ubuntu0.2-Ubuntu <<>> whoami
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 58433
;; flags: qr rd ra; QUERY: 1, ANSWER: 3, AUTHORITY: 0, ADDITIONAL: 0

;whoami. IN A

whoami. 600 IN A
whoami. 600 IN A
whoami. 600 IN A

;; Query time: 0 msec
;; WHEN: Mon Nov 16 22:36:37 UTC 2020
;; MSG SIZE rcvd: 90

If you are only interested in the IP, you can provide the +short option

docker run --rm --network dig_default tutum/dnsutils dig +short whoami

Or look for specific service

docker run --rm --network dig_default tutum/dnsutils dig +short dig_whoami_2

Load balancing

The default loadbalancing happens on the transport layer or layer 4 of the OSI Model. So it is TCP/UDP based. So it is not possible to inspect and manipulate http headers with this method. In the enterprise edition it is apparently possible to use labels similar to the ones traefik is using in the example a bit further down.

docker run --rm --network dig_default curlimages/curl -Ls http://whoami
Hostname: eedc94d45bf4
GET / HTTP/1.1
Host: whoami
User-Agent: curl/7.73.0-DEV
Accept: */*

Here is the hostname from 10 times curl:

Hostname: eedc94d45bf4
Hostname: 42312c03a825
Hostname: 42312c03a825
Hostname: 42312c03a825
Hostname: eedc94d45bf4
Hostname: d922d86eccc6
Hostname: d922d86eccc6
Hostname: eedc94d45bf4
Hostname: 42312c03a825
Hostname: d922d86eccc6

Health Checks

Health checks, by default, are done by checking the process id (PID) of the container on the host kernel. If the process is running successfully, the container is considered healthy.

Oftentimes other health checks are required. The container may be running but the application inside has crashed. In many cases a TCP or HTTP check is preferred.

It is possible to bake a custom health checks into images. For example, using curl to perform L7 health checks.

FROM traefik/whoami
HEALTHCHECK CMD curl --fail http://localhost || exit 1

It is also possible to specify the health check via cli when starting the container.

docker run \
--health-cmd "curl --fail http://localhost || exit 1" \
--health-interval=5s \
--timeout=3s \

Example with Swarm

As initially mentioned, swarms behavior is different in that it will assign a virtual IP to services by default. Its actually not different its just docker or docker-compose doesn’t create real services, it just imitates the behavior of swarm but still runs the container normal setup as services can in fact only be created by manager nodes.

Keeping in mind we are on a swarm manager and thus the default mode is VIP

Create a overlay network that can be used by regular containers too

docker network create --driver overlay --attachable testnet

create some service with 2 replicas

docker service create --network testnet --replicas 2 --name digme nginx

Now lets use dig again and making sure we attach the container to the same network

$ docker run --network testnet --rm tutum/dnsutils dig  digme
digme. 600 IN A

We see that indeed we only got one IP address back, so it appears that this is the virtual IP that has been assigned by docker.

Swarm allows actually to get the single IPs in this case without explicitly setting the endpoint mode.

We can query for task.<servicename> in this case that is tasks.digme

$ docker run --network testnet --rm tutum/dnsutils dig tasks.digme
tasks.digme. 600 IN A
tasks.digme. 600 IN A

This has brought us 2 A records pointing to the individual replicas.

Now lets create another service with endpointmode set to dns roundrobin

docker service create --endpoint-mode dnsrr --network testnet --replicas 2 --name digme2 nginx
$ docker run --network testnet --rm tutum/dnsutils dig digme2
digme2. 600 IN A
digme2. 600 IN A

This way we get both IPs without adding the prefix tasks.

Service Discovery & Loadbalancing Strategies

If the built in features are not sufficient, some strategies can be implemented to achieve better control. Below are some examples.


Haproxy can use the docker nameserver in combination with dynamic server templates to discover the running container. Then the traditional proxy features can be leveraged to achieve powerful layer 7 load balancing with http header manipulation and chaos engineering such as retries.

version: '3.8'

image: haproxy
- ./haproxy.cfg:/usr/local/etc/haproxy/haproxy.cfg:ro
- 80:80
- 443:443

image: "traefik/whoami"
replicas: 3
resolvers docker
nameserver dns1
resolve_retries 3
timeout resolve 1s
timeout retry 1s
hold other 10s
hold refused 10s
hold nx 10s
hold timeout 10s
hold valid 10s
hold obsolete 10s
backend whoami
balance leastconn
option httpchk
option redispatch 1
retry-on all-retryable-errors
retries 2
http-request disable-l7-retry if METH_POST
cookie MY_SERVICES_HASHED_ADDRESS insert dynamic
server-template whoami- 6 whoami:80 check resolvers docker init-addr libc,none


The previous method is already pretty decent. However, you may have noticed that it requires knowing which services should be discovered and also the number of replicas to discover is hard coded. Traefik, a container native edge router, solves both problems. As long as we enable Traefik via label, the service will be discovered. This decentralized the configuration. It is as if each service registers itself.

The label can also be used to inspect and manipulate http headers.

version: "3.8"

image: "traefik:v2.3"
- "--log.level=DEBUG"
- "--api.insecure=true"
- "--providers.docker=true"
- "--providers.docker.exposedbydefault=false"
- "--entrypoints.web.address=:80"
- "80:80"
- "8080:8080"
- "/var/run/docker.sock:/var/run/docker.sock:ro"

image: "traefik/whoami"
- "traefik.enable=true"
- "traefik.port=80"
- "traefik.http.routers.whoami.entrypoints=web"
- "traefik.http.routers.whoami.rule=PathPrefix(`/`)"
- ""
- ""
replicas: 3


Consul is a tool for service discovery and configuration management. Services have to be registered via API request. It is a more complex solution that probably only makes sense in bigger clusters, but can be very powerful. Usually it recommended running this on bare metal and not in a container. You could install it alongside the docker host on each server in your cluster.

In this example it has been paired with the registrator image, which takes care of registering the docker services in consuls catalog.

The catalog can be leveraged in many ways. One of them is to use consul-template.

Note that consul comes with its own DNS resolver so in this instance the docker DNS resolver is somewhat neglected.

version: '3.8'

image: gliderlabs/consul-server:latest
command: "-advertise=${MYHOST} -server -bootstrap"
container_name: consul
hostname: ${MYHOST}
- 8500:8500

image: gliderlabs/registrator:latest
command: "-ip ${MYHOST} consul://${MYHOST}:8500"
container_name: registrator
hostname: ${MYHOST}
- consul
- /var/run/docker.sock:/tmp/docker.sock

build: .
- 80:80
- consul

image: "traefik/whoami"
replicas: 3
- "80"

Dockerfile for custom proxy image with consul template backed in.

FROM nginx

RUN curl \
> consul-template_0.25.1_linux_amd64.tgz

RUN gunzip -c consul-template_0.25.1_linux_amd64.tgz | tar xvf -

RUN mv consul-template /usr/sbin/consul-template
RUN rm /etc/nginx/conf.d/default.conf
ADD proxy.conf.ctmpl /etc/nginx/conf.d/
ADD consul-template.hcl /

CMD [ "/bin/bash", "-c", "/etc/init.d/nginx start && consul-template -config=consul-template.hcl" ]

Consul template takes a template file and renders it according to the content of consuls catalog.

upstream whoami {

server :;


server {
listen 80;
location / {
proxy_pass http://whoami;

After the template has been changed, the restart command is executed.

consul {
address = "consul:8500"

retry {
enabled = true
attempts = 12
backoff = "250ms"
template {
source = "/etc/nginx/conf.d/proxy.conf.ctmpl"
destination = "/etc/nginx/conf.d/proxy.conf"
perms = 0600
command = "/etc/init.d/nginx reload"
command_timeout = "60s"

Feature Table

Built InHAProxyTraefikConsul-Template
Service DiscoveryAutomaticServer TemplatesLabel SystemKV Store + Template
Health ChecksYesYesYesYes
Load BalancingL4L4, L7L4, L7L4, L7
Sticky SessionNoYesYesDepends on proxy
MetricsNoStats PageDashboardDashboard