haproxy Cookbook

Installs and configures HAProxy.

Maintainers

This cookbook is maintained by the Sous Chefs. The Sous Chefs are a community of Chef cookbook maintainers working together to maintain important cookbooks. If you’d like to know more please visit sous-chefs.org or come chat with us on the Chef Community Slack in #sous-chefs.

Requirements

HAProxy stable or LTS
Chef 13.9+

Platforms

This cookbook officially supports and is tested against the following platforms:

debian: 9 & 10
ubuntu: 20.04 & 21.04
centos: 7 & 8
centos-stream: 8
fedora: latest
amazonlinux: 2

PRs are welcome to add support for additional platforms.

Examples

Please check for working examples in TEST

Common Resource Features

HAProxy has many configurable options available, this cookbook makes the most popular options available as resource properties.

If you wish to use a HAProxy property that is not listed the extra_options hash is available to take in any number of additional values.

For example, the ability to disable listeners is not provided out of the box. Further examples can be found in either test/fixtures/recipes or spec/test/recipes. If you have questions on how this works or would like to add more examples so it is easier to understand, please come talk to us on the Chef Community Slack on the #sous-chefs channel.

haproxy_listen 'disabled' do
  bind '0.0.0.0:1337'
  mode 'http'
  extra_options('disabled': '')
end

The extra_options hash is of String => String or String => Array. When an Array value is provided. The values are looped over mapping the key to each value in the config.

For example:

haproxy_listen 'default' do
  extra_options(
    'http-request' => [ 'set-header X-Public-User yes', 'del-header X-Bad-Header' ]
    )
end

Becomes:

listen default
  ...
  http-request set-header X-Public-User yes
  http-request del-header X-Bad-Header

Resources

Configuration Validation

The haproxy.cfg file has a few specific rule orderings that will generate validation errors if not loaded properly. If using any combination of the below rules, avoid the errors by loading the rules via extra_options to specify the top down order as noted below in config file.

frontend & listen

  tcp-request connection
  tcp-request session
  tcp-request content
  monitor fail
  block (deprecated)
  http-request
  reqxxx (any req excluding reqadd, e.g. reqdeny, reqallow)
  reqadd
  redirect
  use_backend

  extra_options(
    'tcp-request' => 'connection set-src src,ipmask(24)',
    'reqdeny' => '^Host:\ .*\.local',
    'reqallow' => '^Host:\ www\.',
    'use_backend' => 'dynamic'
  )

backend

  http-request
  reqxxx (any req excluding reqadd, e.g. reqdeny, reqallow)
  reqadd
  redirect

  extra_options(
    'http-request' => 'set-path /%[hdr(host)]%[path]',
    'reqdeny' => '^Host:\ .*\.local',
    'reqallow' => '^Host:\ www\.',
    'redirect' => 'dynamic'
  )