This repository defines a load balancer container for Docker, based on haproxy, confd and etcd.

The container runs a haproxy load balancer process. The configuration is generated by confd from live data pulled from etcd. Changes made in etcd are automatically reflected in the configuration, making it very convenient for services to add and remove themselves from the system just by interacting with the etcd service.

To deploy a load balancer container, use the following command:

docker run -p 80:80 -e ETCD_PEERS=http://172.17.0.2:2379 miguelgrinberg/easy-lb-haproxy

The container accepts the following environment variables:

• ETCD_PEERS: a comma-separated list of etcd client URLs. (Required, the etcd service must be deployed separately)
• HAPROXY_STATS: set to a non-null value to enable the haproxy stats feature. (Optional, disabled by default)
• HAPROXY_STATS_URI: if stats are enabled, this is the stats URL. (Optional, defaults to /stats)
• HAPROXY_STATS_AUTH: if stats are enabled, this sets login credentials to access the stats page. (Optional, auth is disabled by default)

To build the container image locally, you can use the included build.sh script.

The load balancer is automatically configured from the contents of etcd's /services directory. For example, consider the following etcdctl commands:

etcdctl set /services/foo/upstream/server1 172.17.0.4:5000
etcdctl set /services/foo/upstream/server2 172.17.0.5:5000
etcdctl set /services/bar/upstream/server3 172.17.0.6:5000

This will cause the load balancer to forward requests to URLs that start with /foo to server1 and server2 at the addresses and ports specified, and any requests that start with /bar to server3. Note that the names server{1,2,3} are not significant, each service can register itself with any name, as long as it is unique.

To use a URL prefix different than the service name, set a location key. For example, the following command will make the load balancer send requests with URLs that start with /api/foo to the foo service:

etcdctl set /services/foo/location /api/foo

To set a service as the default, simply set its location to the root URL:

etcdctl set /services/foo/location /

By default, each backend is configured for round robin load balancing. To use custom backend options, add the desired options under a backend key. For example, to set the source load balancing algorithm, write the following key:

etcdctl set /services/foo/backend/balance source

Whenever changes are made in etcd to the /services subtree, those changes will automatically trigger a configuration update.