#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
- 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
- Configure multiple haproxy instances on one machine
- Manage a map file
- 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 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',
},
}
The above shown values are the module's defaults for platforms like Debian and RedHat (see haproxy::params
for details). If you wish to override or add to any of these defaults set merge_options => true
(see below) and set global_options
and/or defaults_options
to a hash containing just the option => value
pairs you need changed or added. In case of duplicates your supplied values will "win" over the default values (this is especially noteworthy for arrays -- they cannot be merged easily). If you want to completely remove a parameter set it to the special value undef
:
class { 'haproxy':
global_options => {
'maxconn' => undef,
'user' => 'root',
'group' => 'root',
'stats' => [
'socket /var/lib/haproxy/stats',
'timeout 30s'
]
},
defaults_options => {
'retries' => '5',
'option' => [
'redispatch',
'http-server-close',
'logasap',
],
'timeout' => [
'http-request 7s',
'connect 3s',
'check 9s',
],
'maxconn' => '15000',
},
}
###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',
],
'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',
],
'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' => '30s',
'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' => '30s' },
{ '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',
],
'balance' => 'roundrobin',
},
}
If option order is important, pass an array of hashes to the options
parameter:
haproxy::backend { 'puppet00':
options => [
{ 'option' => [
'tcplog',
]
},
{ 'balance' => 'roundrobin' },
{ 'cookie' => 'C00 insert' },
],
}
###Set up stick-tables for a frontend (or a backend)
haproxy::backend { 'backend01':
options => [
{ 'stick-table' => 'type ip size 1 nopurge peers LB' },
{ 'stick' => 'on dst' },
],
}
This adds the backend options to the configuration block in the same order as they appear within the array.
###Configure multiple haproxy instances on one machine
This is an advanced feature typically only used at large sites.
It is possible to run multiple haproxy processes ("instances") on the same machine. This has the benefit that each is a distinct failure domain, each can be restarted independently, and each can run a different binary.
In this use case, instead of using Class['haproxy']
, each process
is started using haproxy::instance{'inst'}
where inst
is the
name of the instance. It assumes there is a matching Service['inst']
that will be used to manage service. Different sites may have
different requirements for how the Service[]
is constructed.
However, haproxy::instance_service
exists as an example of one
way to do this, and may be sufficient for most sites.
In this example, two instances are created. The first uses the standard
class and uses haproxy::instance
to add an additional instance called
beta
.
class{ 'haproxy': }
haproxy::listen { 'puppet00':
instance => 'haproxy',
collect_exported => false,
ipaddress => $::ipaddress,
ports => '8800',
}
haproxy::instance { 'beta': }
->
haproxy::instance_service { 'beta':
haproxy_package => 'custom_haproxy',
haproxy_init_source => "puppet:///modules/${module_name}/haproxy-beta.init",
}
->
haproxy::listen { 'puppet00':
instance => 'beta',
collect_exported => false,
ipaddress => $::ipaddress,
ports => '9900',
}
In this example, two instances are created called group1
and group2
.
The second uses a custom package.
haproxy::instance { 'group1': }
->
haproxy::instance_service { 'group1':
haproxy_init_source => "puppet:///modules/${module_name}/haproxy-group1.init",
}
->
haproxy::listen { 'group1-puppet00':
section_name => 'puppet00',
instance => 'group1',
collect_exported => false,
ipaddress => $::ipaddress,
ports => '8800',
}
haproxy::instance { 'group2': }
->
haproxy::instance_service { 'group2':
haproxy_package => 'custom_haproxy',
haproxy_init_source => "puppet:///modules/${module_name}/haproxy-group2.init",
}
->
haproxy::listen { 'group2-puppet00':
section_name => 'puppet00',
instance => 'group2',
collect_exported => false,
ipaddress => $::ipaddress,
ports => '9900',
}
### Manage a map file
~~~puppet
haproxy::mapfile { 'domains-to-backends':
ensure => 'present',
mappings => [
{ 'app01.example.com' => 'bk_app01' },
{ 'app02.example.com' => 'bk_app02' },
{ 'app03.example.com' => 'bk_app03' },
{ 'app04.example.com' => 'bk_app04' },
'app05.example.com bk_app05',
'app06.example.com bk_app06',
],
}
This creates a file /etc/haproxy/domains-to-backends.map
containing the mappings specified in the mappings
array.
The map file can then be used in a frontend to map Host:
values to backends, implementing name-based virtual hosting:
frontend ft_allapps
[...]
use_backend %[req.hdr(host),lower,map(/etc/haproxy/domains-to-backends.map,bk_default)]
Or expressed using haproxy::frontend
:
haproxy::frontend { 'ft_allapps':
ipaddress => '0.0.0.0',
ports => '80',
mode => 'http',
options => {
'use_backend' => '%[req.hdr(host),lower,map(/etc/haproxy/domains-to-backends.map,bk_default)]'
}
}
##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.haproxy::instance
: Creates multiple instances of haproxy on the same machine.haproxy::instance_service
: Example of one way to prepare environment for haproxy::instance.haproxy::mapfile
: Manages an HAProxy map file.
####Private defines
haproxy::balancermember::collect_exported
: Collects exported balancermembers.haproxy::peer::collect_exported
: Collects exported peers.
Main class, includes all other classes.
-
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 ofoption => 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' }
To override or add to any of these default values you don't have to recreate and supply the whole hash, just set
merge_options => true
(see below) and setdefaults_options
to a hash of theoption => value
pairs you'd like to override or add. But note that array values cannot be easily merged with the default values without potentially creating duplicates so you always have to supply the whole array yourself. And if you want a parameter to not appear at all in the resulting configuration set its value toundef
. Example:{ 'retries' => '5', 'timeout' => [ 'http-request 7s', 'http-keep-alive 10s, 'queue 1m', 'connect 5s', 'client 1m', 'server 1m', 'check 10s', ], 'maxconn' => undef, }
-
global_options
: Configures all the global HAProxy options at once. Valid options: a hash ofoption => 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' }
To override or add to any of these default values you don't have to recreate and supply the whole hash, just set
merge_options => true
(see below) and setglobal_options
to a hash of theoption => value
pairs you'd like to override or add. But note that array values cannot be easily merged with the default values without potentially creating duplicates so you always have to supply the whole array yourself. And if you want a parameter to not appear at all in the resulting configuration set its value toundef
. Example:{ log => undef, 'user' => 'root', 'group' => 'root', 'stats' => [ 'socket /var/lib/haproxy/admin.sock mode 660 level admin', 'timeout 30s', ], }
-
merge_options
: Whether to merge the user-suppliedglobal_options
/defaults_options
hashes with their default values set in params.pp. Merging allows to change or add options without having to recreate the entire hash. Defaults tofalse
, but will default totrue
in future releases. -
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 therestart
parameter to Puppet's nativeservice
resource. Valid options: a string. Default: undef (if not specified, Puppet uses theservice
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'. -
service_options
: Contents for the/etc/defaults/haproxy
file on Debian. Defaults to "ENABLED=1\n" on Debian, and is ignored on other systems. -
config_dir
: Path to the directory in which the main configuration filehaproxy.cfg
resides. Will also be used for storing any managed map files (seehaproxy::mapfile
. Default depends on platform.
Configures a service inside a listening or backend service configuration block in haproxy.cfg.
-
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 theserver_names
parameter. For each pair of entries in theipaddresses
andserver_names
arrays, Puppet creates server entries in haproxy.cfg targeting each port specified in theports
parameter. Default: the value of the$::ipaddress
fact. -
listening_service
: Required. Associates the balancermember with anhaproxy::listen
resource. Valid options: a string matching the title of a declaredhaproxy::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 unlesscollect_exported
is set totrue
. 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 theipaddresses
parameter. For each pair of entries in theipaddresses
andserver_names
arrays, Puppet creates server entries in haproxy.cfg targeting each port specified in theports
parameter. Default: the value of the$::hostname
fact. -
instance
: Optional. When usinghaproxy::instance
to run multiple instances of Haproxy on the same machine, this indicates which instance. Defaults to "haproxy".
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).
-
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 thehaproxy::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: -
instance
: Optional. When usinghaproxy::instance
to run multiple instances of Haproxy on the same machine, this indicates which instance. Defaults to "haproxy".
{
'option' => [
'tcplog',
'ssl-hello-chk'
],
'balance' => 'roundrobin'
}
Sets up a frontend service configuration block inside haproxy.cfg. Each frontend service needs one or more balancermember services (declared with the haproxy::balancermember
define).
bind
: Required unlessports
andipaddress
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. Usebind
instead. -
ipaddress
: Required unlessbind
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.
{
'option' => [
'tcplog',
],
}
-
ports
: Required unlessbind
is specified. Specifies which ports to listen on for the address specified inipaddress
. Valid options: an array of port numbers and/or port ranges or a string containing a comma-delimited list of port numbers/ranges. -
instance
: Optional. When usinghaproxy::instance
to run multiple instances of Haproxy on the same machine, this indicates which instance. Defaults to "haproxy".
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).
bind
: Required unlessports
andipaddress
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. Usebind
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 thehaproxy::balancermembers
define. Default: 'true'. -
ipaddress
: Required unlessbind
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 unlessbind
is specified. Specifies which ports to listen on for the address specified inipaddress
. 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).
Sets up a userlist configuration block inside haproxy.cfg.
-
groups
: Required unlessusers
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 'userlist' statement in haproxy.cfg. Valid options: a string. Default: the title of your declared resource. -
users
: Required unlessgroups
is specified. Adds users to the userlist. For more information, see the HAProxy Configuration Manual. Valid options: an array of usernames. Default: undef. -
instance
: Optional. When usinghaproxy::instance
to run multiple instances of Haproxy on the same machine, this indicates which instance. Defaults to "haproxy".
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.
-
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. -
instance
: Optional. When usinghaproxy::instance
to run multiple instances of Haproxy on the same machine, this indicates which instance. Defaults to "haproxy".
Sets up a peer entry inside the peers configuration block in haproxy.cfg.
-
ensure
: Specifies whether the peer should exist in the configuration block. Valid options: 'present' or 'absent'. Default: 'present'. -
ipaddresses
: Required unless thecollect_exported
parameter of yourhaproxy::peers
resource is set totrue
. 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 theserver_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. -
port
: 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 thecollect_exported
parameter of yourhaproxy::peers
resource is set totrue
. 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 toipaddresses
. Puppet pairs up the elements from both arrays and creates a peer for each pair of values. Default: the value of the$::hostname
fact. -
instance
: Optional. When usinghaproxy::instance
to run multiple instances of Haproxy on the same machine, this indicates which instance. Defaults to "haproxy".
Runs multiple instances of haproxy on the same machine. Normally users use the Class['haproxy'], which runs a single haproxy daemon on a machine.
-
package_ensure
: Chooses whether the haproxy package should be installed or uninstalled. Defaults to 'present' -
package_name
: The package name of haproxy. Defaults to undef, and no package is installed. NOTE: Class['haproxy'] has a different default. -
service_ensure
: Chooses whether the haproxy service should be running & enabled at boot, or stopped and disabled at boot. Defaults to 'running' -
service_manage
: Chooses whether the haproxy service state should be managed by puppet at all. Defaults to true -
global_options
: A hash of all the haproxy global options. 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 resultant haproxy.cfg file. -
defaults_options
: A hash of all the haproxy defaults options. 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 resultant haproxy.cfg file. -
restart_command
: Command to use when restarting the on config changes. Passed directly as the'restart'
parameter to the service resource. Defaults to undef i.e. whatever the service default is. -
custom_fragment
: Allows arbitrary HAProxy configuration to be passed through to support additional configuration not available via parameters, or to short-circuit the defined resources such as haproxy::listen when an operater would rather just write plain configuration. Accepts a string (ie, output from the template() function). Defaults to undef -
config_file
: Allows arbitrary config filename to be specified. If this is used, it is assumed that the directory path to the file exists and has owner/group/permissions as desired. If set to undef, the name will be generated as follows: If $title is 'haproxy', the operating system default will be used. Otherwise, /etc/haproxy-$title/haproxy-$title.conf (Linux), or /usr/local/etc/haproxy-$title/haproxy-$title.conf (FreeBSD) The parent directory will be created automatically. Defaults to undef.
Example manifest that shows one way to create the Service[] environment needed by haproxy::instance.
-
haproxy_package
: The name of the package to be installed. This is useful if you package your own custom version of haproxy. Defaults to 'haproxy' -
bindir
: Where to put symlinks to the binary used for each instance. Defaults to '/opt/haproxy/bin' -
haproxy_init_source
: Path to the template init.d script that will start/restart/reload this instance. -
haproxy_unit_template
: Path to the template systemd service unit definition that will start/restart/reload this instance.
Manages an HAProxy map file. A map allows to map data in input to other data on output. This is especially useful for efficiently mapping domain names to backends, thus effectively implementing name-based virtual hosting. A map file contains one key + value per line. These key-value pairs are specified in the mappings
array.
This article on the HAProxy blog gives a nice overview of the use case: http://blog.haproxy.com/2015/01/26/web-application-name-to-backend-mapping-in-haproxy/
-
namevar
: The namevar of the defined resource type is the filename of the map file (without any extension), relative to thehaproxy::config_dir
directory. A '.map' extension is added automatically. -
mappings
: An array of mappings for this map file. Array elements may be Hashes with a single key-value pair each (preferably) or simple Strings. Default:[]
. Example:mappings => [ { 'app01.example.com' => 'bk_app01' }, { 'app02.example.com' => 'bk_app02' }, { 'app03.example.com' => 'bk_app03' }, { 'app04.example.com' => 'bk_app04' }, 'app05.example.com bk_app05', 'app06.example.com bk_app06', ]
-
ensure
: The state of the underlying file resource, either 'present' or 'absent'. Default: 'present' -
owner
: The owner of the underlying file resource. Defaut: 'root' -
group
: The group of the underlying file resource. Defaut: 'root' -
mode
: The mode of the underlying file resource. Defaut: '0644' -
instances
: Array of names of managed HAproxy instances to notify (restart/reload) when the map file is updated. This is so that the same map file can be used with multiple HAproxy instances (if multiple instances are used). Default:[ 'haproxy' ]
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.
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.