elasticio/haproxy-srv repository overview

⁠HAProxy SRV

HAProxy-SRV is a templating solution that can flexibly reconfigure HAProxy based on the regular polling of the service data from DNS (e.g. SkyDNS or Mesos-DNS) using SRV records.

HAProxy-SRV also works with Round-Robin DNS A records, like Docker Swarm Mode.

It has a very simple logic - HA Proxy is configured based on the Handlebars template that is re-evaluated every time changes in DNS are detecting. Script is polling DNS and trigger a HA Proxy configuration refresh after changes.

Made by elastic.io⁠ in Germany.

⁠Quick start

Simplest way to start it with Docker:

docker run -d -p 8080:8080 -p 80:80 -v $PWD/haproxy.cfg.template:/src/haproxy.cfg.template elasticio/haproxy-srv:latest

if you want to see more DEBUG output then just add -e "DEBUG=*"

⁠How it works

Script works very simple - after docker container started script parse and validates template, create a HAProxy configuration file in /src/haproxy.cfg and start HAProxy as a daemon. Every second (by default, can be configured via REFRESH_TIMEOUT env variable, default 1000) scirpt will execute a DNS lookup and re-evaluate the template, if result of evaluation is different from original configuration, original config will be overwritten and HAProxy reload will be triggered. HAProxy reload will not affect existing connections.

⁠How to use it

Recommended way to deploy is is to use a Docker image⁠. You would need to place your configuration file template, the simples way to do it is to build an image based on haproxy-srv image.

Create a new Dockerfile content like this:

FROM elasticio/haproxy-srv:latest

COPY haproxy.cfg.template /src/

EXPOSE 80 8880

Note the EXPOSE part here, don't forget to specify exposed ports if your HAProxy configuration listens on any port different from 80.

As a next step create a template file, it should be placed under /src/haproxy.cfg.template in resulting Docker container and should have a Handlebars⁠ syntax with one little extension (see below). Here is the sample:

global
    user root
    group root

    # Stats required for this module to work
    # https://github.com/observing/haproxy#haproxycfg
    stats socket /tmp/haproxy.sock level admin

defaults
    mode    http
    timeout connect 5000
    timeout client  50000
    timeout server  50000

{{#dns-srv "_frontend._tcp.marathon.mesos"}}
    frontend sample
        bind 0.0.0.0:80
        balance roundrobin
        option http-server-close
        option forwardfor
        {{#each this}}
            server frontend-{{@index}} {{ip}}:{{port}} check weight {{weight}}
        {{/each}}
{{/dns-srv}}

# Standard DNS Round-Robin
{{#dns-a "cluster.example.com"}}
  frontend sample2
    bind 0.0.0.0:8080
    {{#each this}}
      server {{name}} {{ip}}:80 check
    {{/each}}
{{/dns-a}}

# Docker Swarm Mode example
{{#dns-a "tasks.myservice"}}
  frontend sample3
    bind 0.0.0.0:8081
    {{#each this}}
      server {{name}} {{ip}}:80 check
    {{/each}}
{{/dns-a}}

It could be any valid HAProxy configuration with one mandatory addition:

stats socket /tmp/haproxy.sock level admin

to trigger HAProxy restart the script inside the file will communicate with HAProxy daemon via socket /tmp/haproxy.sock.

⁠Template

Configuration template is a normal Handlebars⁠ so that you could use any of the feature of this template language. There is however one additional helper dns-srv implemented. This helper takes one string parameter and will execute a DNS SRV lookup⁠ to fetch an SRV record(s). After SRV Record lookup, for each SRV record a DNS resolution⁠ to find the IP will be made.

This template will give you an idea how to use it:

# Your usual configuration is here
{{#dns-srv "_frontend._tcp.marathon.mesos"}}
    # This block will only be rendered when _frontend._tcp.marathon.mesos was found in DNS
    {{#each this}}
        # This piece will be rendered for each SRV entry from DNS
        SRV Name is {{name}}
        SRV Weight is {{weight}}
        SRV Port is {{port}}
        IP for SRV Name is {{ip}}
    {{/each}}
{{/dns-srv}}
# rest of your configuration

Typical use-case for Msos-DNS you can see above.

⁠Docker Swarm Mode Guide

First, create a network, and web service:

$ docker network create -d overlay --subnet 10.1.1.0/24 my_net
$ docker service create --replicas 2 --name my_web --network my_net nginx

By default, services are created as --endpoint-mode vip. If you use VIP mode, then the Round-Robin DNS name is tasks.my_web. If you use --endpoint-mode dnsrr then the my_web DNS name will work in the HAProxy dns-a template.

Follow the How to use it section above on creating a new proxy image using a custom haproxy.cfg.template. For the dns-a section use:

{{#dns-a "tasks.my_web"}}
  # other configs
  backend my_web
  {{#each this}}
    server {{name}} {{ip}}:80 check
  {{/each}}
{{/dns-a}}

$ mkdir my_proxy ; cd my_proxy
#  (make a new Dockerfile)
$ docker build -t my_proxy_image .

Fire up a new proxy, publishing port 80 to something unique on each docker host node

$ docker service create --name my_proxy --network my_net -p 8081:80 my_proxy_image

Optionally, use some other method for sharing & binding the haproxy.cfg.template file into the elasticio/haproxy-srv image.

⁠Debugging

Just set the DEBUG environment variable into * to see detailed logging.

⁠TODOs

PRs are welcome for

• Bug fixes
• Unit tests
• Gulp or Grunt-based builds
• CircleCI config for continous integration