Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Puppet module to dynamically configure haproxy on Redhat family OSes using storeconfigs
branch: 1.1.x

This branch is even with puppetlabs:1.1.x

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
manifests
spec
templates
tests
.fixtures.yml
.gitignore
.nodeset.yml
.travis.yml
CHANGELOG.md
Gemfile
LICENSE
README.md
Rakefile
metadata.json

README.md

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.

Something went wrong with that request. Please try again.