haproxy

#haproxy

####Table of Contents

1. Overview
2. Module Description - What the module does and why it is useful
3. Setup - The basics of getting started with haproxy
   • Beginning with haproxy
4. Usage - Configuration options and additional functionality
   • Configure HAProxy options
   • Configure HAProxy daemon listener
   • Configure multi-network daemon listener
   • Configure HAProxy load-balanced member nodes
   • Configure a load balancer with exported resources
   • Set up a frontend service
   • Set up a backend service
5. Reference - An under-the-hood peek at what the module is doing and how
6. Limitations - OS compatibility, etc.
7. Development - Guide for contributing to the module

##Overview

The haproxy module lets you use Puppet to install, configure, and manage HAProxy.

##Module Description

HAProxy is a daemon for load-balancing and proxying TCP- and HTTP-based services. This module lets you use Puppet to configure HAProxy servers and backend member servers.

##Setup

###Beginning with haproxy

The quickest way to get up and running using the haproxy module is to install and configure a basic HAProxy server that is listening on port 8140 and balanced against two nodes:

node 'haproxy-server' {
  class { 'haproxy': }
  haproxy::listen { 'puppet00':
    collect_exported => false,
    ipaddress        => $::ipaddress,
    ports            => '8140',
  }
  haproxy::balancermember { 'master00':
    listening_service => 'puppet00',
    server_names      => 'master00.example.com',
    ipaddresses       => '10.0.0.10',
    ports             => '8140',
    options           => 'check',
  }
  haproxy::balancermember { 'master01':
    listening_service => 'puppet00',
    server_names      => 'master01.example.com',
    ipaddresses       => '10.0.0.11',
    ports             => '8140',
    options           => 'check',
  }
}

##Usage

###Configure HAProxy options

The main haproxy class has many options for configuring your HAProxy server:

class { 'haproxy':
  global_options   => {
    'log'     => "${::ipaddress} local0",
    'chroot'  => '/var/lib/haproxy',
    'pidfile' => '/var/run/haproxy.pid',
    'maxconn' => '4000',
    'user'    => 'haproxy',
    'group'   => 'haproxy',
    'daemon'  => '',
    'stats'   => 'socket /var/lib/haproxy/stats',
  },
  defaults_options => {
    'log'     => 'global',
    'stats'   => 'enable',
    'option'  => 'redispatch',
    'retries' => '3',
    'timeout' => [
      'http-request 10s',
      'queue 1m',
      'connect 10s',
      'client 1m',
      'server 1m',
      'check 10s',
    ],
    'maxconn' => '8000',
  },
}

###Configure HAProxy daemon listener

To export the resource for a balancermember and collect it on a single HAProxy load balancer server:

haproxy::listen { 'puppet00':
  ipaddress => $::ipaddress,
  ports     => '18140',
  mode      => 'tcp',
  options   => {
    'option'  => [
      'tcplog',
      'ssl-hello-chk',
    ],
    'balance' => 'roundrobin',
  },
}

###Configure multi-network daemon listener

If you need a more complex configuration for the listen block, use the $bind parameter:

haproxy::listen { 'puppet00':
  mode    => 'tcp',
  options => {
    'option'  => [
      'tcplog',
      'ssl-hello-chk',
    ],
    'balance' => 'roundrobin',
  },
  bind    => {
    '10.0.0.1:443'             => ['ssl', 'crt', 'puppetlabs.com'],
    '168.12.12.12:80'          => [],
    '192.168.122.42:8000-8100' => ['ssl', 'crt', 'puppetlabs.com'],
    ':8443,:8444'              => ['ssl', 'crt', 'internal.puppetlabs.com']
  },
}

Note: $ports and $ipaddress cannot be used in combination with $bind.

###Configure HAProxy load-balanced member nodes

First export the resource for a balancermember:

@@haproxy::balancermember { 'haproxy':
  listening_service => 'puppet00',
  ports             => '8140',
  server_names      => $::hostname,
  ipaddresses       => $::ipaddress,
  options           => 'check',
}

Then collect the resource on a load balancer:

Haproxy::Balancermember <<| listening_service == 'puppet00' |>>

Then create the resource for multiple balancermembers at once:

haproxy::balancermember { 'haproxy':
  listening_service => 'puppet00',
  ports             => '8140',
  server_names      => ['server01', 'server02'],
  ipaddresses       => ['192.168.56.200', '192.168.56.201'],
  options           => 'check',
}

This example assumes a single-pass installation of HAProxy where you know the members in advance. Otherwise, you'd need a first pass to export the resources.

###Configure a load balancer with exported resources

Install and configure an HAProxy service listening on port 8140 and balanced against all collected nodes:

node 'haproxy-server' {
  class { 'haproxy': }
  haproxy::listen { 'puppet00':
    ipaddress => $::ipaddress,
    ports     => '8140',
  }
}

node /^master\d+/ {
  @@haproxy::balancermember { $::fqdn:
    listening_service => 'puppet00',
    server_names      => $::hostname,
    ipaddresses       => $::ipaddress,
    ports             => '8140',
    options           => 'check',
  }
}

The resulting HAProxy service uses storeconfigs to collect and realize balancermember servers, and automatically collects configurations from backend servers. The backend nodes export their HAProxy configurations to the Puppet master, which then distributes them to the HAProxy server.

###Set up a frontend service

This example routes traffic from port 8140 to all balancermembers added to a backend with the title 'puppet_backend00':

haproxy::frontend { 'puppet00':
  ipaddress     => $::ipaddress,
  ports         => '18140',
  mode          => 'tcp',
  bind_options  => 'accept-proxy',
  options       => {
    'default_backend' => 'puppet_backend00',
    'timeout client'  => '30',
    'option'          => [
      'tcplog',
      'accept-invalid-http-request',
    ],
  },
}

If option order is important, pass an array of hashes to the options parameter:

haproxy::frontend { 'puppet00':
  ipaddress     => $::ipaddress,
  ports         => '18140',
  mode          => 'tcp',
  bind_options  => 'accept-proxy',
  options       => [
    { 'default_backend' => 'puppet_backend00' },
    { 'timeout client'  => '30' },
    { 'option'          => [
        'tcplog',
        'accept-invalid-http-request',
      ],
    }
  ],
}

This adds the frontend options to the configuration block in the same order as they appear within your array.

###Set up a backend service

haproxy::backend { 'puppet00':
  options => {
    'option'  => [
      'tcplog',
      'ssl-hello-chk',
    ],
    'balance' => 'roundrobin',
  },
}

If option order is important, pass an array of hashes to the options parameter:

haproxy::backend { 'puppet00':
  options => [
    { 'option'  => [
        'tcplog',
        'ssl-hello-chk',
      ]
    },
    { 'balance' => 'roundrobin' },
    { 'cookie'  => 'C00 insert' },
  ],
}

This adds the backend options to the configuration block in the same order as they appear within the array.

##Reference

###Classes

####Public classes

• haproxy: Main configuration class.

####Private classes

• haproxy::params: Sets parameter defaults per operating system.
• haproxy::install: Installs packages.
• haproxy::config: Configures haproxy.cfg.
• haproxy::service: Manages the haproxy service.

###Defines

####Public defines

• haproxy::listen: Creates a listen entry in haproxy.cfg.
• haproxy::frontend: Creates a frontend entry in haproxy.cfg.
• haproxy::backend: Creates a backend entry in haproxy.cfg.
• haproxy::balancermember: Creates server entries for listen or backend blocks in haproxy.cfg.
• haproxy::userlist: Creates a userlist entry in haproxy.cfg.
• haproxy::peers: Creates a peers entry in haproxy.cfg.
• haproxy::peer: Creates server entries within a peers entry in haproxy.cfg.

####Private defines

• haproxy::balancermember::collect_exported: Collects exported balancermembers.
• haproxy::peer::collect_exported: Collects exported peers.

Class: haproxy

Main class, includes all other classes.

Parameters (all optional)

• custom_fragment: Inserts an arbitrary string into the configuration file. Useful for configurations not available through other parameters. Valid options: a string (e.g., output from the template() function). Default: undef.

• defaults_options: Configures all the default HAProxy options at once. Valid options: a hash of option => value pairs. To set an option multiple times (e.g. multiple 'timeout' or 'stats' values) pass its value as an array. Each element in your array results in a separate instance of the option, on a separate line in haproxy.cfg. Default:

{
        'log'     => 'global',
        'stats'   => 'enable',
        'option'  => 'redispatch',
        'retries' => '3',
        'timeout' => [
          'http-request 10s',
          'queue 1m',
          'connect 10s',
          'client 1m',
          'server 1m',
          'check 10s',
        ],
        'maxconn' => '8000'
}

• global_options: Configures all the global HAProxy options at once. Valid options: a hash of option => value pairs. To set an option multiple times (e.g. multiple 'timeout' or 'stats' values) pass its value as an array. Each element in your array results in a separate instance of the option, on a separate line in haproxy.cfg. Default:

{
        'log'     => "${::ipaddress} local0",
        'chroot'  => '/var/lib/haproxy',
        'pidfile' => '/var/run/haproxy.pid',
        'maxconn' => '4000',
        'user'    => 'haproxy',
        'group'   => 'haproxy',
        'daemon'  => '',
        'stats'   => 'socket /var/lib/haproxy/stats'
}

• package_ensure: Specifies whether the HAProxy package should exist. Defaults to 'present'. Valid options: 'present' and 'absent'. Default: 'present'.

• package_name: Specifies the name of the HAProxy package. Valid options: a string. Default: 'haproxy'.

• restart_command: Specifies a command that Puppet can use to restart the service after configuration changes. Passed directly as the restart parameter to Puppet's native service resource. Valid options: a string. Default: undef (if not specified, Puppet uses the service default).

• service_ensure: Specifies whether the HAProxy service should be enabled at boot and running, or disabled at boot and stopped. Valid options: 'running' and 'stopped'. Default: 'running'.

• service_manage: Specifies whether the state of the HAProxy service should be managed by Puppet. Valid options: 'true' and 'false'. Default: 'true'.

Define: haproxy::balancermember

Configures a service inside a listening or backend service configuration block in haproxy.cfg.

Parameters

• define_cookies: Optional. Specifies whether to add 'cookie SERVERID' stickiness options. Valid options: 'true' and 'false'. Default: 'false'.

• ensure: Specifies whether the balancermember should be listed in haproxy.cfg. Valid options: 'present' and 'absent'. Default: 'present'.

• ipaddresses: Optional. Specifies the IP address used to contact the balancermember service. Valid options: a string or an array. If you pass an array, it must contain the same number of elements as the array you pass to the server_names parameter. For each pair of entries in the ipaddresses and server_names arrays, Puppet creates server entries in haproxy.cfg targeting each port specified in the ports parameter. Default: the value of the $::ipaddress fact.

• listening_service: Required. Associates the balancermember with an haproxy::listen resource. Valid options: a string matching the title of a declared haproxy::listen resource.

• options: Optional. Adds one or more options to the listening service's configuration block in haproxy.cfg, following the server declaration. Valid options: a string or an array. Default: ''.

• ports: Optional. Specifies one or more ports on which the load balancer sends connections to balancermembers. Valid options: an array. Default: undef. If no port is specified, the load balancer forwards traffic on the same port as received on the frontend.

• server_names: Required unless collect_exported is set to true. Sets the name of the balancermember service in the listening service's configuration block in haproxy.cfg. Valid options: a string or an array. If you pass an array, it must contain the same number of elements as the array you pass to the ipaddresses parameter. For each pair of entries in the ipaddresses and server_names arrays, Puppet creates server entries in haproxy.cfg targeting each port specified in the ports parameter. Default: the value of the $::hostname fact.

Define: haproxy::backend

Sets up a backend service configuration block inside haproxy.cfg. Each backend service needs one or more balancermember services (declared with the haproxy::balancermember define).

Parameters

• collect_exported: Optional. Specifies whether to collect resources exported by other nodes. This serves as a form of autodiscovery. Valid options: 'true' and 'false'. If set to 'false', Puppet only manages balancermembers that you specify through the haproxy::balancermembers define. Default: 'true'.

• name: Optional. Supplies a name for the backend service. This value appears right after the 'backend' statement in haproxy.cfg. Valid options: a string. Default: the title of your declared resource.

• options: Optional. Adds one or more options to the backend service's configuration block in haproxy.cfg. Valid options: a hash or an array. To control the ordering of these options within the configuration block, supply an array of hashes where each hash contains one 'option => value' pair. Default:

{
    'option'  => [
      'tcplog',
      'ssl-hello-chk'
    ],
    'balance' => 'roundrobin'
}

Define: haproxy::frontend

Sets up a backend service configuration block inside haproxy.cfg. Each backend service needs one or more balancermember services (declared with the haproxy::balancermember define).

Parameters

• bind: Required unless ports and ipaddress are specified. Adds one or more bind lines to the frontend service's configuration block in haproxy.cfg. Valid options: a hash of 'address:port' => [parameters] pairs, where the key is a comma-delimited list of one or more listening addresses and ports passed as a string, and the value is an array of bind options. For example:

bind => {
  '168.12.12.12:80'                     => [],
  '192.168.1.10:8080,192.168.1.10:8081' => [],
  '10.0.0.1:443-453'                    => ['ssl', 'crt', 'puppetlabs.com'],
  ':8443,:8444'                         => ['ssl', 'crt', 'internal.puppetlabs.com'],
  '/var/run/haproxy-frontend.sock'      => [ 'user root', 'mode 600', 'accept-proxy' ],
}

For more information, see the HAProxy Configuration Manual.

• bind_options: Deprecated. This setting has never functioned in any version of the haproxy module. Use bind instead.

• ipaddress: Required unless bind is specified. Specifies an IP address for the proxy to bind to. Valid options: a string. If left unassigned or set to '*' or '0.0.0.0', the proxy listens to all valid addresses on the system.

• mode: Optional. Sets the mode of operation for the frontend service. Valid options: 'tcp', 'http', and 'health'. Default: undef.

• name: Optional. Supplies a name for the frontend service. This value appears right after the 'frontend' statement in haproxy.cfg. Valid options: a string. Default: the title of your declared resource.

• options: Optional. Adds one or more options to the frontend service's configuration block in haproxy.cfg. Valid options: a hash or an array. To control the ordering of these options within the configuration block, supply an array of hashes where each hash contains one 'option => value' pair. Default:

{
    'option'  => [
      'tcplog',
    ],
}

• ports: Required unless bind is specified. Specifies which ports to listen on for the address specified in ipaddress. Valid options: an array of port numbers and/or port ranges or a string containing a comma-delimited list of port numbers/ranges.

Define: haproxy::listen

Sets up a listening service configuration block inside haproxy.cfg. Each listening service configuration needs one or more balancermember services (declared with the haproxy::balancermember define).

Parameters

• bind: Required unless ports and ipaddress are specified. Adds one or more bind options to the listening service's configuration block in haproxy.cfg. Valid options: a hash of 'address:port' => [parameters] pairs, where the key is a comma-delimited list of one or more listening addresses and ports passed as a string, and the value is an array of bind options. For example:

bind => {
  '168.12.12.12:80'                     => [],
  '192.168.1.10:8080,192.168.1.10:8081' => [],
  '10.0.0.1:443-453'                    => ['ssl', 'crt', 'puppetlabs.com'],
  ':8443,:8444'                         => ['ssl', 'crt', 'internal.puppetlabs.com'],
  '/var/run/haproxy-frontend.sock'      => [ 'user root', 'mode 600', 'accept-proxy' ],
}

For more information, see the HAProxy Configuration Manual.

• bind_options: Deprecated. This setting has never functioned in any version of the haproxy module. Use bind instead.

• collect_exported: Optional. Specifies whether to collect resources exported by other nodes. This serves as a form of autodiscovery. Valid options: 'true' and 'false'. If set to 'false', Puppet only manages balancermembers that you specify through the haproxy::balancermembers define. Default: 'true'.

• ipaddress: Required unless bind is specified. Specifies an IP address for the proxy to bind to. Valid options: a string. If left unassigned or set to '*' or '0.0.0.0', the proxy listens to all valid addresses on the system.

• mode: Optional. Sets the mode of operation for the listening service. Valid options: 'tcp', 'http', and 'health'. Default: undef.

• name: Optional. Supplies a name for the listening service. This value appears right after the 'listen' statement in haproxy.cfg. Valid options: a string. Default: the title of your declared resource.

• options: Optional. Adds one or more options to the listening service's configuration block in haproxy.cfg. Valid options: a hash or an array. To control the ordering of these options within the configuration block, supply an array of hashes where each hash contains one 'option => value' pair.

• ports: Required unless bind is specified. Specifies which ports to listen on for the address specified in ipaddress. Valid options: a single comma-delimited string or an array of strings. Each string can contain a port number or a hyphenated range of port numbers (e.g., 8443-8450).

Define: haproxy::userlist

Sets up a userlist configuration block inside haproxy.cfg.

Parameters

• groups: Required unless users is specified. Adds groups to the userlist. For more information, see the HAProxy Configuration Manual. Valid options: an array of groupnames. Default: undef.

• name: Optional. Supplies a name for the userlist. This value appears right after the 'listen' statement in haproxy.cfg. Valid options: a string. Default: the title of your declared resource.

• users: Required unless groups is specified. Adds users to the userlist. For more information, see the HAProxy Configuration Manual. Valid options: an array of usernames. Default: undef.

Define: haproxy::peers

Sets up a peers entry in haproxy.cfg on the load balancer. This entry is required to share the current state of HAProxy with other HAProxy instances in high-availability configurations.

Parameters

• collect_exported: Optional. Specifies whether to collect resources exported by other nodes. This serves as a form of autodiscovery. Valid options: 'true' and 'false'. Default: 'true'.

• name: Optional. Appends a name to the peers entry in haproxy.cfg. Valid options: a string. Default: the title of your declared resource.

Define: haproxy::peer

Sets up a peer entry inside the peers configuration block in haproxy.cfg.

Parameters

• ensure: Specifies whether the peer should exist in the configuration block. Valid options: 'present' or 'absent'. Default: 'present'.

• ipaddresses: Required unless the collect_exported parameter of your haproxy::peers resource is set to true. Specifies the IP address used to contact the peer member server. Valid options: a string or an array. If you pass an array, it must contain the same number of elements as the array you pass to the server_names parameter. Puppet pairs up the elements from both arrays and creates a peer for each pair of values. Default: the value of the $::ipaddress fact.

• peers_name: Required. Specifies the peer in which to add the load balancer. Valid options: a string containing the name of an HAProxy peer.

• ports: Required. Specifies the port on which the load balancer sends connections to peers. Valid options: a string containing a port number.

• server_names: Required unless the collect_exported parameter of your haproxy::peers resource is set to true. Sets the name of the peer server as listed in the peers configuration block. Valid options: a string or an array. If you pass an array, it must contain the same number of elements as the array you pass to ipaddresses. Puppet pairs up the elements from both arrays and creates a peer for each pair of values. Default: the value of the $::hostname fact.

##Limitations

This module is tested and officially supported on the following platforms:

• RHEL versions 5, 6, and 7
• Ubuntu versions 10.04, 12.04, and 14.04
• Debian versions 6 and 7
• Scientific Linux versions 5, 6, and 7
• CentOS versions 5, 6, and 7
• Oracle Linux versions 5, 6, and 7

Testing on other platforms has been light and cannot be guaranteed.

Development

Puppet Labs modules on the Puppet Forge are open projects, and community contributions are essential for keeping them great. We can't access the huge number of platforms and myriad hardware, software, and deployment configurations that Puppet is intended to serve. We want to keep it as easy as possible to contribute changes so that our modules work in your environment. There are a few guidelines that we need contributors to follow so that we can have a chance of keeping on top of things.

For more information, see our module contribution guide.

To see who's already involved, see the list of contributors.

Supported Release 1.3.1

###Summary

Small release for support of newer PE versions. This increments the version of PE in the metadata.json file.

2015-07-15 - Supported Release 1.3.0

Summary

This release adds puppet 4 support, and adds the ability to specify the order of option entries for haproxy::frontend and haproxy::listen defined resources.

Features

• Adds puppet 4 compatibility
• Updated readme
• Gentoo compatibility
• Suse compatibility
• Add ability for frontend and listen to be ordered

##2015-03-10 - Supported Release 1.2.0 ###Summary This release adds flexibility for configuration of balancermembers and bind settings, and adds support for configuring peers. This release also renames the tests directory to examples

####Features

• Add support for loadbalancer members without ports
• Add haproxy_version fact (MODULES-1619)
• Add haproxy::peer and haproxy::peers defines
• Make bind parameter processing more flexible

####Bugfixes

• Fix 'RedHat' name for osfamily case in haproxy::params
• Fix lint warnings
• Don't set a default for ipaddress so bind can be used (MODULES-1497)

##2014-11-04 - Supported Release 1.1.0 ###Summary

This release primarily adds greater flexibility in the listen directive.

####Features

• Added bind parameter to haproxy::frontend

####Deprecations

• bind_options in haproxy::frontend is being deprecated in favor of bind
• Remove references to deprecated concat::setup class and update concat dependency

##2014-07-21 - Supported Release 1.0.0 ###Summary

This supported release is the first stable release of haproxy! The updates to this release allow you to customize pretty much everything that HAProxy has to offer (that we could find at least).

####Features

• Brand new readme
• Add haproxy::userlist defined resource for managing users
• Add haproxy::frontend::bind_options parameter
• Add haproxy::custom_fragment parameter for arbitrary configuration
• Add compatibility with more recent operating system releases

####Bugfixes

• Check for listen/backend with the same names to avoid misordering
• Removed warnings when storeconfigs is not being used
• Passing lint
• Fix chroot ownership for global user/group
• Fix ability to uninstall haproxy
• Fix some linting issues
• Add beaker-rspec tests
• Increase unit test coverage
• Fix balancermember server lines with multiple ports

##2014-05-28 - Version 0.5.0 ###Summary

The primary feature of this release is a reorganization of the module to match best practices. There are several new parameters and some bug fixes.

####Features

• Reorganized the module to follow install/config/service pattern
• Added bind_options parameter to haproxy::listen
• Updated tests

####Fixes

• Add license file
• Whitespace cleanup
• Use correct port in README
• Fix order of concat fragments

##2013-10-08 - Version 0.4.1

###Summary

Fix the dependency for concat.

####Fixes

• Changed the dependency to be the puppetlabs/concat version.

##2013-10-03 - Version 0.4.0

###Summary

The largest feature in this release is the new haproxy::frontend and haproxy::backend defines. The other changes are mostly to increase flexibility.

####Features

• Added parameters to haproxy:
• package_name: Allows alternate package name.
• Add haproxy::frontend and haproxy::backend defines.
• Add an ensure parameter to balancermember so they can be removed.
• Made chroot optional

####Fixes

• Remove deprecation warnings from templates.

##2013-05-25 - Version 0.3.0 ####Features

• Add travis testing
• Add haproxy::balancermember define_cookies parameter
• Add array support to haproxy::listen ipaddress parameter

####Bugfixes

• Documentation
• Listen -> Balancermember dependency
• Config line ordering
• Whitespace
• Add template lines for haproxy::listen mode parameter

##2012-10-12 - Version 0.2.0

• Initial public release
• Backwards incompatible changes all around
• No longer needs ordering passed for more than one listener
• Accepts multiple listen ips/ports/server_names