Forge Home

Modules

Puppet

Resources

PuppetEcosystemPuppet CommunityUpdates

haproxy

Puppet module for HAProxy
Project URLRSS FeedReport issues

7,290,764 downloads

6,003 latest version

2.9 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 8.0.0 (latest)
  • 7.2.1
  • 7.2.0
  • 7.1.0
  • 7.0.0
  • 6.5.0
  • 6.4.0
  • 6.3.0
  • 6.2.1
  • 6.2.0
  • 6.1.0
  • 6.0.2
  • 6.0.1
  • 6.0.0
  • 5.0.0
  • 4.5.0
  • 4.4.0
  • 4.3.0
  • 4.2.1
  • 4.2.0
  • 4.1.0
  • 4.0.0
  • 3.0.1
  • 3.0.0
  • 2.2.0
  • 2.1.0
  • 2.0.1
  • 2.0.0
  • 1.5.0
  • 1.4.0
  • 1.3.1
  • 1.3.0
  • 1.2.0
  • 1.1.0
  • 1.0.0
  • 0.5.0
  • 0.4.1
  • 0.4.0
  • 0.3.0
  • 0.2.0
released Nov 4th 2014
This version is compatible with:
  • Puppet Enterprise 3.x
  • Puppet 3.x
  • , , , , ,

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'puppetlabs-haproxy', '1.1.0'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add puppetlabs-haproxy
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install puppetlabs-haproxy --version 1.1.0

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.

Download
Tags: proxy, haproxy, lb, load-balancer

Documentation

puppetlabs/haproxy — version 1.1.0 Nov 4th 2014

#haproxy

Build Status

####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
  4. Usage - Configuration options and additional functionality
  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 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. 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.

#####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.