Public | Automated Build

Last pushed: a year ago
Short Description
Simple load balancer container based on nginx, confd and etcd.
Full Description


Simple load balancer container for Docker, based on nginx, confd and etcd.

High-level design

The container runs an nginx 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=, miguelgrinberg/easy-lb-nginx

The ETCD_PEERS variable is a comma-separated list of URLs for the etcd service, which must be deployed separately. This variable is required.


To build the container image locally, you can use the included 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
etcdctl set /services/foo/upstream/server2
etcdctl set /services/bar/upstream/server3

This will cause the load balancer to proxy requests to /foo/... URLs to server1 and server2, at the addresses and ports specified, while any requests to /bar/... URLs will be sent 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 mount a service on a different URL, set a location key. For example, the following command will make service foo available on the root URL:

etcdctl set /services/foo/location /

To use a custom path in the proxied URLs, set a path key. For example, the following command will make nginx send requests to the foo service to /api/foo/... URLs:

etcdctl set /services/foo/path /api/foo/

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


  • SSL support
  • Automatic Let's Encrypt certificates
  • Select load balancing method for each service
  • WebSocket proxying
  • Configure other options in location or upstream blocks
Docker Pull Command
Source Repository