wglass/lighthouse

Configuring HAProxy
====================

The configuration of HAProxy is one of the more complicated (read: flexible!)
parts of the Lighthouse system.  Just about any setup can be accommodated, it's
helpful to have an `HAProxy config reference`_ on hand.

Let's start with an example:

`haproxy.yaml`

.. code-block:: yaml

    config_file: "/etc/haproxy.cfg"
    socket_file: "/var/run/haproxy.sock"
    pid_file: "/var/run/haproxy.pid"
    bind_address: "127.0.0.1"
    global:
      - "daemon"
      - "maxconn 40000"
      - "user haproxy"
      - "log /var/run/syslog local2"
    defaults:
      - "balance roundrobin"
      - "timeout connect 10s"
      - "timeout client 20s"
      - "timeout server 20s"
    stats:
      port: 9009
      uri: "/haproxy"
      timeouts:
        connect: 4000
        server: 30000

The only *required* configuration settings are the `config_file`,
`socket_file`, and `pid_file` but such a bare-bones setup is probably not what
you want.  The main points of configuration will be the `global` and `defaults`
settings, where you can list any HAProxy config directives that will go under
those respective stanzas in the generated config file.


.. note::

   If HAProxy is not currently running when `lighthouse-writer` tries to restart
   it, HAProxy will be started automatically.


Proxies
~~~~~~~~

Sometimes it can be useful to list straight-up proxies in the generated HAProxy
configuration.  For example, if you have a 3rd-party partner API you talk to on
a whitelisted IP basis you would want a dedicated proxy machine with a known
IP that listens on a port and proxies to the business partner.

To facilitate such a use-case the HAProxy YAML config supports a `proxies`
setting.  Each entry in the mapping under `proxies` is a separate named proxy
with certain :ref:`settings requirements <proxies-settings>` themselves.

For example:

`haproxy.yaml`

.. code-block:: yaml

    config_file: "/etc/haproxy.cfg"
    socket_file: "/var/run/haproxy.sock"
    pid_file: "/var/run/haproxy.pid"
    bind_address: "0.0.0.0"
    global:
      - "daemon"
      - "user haproxy"
    proxies:
      business_partner:
          port: 1100
          upstreams:
            - host: "b2b.partner.com"
              port: 88
              max_conn: 400
          options:
            - "mode http"

This config sets up a "business_partner" proxy that takes traffic from the
local port 1100 and forwards it to a partner server on port 88.


Peers
~~~~~~

A new feature available in HAProxy 1.5 and newer is the concept of peers_.

When a node is reported as up and available, information about the HAProxy
instance that lives on the node is included along with it.  This allows the
config file generator to list the peers of each cluster, allowing HAProxy to
coordinate cluster-wide statistics in what's known as `"stick tables"`_.

.. note::

   This feature is automatically used and only available in HAProxy 1.5 and
   newer.


Stats Listener
~~~~~~~~~~~~~~

HAProxy comes with a built-in feature for serving up a status page with all
sorts of useful information.  Each known backend and frontend is listed along
with their statuses and usage statistics (see the `live demo on haproxy.org`_
for an example).

To enable the feature for *your* HAProxy instance, include the `stats` setting
in your YAML config.  A port to use for serving the page is required, check the
:ref:`stats settings <stats-settings>` section for more detailed info.


Settings
~~~~~~~~

* **config_file** *(required)*:

  This is the path of the HAProxy config file that will be automatically
  generated by Lighthouse.

* **socket_file** *(required)*:

  The path to the UNIX socket file Lighthouse should use to communicate with
  HAProxy.

* **pid_file** *(required)*:

  The path to the PID file for HAProxy.

* **global**:

  Optional list of directives to put under the "global" stanza in the generated
  HAProxy config file.

* **defaults**:

  Optional list of directives to put under the "defaults" stanza in the generated
  HAProxy config file.

* **bind_address**:

  The address to bind to for the various ports HAProxy will listen on.  Default
  is "localhost".

* **meta_cluster_ports**:

  A mapping of meta cluster name to a port.  This tells HAProxy to bind to that
  port to handle traffic for the meta cluster.

* **proxies**:

  Optional setting section for configuring simple proxies.  Each of the proxy
  entries have their own settings requirements, see :ref:`proxies-settings`
  below.

* **stats**:

  Optional but recommended feature for having HAProxy serve a simple web page
  with status and metrics info (see the `live demo on haproxy.org`_ for an
  example).  This setting has further required settings that are listed below.


.. _proxies-settings:

Proxies Settings
~~~~~~~~~~~~~~~~

* **port** *(required)*:

  The local port to bind to and listen for traffic to proxy on.

* **upstreams** *(required)*:

  List of servers to proxy traffic to.  If multiple servers are listed they're
  balanced with a round robin algorithm.

* **bind_address**:

  Optional setting for the address to use when binding the local port.  Defaults
  to "localhost".

* **options**:

  A list of extra directive lines to include in the generated "listen" stanza
  for the proxy.


.. _stats-settings:

Stats Settings
~~~~~~~~~~~~~~~~

* **port** *(required)*:

  The local port to bind to and serve up the stats page with.

* **uri**:

  Optional uri path for the page.  For example if the `port` is set to 9009
  and the uri set to "/haproxy_stats", the HAProxy stats page would be available
  at `http://<machine address>:9009/haproxy_stats`.

* **timeouts**:

  Optional timeouts.  These are a mapping from timeout name to value, the
  only names recognized are `connect`, `client` and `server`.


.. _`HAProxy config reference`: http://cbonte.github.io/haproxy-dconv/
.. _`live demo on haproxy.org`: http://demo.haproxy.org
.. _`"stick tables"`: http://cbonte.github.io/haproxy-dconv/configuration-1.5.html#stick-table
.. _peers: https://cbonte.github.io/haproxy-dconv/configuration-1.5.html#3.5