#haproxy
####Table of Contents
- Overview
- Module Description - What the module does and why it is useful
- Setup - The basics of getting started with haproxy
- Usage - Configuration options and additional functionality
- Reference - An under-the-hood peek at what the module is doing and how
- Limitations - OS compatibility, etc.
- Development - Guide for contributing to the module
##Overview
The haproxy module provides the ability to install, configure, and manage HAProxy.
##Module Description
HAProxy is a daemon for load-balancing and proxying TCP and HTTP-based services. This module configures proxy servers and manages the configuration of 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
###Configuring 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',
},
}###Configuring 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',
},
}###Configuring multi-network daemon listener
One might have more advanced needs for the listen block, then 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:80' => []
},
}Note: $ports or $ipaddress and $bind are mutually exclusive
###Configuring HAProxy load-balanced member nodes
First, export the resource for a balancer member.
@@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 balancer members at once (this assumes a single-pass installation of HAProxy without requiring a first pass to export the resources, and is intended for situations where you know the members in advance).
haproxy::balancermember { 'haproxy':
listening_service => 'puppet00',
ports => '8140',
server_names => ['server01', 'server02'],
ipaddresses => ['192.168.56.200', '192.168.56.201'],
options => 'check',
}###Configuring a load balancer with exported resources
Install and configure an HAProxy server listening on port 8140 and balanced against all collected nodes. This HAProxy uses storeconfigs to collect and realize balancermember servers on a load balancer server.
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 server will automatically collect configurations from backend servers. The backend nodes will export their HAProxy configurations to the puppet master which will then distribute them to the HAProxy server.
###Classes and Defined Types
####Class: haproxy
This is the main class of the module, guiding the installation and configuration of at least one HAProxy server.
Parameters:
#####custom_fragment
Allows arbitrary HAProxy configuration to be passed through to support additional configuration not otherwise available via parameters. Also allows arbitrary HAPRoxy configuration to short-circuit defined resources, such as haproxy::listen. Accepts a string (e.g. output from the template() function). Defaults to 'undef'.
#####defaults_options
All the default haproxy options, displayed in a hash. If you want to specify more than one option (i.e. multiple timeout or stats options), pass those options as an array and you will get a line for each of them in the resulting haproxy.cfg file.
#####global_options
All the haproxy global options, displayed in a hash. If you want to specify more than one option (i.e. multiple timeout or stats options), pass those options as an array and you will get a line for each of them in the resulting haproxy.cfg file.
#####package_ensure
Determines whether the HAProxy package should be installed or uninstalled. Defaults to 'present'.
#####package_name
Sets the HAProxy package name. Defaults to 'haproxy'.
#####restart_command
Specifies the command to use when restarting the service upon config changes. Passed directly as the restart parameter to the service resource. Defaults to 'undef', i.e. whatever the service default is.
#####service_ensure
Determines whether the HAProxy service should be running & enabled at boot, or stopped and disabled at boot. Defaults to 'running'.
#####service_manage
Specifies whether the HAProxy service state should be managed by Puppet. Defaults to 'true'.
####Defined Type: haproxy::balancermember
This type will set up a balancermember inside a listening or backend service configuration block in /etc/haproxy/haproxy.cfg on the load balancer. Currently, it has the ability to specify the instance name, ip address, port, and whether or not it is a backup.
Automatic discovery of balancermember nodes may be implemented by exporting the balancermember resource for all HAProxy balancer member servers and then collecting them on the main HAProxy load balancer.
Parameters:
#####define_cookies
Determines whether 'cookie SERVERID' stickiness options are added. Defaults to 'false'.
#####ensure
Determines whether the balancermember should be present or absent. Defaults to 'present'.
#####ipaddresses
Specifies the IP address used to contact the balancer member server. Can be an array. If this parameter is specified as an array it must be the same length as the server\_names parameter's array. A balancermember is created for each pair of addresses. These pairs will be multiplied, and additional balancermembers created, based on the number of ports specified.
#####listening_service
Sets the HAProxy service's instance name (or the title of the haproxy::listen resource). This must match a declared haproxy::listen resource.
#####name
Specifies the title of the resource. The name is arbitrary and only utilized in the concat fragment name.
#####options
An array of options to be specified after the server declaration in the listening service's configuration block.
#####ports
Sets the ports on which the balancer member will accept connections from the load balancer. If ports are specified, it must be an array. If you use an array in server\_names and ipaddresses, the number of ports specified will multiply the number of balancermembers formed from the IP address and server name pairs. If no port is specified, the balancermember will receive the traffic on the same port the frontend receive it (Very useful if used with a frontend with multiple bind ports).
#####server_names
Sets the name of the balancermember server in the listening service's configuration block. Defaults to the hostname. Can be an array. If this parameter is specified as an array, it must be the same length as the ipaddresses parameter's array. A balancermember is created for each pair of server\_names and ipaddresses in the array.hese pairs will be multiplied, and additional balancermembers created, based on the number of ports specified.
####Defined Type: haproxy::backend
This type sets up a backend service configuration block inside the haproxy.cfg file on an HAProxy load balancer. Each backend service needs one or more load balancer member servers (declared with the haproxy::balancermember defined type).
Using storeconfigs, you can export the haproxy::balancermember resources on all load balancer member servers and collect them on a single HAProxy load balancer server.
Parameters
#####name
Sets the backend service's name. Generally, it will be the namevar of the defined resource type. This value appears right after the 'backend' statement in haproxy.cfg
#####options
A hash of options that are inserted into the backend service configuration block.
#####collect_exported
Enables exported resources from haproxy::balancermember to be collected, serving as a form of autodiscovery. Displays as a Boolean and defaults to 'true'.
The 'true' value means exported balancermember resources, for the case when every balancermember node exports itself, will be collected. Whereas, 'false' means the existing declared balancermember resources will be relied on; this is meant for cases when you know the full set of balancermembers in advance and use haproxy::balancermember with array arguments, allowing you to deploy everything in a single run.
#####Example
To export the resource for a backend service member,
haproxy::backend { 'puppet00':
options => {
'option' => [
'tcplog',
'ssl-hello-chk',
],
'balance' => 'roundrobin',
},
}####Defined type: haproxy::frontend
This type sets up a frontend service configuration block in haproxy.cfg. The HAProxy daemon uses the directives in the .cfg file to determine which ports/IPs to listen on and route traffic on those ports/IPs to specified balancermembers.
Parameters
#####bind_options
Lists an array of options to be specified after the bind declaration in the bind's configuration block. Deprecated: This parameter is being deprecated in favor of $bind
#####bind
A hash of ipaddress:port, with the haproxy bind options the address will have in the listening service's configuration block.
#####ipaddress
Specifies the IP address the proxy binds to. No value, '*', and '0.0.0.0' mean that the proxy listens to all valid addresses on the system.
#####mode
Sets the mode of operation for the frontend service. Valid values are 'undef', 'tcp', 'http', and 'health'.
#####name
Sets the frontend service's name. Generally, it will be the namevar of the defined resource type. This value appears right after the 'fronted' statement in haproxy.cfg.
#####options
A hash of options that are inserted into the frontend service configuration block.
#####ports
Sets the ports to listen on for the address specified in ipaddress. Accepts a single, comma-separated string or an array of strings, which may be ports or hyphenated port ranges.
#####Example
To route 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 => {
'option' => [ 'default_backend', 'puppet_backend00'],
'timeout client' => '30',
'balance' => 'roundrobin'
'option' => [
'tcplog',
'accept-invalid-http-request',
],
},
}####Defined type: haproxy::listen
This type sets up a listening service configuration block inside the haproxy.cfg file on an HAProxy load balancer. Each listening service configuration needs one or more load balancer member server (declared with the haproxy::balancermember defined type).
Using storeconfigs, you can export the haproxy::balancermember resources on all load balancer member servers and collect them on a single HAProxy load balancer server.
Parameters:
#####bind_options
Sets the options to be specified after the bind declaration in the listening service's configuration block. Displays as an array. Deprecated: This parameter is being deprecated in favor of $bind
#####bind
A hash of ipaddress:port, with the haproxy bind options the address will have in the listening service's configuration block.
#####collect_exported
Enables exported resources from haproxy::balancermember to be collected, serving as a form of autodiscovery. Displays as a Boolean and defaults to 'true'.
The 'true' value means exported balancermember resources, for the case when every balancermember node exports itself, will be collected. Whereas, 'false' means the existing declared balancermember resources will be relied on; this is meant for cases when you know the full set of balancermembers in advance and use haproxy::balancermember with array arguments, allowing you to deploy everything in a single run.
#####ipaddress
Specifies the IP address the proxy binds to. No value, '*', and '0.0.0.0' mean that the proxy listens to all valid addresses on the system.
#####mode
Specifies the mode of operation for the listening service. Valid values are 'undef', 'tcp', 'http', and 'health'.
#####name
Sets the listening service's name. Generally, it will be the namevar of the defined resource type. This value appears right after the 'listen' statement in haproxy.cfg.
#####options
A hash of options that are inserted into the listening service configuration block.
#####ports
Sets the ports to listen on for the address specified in ipaddress. Accepts a single, comma-separated string or an array of strings, which may be ports or hyphenated port ranges.
####Defined Type: haproxy::userlist
This type sets up a userlist configuration block inside the haproxy.cfg file on an HAProxy load balancer.
Parameters:
#####name
Sets the userlist's name. Generally it will be the namevar of the defined resource type. This value appears right after the 'userlist' statement in haproxy.cfg
#####users
An array of users in the userlist. See http://cbonte.github.io/haproxy-dconv/configuration-1.4.html#3.4-user
#####groups
An array of groups in the userlist. See http://cbonte.github.io/haproxy-dconv/configuration-1.4.html#3.4-group
##Reference
###Public classes and defined types
- Class
haproxy: Main configuration class - Define
haproxy::listen: Creates a listen entry in the config - Define
haproxy::frontend: Creates a frontend entry in the config - Define
haproxy::backend: Creates a backend entry in the config - Define
haproxy::balancermember: Creates server entries for listen or backend blocks. - Define
haproxy::userlist: Creates a userlist entry in the config
###Private classes and defined types
- Class
haproxy::params: Per-operatingsystem defaults. - Class
haproxy::install: Installs packages. - Class
haproxy::config: Configures haproxy.cfg. - Class
haproxy::service: Manages service. - Define
haproxy::balancermember::collect_exported: Collects exported balancermembers
##Limitations
RedHat and Debian family OSes are officially supported. Tested and built on Ubuntu and CentOS.
##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 of 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.
You can read the complete module contribution guide on the Puppet Labs wiki.