Configuring haproxy
===================

TPA will install and configure haproxy on instances whose ``role``
contains ``haproxy`` .

By default, haproxy listens on ``127.0.0.1:5432`` for requests forwarded
by :ref:`Repmgr redirect pgbouncer <Repmgr redirect pgbouncer>`  running on the same instance. You must specify a list
of ``haproxy_backend_servers`` to forward requests to.

TPA will install the latest available version of haproxy by default. You
can install a specific version instead by setting
``haproxy_package_version: 1.9.15*`` (for example).

Note: see limitations of using wildcards in package_version in
:ref:`tpaexec-configure <Cluster configuration>`  .

Haproxy packages are selected according to the type of architecture. An
EDB managed haproxy package may be used but requires a subscription.
Packages from PGDG extras repo can be installed if required.

You can set the following variables on any ``haproxy`` instance.

.. csv-table::
  :header: Variable,Default value,Description
  :widths: 15,12,20
  :align: left
  :class: longtable

  `haproxy_bind_address`,127.0.0.1\*,The address to which haproxy should bind \ *0.0.0.0 if `failover_manager` is patroni. ** Users should change this value to something more restrictive and appropriate for their cluster networking** 
  `haproxy_port`,5432 (5444 for EPAS),The TCP port haproxy should listen on
  `haproxy_read_only_port`,5433 (5445 for EPAS),TCP port for read-only load-balancer
  `haproxy_backend_servers`,None,A list of Postgres instance names
  `haproxy_maxconn`,`max_connections`×0.9,The maximum number of connections allowed per backend server; the default is derived from the backend's `max_connections` setting
  `haproxy_peer_enabled`,True\*,Add known haproxy hosts as `peer` list.  \*`False` if `failover_manager` is harp or patroni.

Read-Only load-balancer
-----------------------

Haproxy can be configured to listen on an additional port for read-only
access to the database. At the moment this is only supported with the
Patroni failover manager. The backend health check determines which
postgres instances are currently acting as replicas and will send
traffic using a roundrobin load balancing algorithm.

The read-only load balancer is disabled by default but can be turned on
using the cluster_vars variable
``haproxy_read_only_load_balancer_enabled`` .

Server options
--------------

TPA will generate ``/etc/haproxy/haproxy.cfg`` with a backend that has a
``default-server`` line and one line per backend server. All but the
first one will be marked as “backup” servers.

Set ``haproxy_default_server_extra_options`` to a list of options on the
haproxy instance to add options to the ``default-server`` line; and set
``haproxy_server_options`` to a list of options on the backend server to
add options (which will override the defaults) to the individual server
lines for each backend.

Example
-------

.. code:: yaml

   instances:

   - Name: one
     vars:
       haproxy_server_options:
       - maxconn 33

   - Name: two
   …

   - Name: proxy
     role:
     - haproxy
     vars:
       haproxy_backend_servers:
       - one
       - two
       haproxy_default_server_extra_options:
       - on-error mark-down
       - on-marked-down shutdown-sessions