HAProxy is a TCP/HTTP reverse proxy which is particularly suited for high availability environments. It features connection persistence through HTTP cookies, load balancing, header addition, modification, deletion both ways. It has request blocking capabilities and provides interface to display server status.


This charm deploys a reverse proxy in front of other servies. You can use this to load balance existing deployments.


juju deploy haproxy
juju deploy my-web-app
juju add-relation my-web-app:website haproxy:reverseproxy
juju add-unit my-web-app

Reverse Proxy Relation

The reverse proxy relation is used to distribute connections from one frontend
port to many backend services (typically different Juju units). You can use
haproxy just like this, but typically in a production service you would
frontend this service with apache2 to handle the SSL negotiation, etc. See
the "Website Relation" section for more information about that.

When your charm hooks into reverseproxy you have two general approaches
which can be used to notify haproxy about what services you are running.
1) Single-service proxying or 2) Multi-service or relation-driven proxying.

  1. Single-Service Proxying

In this case, your website relation will join underneath a single listen
stanza in haproxy. This stanza will have one service entry for each unit
connecting. By convention, this is typically called "website". The
following is an example of a relation-joined or changed hook:

# hooks/website-relation-joined

relation-set "hostname=$(unit-get private-address)"
relation-set "port=80"

# Set an optional service name, allowing more config-based
# customization
relation-set "service_name=my_web_app"

If you set the service_name relation setting, the configuration services
yaml mapping will be consulted to lookup 3 other options based on service

  • {service_name}_servers - sets the server line in the listen stanza
  • {service_name}_server_options - Will append to the charm-generated
    server line for for each joining unit in the reverseproxy relation.
  • {service_name}_service_options - expected to be a list of strings. Will
    set each item as an option under the listen stanza.
  1. Relation-Driven Proxying

In this relation style, your charm should specify these relation settings
directly as relation variables when joining reverseproxy. Your charm's
website-relation-changed hook would look something like this:

# hooks/website-relation-changed

host=$(unit-get private-address)

relation-set "services=
- { service_name: my_web_app,
    service_options: [mode http, balance leastconn],
    servers: [[my_web_app_1, $host, $port, option httpchk GET / HTTP/1.0],
              [... optionally more servers here ...]]}
- { ... optionally more services here ... }

Once set, haproxy will union multiple servers stanzas from any units
joining with the same service_name under one listen stanza.
service-options and server_options will be overwritten, so ensure they
are set uniformly on all services with the same name.

Website Relation

The website relation is the other side of haproxy. It can communicate with
charms written like apache2 that can act as a front-end for haproxy to take of
things like ssl encryption. When joining a service like apache2 on its
reverseproxy relation, haproxy's website relation will set an all_services
varaible that conforms to the spec layed out in the apache2 charm.

These settings can then be used when crafting your vhost template to make sure
traffic goes to the correct haproxy listener which will in turn forward the
traffic to the correct backend server/port


The following steps are needed for testing and development of the charm,
but not for deployment:

sudo apt-get install python-software-properties
sudo add-apt-repository ppa:cjohnston/flake8
sudo apt-get update
sudo apt-get install python-mock python-flake8 python-nose python-nosexcover python-testtools charm-tools

To run the tests:

make build

... will run the unit tests, run flake8 over the source to warn about
formatting issues and output a code coverage summary of the '' module.

Known Limitations and Issues

  • Expand Single-Service section as I have not tested that mode fully.
  • Trigger website-relation-changed when the reverse-proxy relation changes


Many of the haproxy settings can be altered via the standard juju configuration
settings. Please see the config.yaml file as each is fairly clearly documented.


This charm supports sending metrics to statsd.

This is done by setting config values (metrics_target being the primary one)
to a host/port of a (UDP) statsd server.

This could instead be done using a relation, but it is common to have
one statsd server that serves multiple environments. Once juju supports
cross-environment relations then that will be the best way to handle
this configuration, as it will work in either scenario.

HAProxy Project Information


(string) Used by the nrpe-external-master subordinate charm. A string that will be prepended to instance name to set the host name in nagios. So for instance the hostname would be something like: juju-postgresql-0 If you're running multiple environments with the same services in them this allows you to differentiate between them.
(string) YAML-formatted list of sysctl values, e.g.: '{ net.ipv4.tcp_max_syn_backlog : 65536 }'
(int) Set the number of retries to perform on a server after a connection failure. It is important to understand that this value applies to the number of connection attempts, not full requests. When a connection has effectively been established to a server, there will be no more retry. In order to avoid immediate reconnections to a server which is restarting, a turn-around timer of 1 second is applied before a retry occurs.
(boolean) Whether to enable the stats UNIX socket.
(string) Group
(int) Monitoring interface refresh interval (in seconds)
(string) Default options
httplog, dontlognull
(string) User
(string) Optional configuration to support use of additional sources such as: . - ppa:myteam/ppa - cloud:precise-proposed/folsom - main . The last option should be used in conjunction with the key configuration option.
(string) Password to the monitoring interface ( if "changeme", a new password will be generated and displayed in juju-log )
(string) Default mode
(string) Prefix for metrics. Special value $UNIT can be used to include the name of the unit in the prefix.
(string) Default timeouts
queue 20000, client 50000, connect 5000, server 50000
(string) Global log line ( multiples ... comma separated list ) local0, local1 notice
(int) Sometimes it is desirable to avoid sending health checks to servers at exact intervals, for instance when many logical servers are located on the same physical server. With the help of this parameter, it becomes possible to add some randomness in the check interval between 0 and +/- 50%. A value between 2 and 5 seems to show good results.
(string) CIDR allowed ( multiple CIDRs separated by space ) access to the monitoring interface.
(string) Monitoring username
(string) Default log
(string) The status of service-affecting packages will be set to this value in the dpkg database. Useful valid values are "install" and "hold".
(string) Key ID to import to the apt keyring to support use with arbitary source configuration from outside of Launchpad archives or PPA's.
(string) Services definition(s). Although the variable type is a string, this is interpreted in the charm as yaml. To use multiple services within the same haproxy instance, specify all of the variables (service_name, service_host, service_port, service_options, server_options) with a "-" before the first variable, service_name, as above. Service options is a comma separated list, server options will be appended as a string to the individual server lines for a given listen stanza. If your web application serves dynamic content based on users' login sessions, a visitor will experience unexpected behaviour if each request is proxied to a different backend web server. Session stickiness ensures that a visitor 'sticks' to the backend web server which served their first request. This is made possible by tagging each backend server with a cookie. Session are sticky by default. To turn off sticky sessions, remove the 'cookie SRVNAME insert' and 'cookie S{i}' stanzas from `service_options` and `server_options`.
- service_name: haproxy_service service_host: "" service_port: 80 service_options: [balance leastconn, cookie SRVNAME insert] server_options: maxconn 100 cookie S{i} check
(int) Sets the maximum per-process number of concurrent connections to <number>.
(string) Destination for statsd-format metrics, format "host:port". If not present and valid, metrics disabled. Requires "enable_monitoring" to be set to true to work.
(int) Default monitoring port
(boolean) Debug or not
(int) Period for metrics cron job to run in minutes
(boolean) Quiet
(boolean) Enable monitoring