Public | Automated Build

Last pushed: 2 years ago
Short Description
HAProxy - Consul template image - truly turnkey dynamic load balancer for docker containers.
Full Description

haproxy-consul image

This image intention is to put together the best practices around the HAProxy - Consul set up in order to create a truly turnkey dynamic load balancer solution for docker containers.


  • HAProxy 1.6.3 (Based on Alpine janeczku/alpine-haproxy:1.6.3)
  • Consul-template 0.13.0 (Compiled with go 1.6!)
  • S6 Overlay (v1.17.1.2)


  • Auto-configured reverse proxy for your registered services. Just TAG them as http in Consul and you can access them by subdomain or url. For example the service name webapp automatically is available by:
    • (Add a wildcard DNS record or individual records per app)
    • (Ideal for APIs)
  • HAProxy soft restart fixed (no more zombie processes after consul reconfiguration- consul-template 0.13.0)
  • Supervised consul-template process (reloaded if fails without affecting HAProxy - s6 overlay)
  • haproxy.cfg validation before restarting HAProxy (using backup until a new valid config is generated)
  • Seamless server states (load-server-state-from-file)
  • Soft HAProxy shutdown (thanks to S6 overlay)
  • Session stickiness for stateful legacy apps/APIs. Just add the stateful service tag (ref. Using application session cookie for persistence)
  • Multiple dynamic configurations


  • More sample applications and load tests
  • Separate consul-template and HAProxy. Explore signaling containers or XML RPC.
  • Graceful hot service version switch/rollback for stateful apps (e.g. 1.1 to 1.2 with Zero downtime) (up, drain and down mode)

HAProxy - consul_template

This image starts up a dynamically configured HAProxy server. The configuration is automatically generated based on the services registered in a Consul Server. The image also starts consul-template. This process is in charge of watching for Consul changes and for updating the HAProxy template.

After consul_template updates the haproxy.cfg configuration file, the container validates the changes and if the new configuration is valid, then it restarts the haproxy server. Otherwise, the load balancer server is not restarted.

This is an important feature that avoids haproxy outages in case the generated template gets corrupted.

The haproxy.ctmpl template has extension points that allow to dynamically inject HAProxy parameters, so if not done carefully, it might corrupt the configuration file. Fortunately it won't affect the load balance service.

The image lifecycle is initiated, monitored and finalized by S6. See more details here (S6 overlay).

Initialization phase

  1. The container executes consul_template and generates an initial haproxy.cfg template.
  2. Starts the haproxy applications as a Daemon.

If the 'HAProxy' server or the consul_template app fails to start, the container exits immediately. You can override this behavior by changing the environment variable S6_BEHAVIOUR_IF_STAGE2_FAILS=1. Please see how to customize S6 Overlay behavior

How to use this image

Before you can use this image, you need a consul server running. Also, you may like to use registrator to automatically add your services to consul.

Please refer to the compose file docker-compose.yml for an example.

$ git clone
$ cd haproxy-consul
$ docker-compose up
$ curl localhost/webapp

Adding a new services

If running Registrator, just add labels. If not, then register the service directly in consul using the API



Template configurations

Consul KV Description Example
KV/service/haproxy/global Override properties in global section log /dev/log local0
KV/service/haproxy/defaults Override properties in default section log /dev/log local0
service/haproxy/domain Defines the domain base for all the services service.<domain>. $HOSTNAME by Default
KV/service/<service.Name>/domain Overrides the server domain only for the service.Name
KV/service/<service.Name>/serverCookie Defines the server cookie name used for session afinity. JSESSION by default mycookie

TODO - Add curl examples how to update these properties

Docker Pull Command
Source Repository