{"id":15022583,"url":"https://github.com/puppetlabs/puppetlabs-haproxy","last_synced_at":"2025-09-30T06:31:13.757Z","repository":{"id":4440779,"uuid":"5579089","full_name":"puppetlabs/puppetlabs-haproxy","owner":"puppetlabs","description":"Puppet module to dynamically configure haproxy on Redhat family OSes using storeconfigs","archived":false,"fork":true,"pushed_at":"2024-09-24T11:24:10.000Z","size":1092,"stargazers_count":102,"open_issues_count":20,"forks_count":267,"subscribers_count":146,"default_branch":"main","last_synced_at":"2024-09-25T21:24:51.391Z","etag":null,"topics":["hacktoberfest","module","supported"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"glarizza/puppet-haproxy","license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/puppetlabs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null}},"created_at":"2012-08-28T00:48:30.000Z","updated_at":"2024-09-24T11:24:13.000Z","dependencies_parsed_at":"2023-07-06T14:02:11.023Z","dependency_job_id":"84f6a01e-02ae-4faf-ab11-d8fa79692378","html_url":"https://github.com/puppetlabs/puppetlabs-haproxy","commit_stats":{"total_commits":523,"total_committers":147,"mean_commits":3.557823129251701,"dds":0.9273422562141491,"last_synced_commit":"419067a0a57a93a16bb913dff89b20a89b3291e5"},"previous_names":[],"tags_count":39,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fpuppetlabs-haproxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fpuppetlabs-haproxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fpuppetlabs-haproxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fpuppetlabs-haproxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/puppetlabs","download_url":"https://codeload.github.com/puppetlabs/puppetlabs-haproxy/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219873900,"owners_count":16554524,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest","module","supported"],"created_at":"2024-09-24T19:58:08.687Z","updated_at":"2025-09-30T06:31:08.428Z","avatar_url":"https://github.com/puppetlabs.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# haproxy\n\n#### Table of Contents\n\n1. [Overview](#overview)\n2. [Module Description - What the module does and why it is useful](#module-description)\n3. [Setup - The basics of getting started with haproxy](#setup)\n    * [Beginning with haproxy](#beginning-with-haproxy)\n4. [Usage - Configuration options and additional functionality](#usage)\n    * [Configure HAProxy options](#configure-haproxy-options)\n    * [HAProxy and Software Collections](#haproxy-and-software-collections)\n    * [Configure HAProxy daemon listener](#configure-haproxy-daemon-listener)\n    * [Configure multi-network daemon listener](#configure-multi-network-daemon-listener)\n    * [Configure HAProxy load-balanced member nodes](#configure-haproxy-load-balanced-member-nodes)\n    * [Configure a load balancer with exported resources](#configure-a-load-balancer-with-exported-resources)\n    * [Set up a frontend service](#set-up-a-frontend-service)\n    * [Set up a backend service](#set-up-a-backend-service)\n    * [Set up a resolver](#set-up-a-resolver)\n    * [Configure multiple haproxy instances on one machine](#configure-multiple-haproxy-instances-on-one-machine)\n    * [Manage a map file](#manage-a-map-file)\n5. [Reference - An under-the-hood peek at what the module is doing and how](#reference)\n6. [Limitations - OS compatibility, etc.](#limitations)\n7. [License](#license)\n7. [Development - Guide for contributing to the module](#development)\n\n## Overview\n\nThe haproxy module lets you use Puppet to install, configure, and manage HAProxy.\n\n## Module Description\n\nHAProxy 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.\n\n## Setup\n\n### Beginning with haproxy\n\nThe simplest HAProxy configuration consists of a server that listens on a port and balances against some other nodes:\n\n~~~puppet\nnode 'haproxy-server' {\n  include ::haproxy\n  haproxy::listen { 'puppet00':\n    collect_exported =\u003e false,\n    ipaddress        =\u003e $facts['networking']['ip'],\n    ports            =\u003e [8140],\n  }\n  haproxy::balancermember { 'server00':\n    listening_service =\u003e 'puppet00',\n    server_names      =\u003e 'server00.example.com',\n    ipaddresses       =\u003e '10.0.0.10',\n    ports             =\u003e [8140],\n    options           =\u003e 'check',\n  }\n  haproxy::balancermember { 'server01':\n    listening_service =\u003e 'puppet00',\n    server_names      =\u003e 'server01.example.com',\n    ipaddresses       =\u003e '10.0.0.11',\n    ports             =\u003e [8140],\n    options           =\u003e 'check',\n  }\n}\n~~~\n\n## Usage\n\n### Configure HAProxy options\n\nThe main [`haproxy` class](#class-haproxy) has many options for configuring your HAProxy server:\n\n~~~puppet\nclass { 'haproxy':\n  global_options   =\u003e {\n    'log'     =\u003e \"${facts['networking']['ip']} local0\",\n    'chroot'  =\u003e '/var/lib/haproxy',\n    'pidfile' =\u003e '/var/run/haproxy.pid',\n    'maxconn' =\u003e '4000',\n    'user'    =\u003e 'haproxy',\n    'group'   =\u003e 'haproxy',\n    'daemon'  =\u003e '',\n    'stats'   =\u003e 'socket /var/lib/haproxy/stats',\n  },\n  defaults_options =\u003e {\n    'log'     =\u003e 'global',\n    'stats'   =\u003e 'enable',\n    'option'  =\u003e [\n      'redispatch',\n    ],\n    'retries' =\u003e '3',\n    'timeout' =\u003e [\n      'http-request 10s',\n      'queue 1m',\n      'connect 10s',\n      'client 1m',\n      'server 1m',\n      'check 10s',\n    ],\n    'maxconn' =\u003e '8000',\n  },\n}\n~~~\n\nThe 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 =\u003e true` (see below) and set `global_options` and/or `defaults_options` to a hash containing just the `option =\u003e 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`:\n\n~~~puppet\nclass { 'haproxy':\n  global_options   =\u003e {\n    'maxconn' =\u003e undef,\n    'user'    =\u003e 'root',\n    'group'   =\u003e 'root',\n    'stats'   =\u003e [\n      'socket /var/lib/haproxy/stats',\n      'timeout 30s'\n    ]\n  },\n  defaults_options =\u003e {\n    'retries' =\u003e '5',\n    'option'  =\u003e [\n      'redispatch',\n      'http-server-close',\n      'logasap',\n    ],\n    'timeout' =\u003e [\n      'http-request 7s',\n      'connect 3s',\n      'check 9s',\n    ],\n    'maxconn' =\u003e '15000',\n  },\n}\n~~~\n\n### HAProxy and Software Collections\n\nTo use this module with a software collection such as\n[rh-haproxy18](https://www.softwarecollections.org/en/scls/rhscl/rh-haproxy18/)\nyou will need to set a few extra parameters like so:\n\n~~~puppet\nclass { 'haproxy':\n  package_name        =\u003e 'rh-haproxy18',\n  config_dir          =\u003e '/etc/opt/rh/rh-haproxy18/haproxy',\n  config_file         =\u003e '/etc/opt/rh/rh-haproxy18/haproxy/haproxy.cfg',\n  config_validate_cmd =\u003e '/bin/scl enable rh-haproxy18 \"haproxy -f % -c\"',\n  service_name        =\u003e 'rh-haproxy18-haproxy',\n}\n~~~\n\n### Configure HAProxy daemon listener\n\nTo export the resource for a balancermember and collect it on a single HAProxy load balancer server:\n\n~~~puppet\nhaproxy::listen { 'puppet00':\n  ipaddress =\u003e $facts['networking']['ip'],\n  ports     =\u003e [8140],\n  mode      =\u003e 'tcp',\n  options   =\u003e {\n    'option'  =\u003e [\n      'tcplog',\n    ],\n    'balance' =\u003e 'roundrobin',\n  },\n}\n~~~\n\n### Configure multi-network daemon listener\n\nIf you need a more complex configuration for the listen block, use the `$bind` parameter:\n\n~~~puppet\nhaproxy::listen { 'puppet00':\n  mode    =\u003e 'tcp',\n  options =\u003e {\n    'option'  =\u003e [\n      'tcplog',\n    ],\n    'balance' =\u003e 'roundrobin',\n  },\n  bind    =\u003e {\n    '10.0.0.1:443'             =\u003e ['ssl', 'crt', 'puppetlabs.com'],\n    '168.12.12.12:80'          =\u003e [],\n    '192.168.122.42:8000-8100' =\u003e ['ssl', 'crt', 'puppetlabs.com'],\n    ':8443,:8444'              =\u003e ['ssl', 'crt', 'internal.puppetlabs.com']\n  },\n}\n~~~\n\n**Note:** `$ports` and `$ipaddress` cannot be used in combination with `$bind`.\n\n### Configure HAProxy load-balanced member nodes\n\nFirst export the resource for a balancermember:\n\n~~~puppet\n@@haproxy::balancermember { 'haproxy':\n  listening_service =\u003e 'puppet00',\n  ports             =\u003e '8140',\n  server_names      =\u003e $facts['networking']['hostname'],\n  ipaddresses       =\u003e $facts['networking']['ip'],\n  options           =\u003e 'check',\n}\n~~~\n\nThen collect the resource on a load balancer:\n\n~~~puppet\nHaproxy::Balancermember \u003c\u003c| listening_service == 'puppet00' |\u003e\u003e\n~~~\n\nThen create the resource for multiple balancermembers at once:\n\n~~~puppet\nhaproxy::balancermember { 'haproxy':\n  listening_service =\u003e 'puppet00',\n  ports             =\u003e 8140,\n  server_names      =\u003e ['server01', 'server02'],\n  ipaddresses       =\u003e ['192.168.56.200', '192.168.56.201'],\n  options           =\u003e 'check',\n}\n~~~\n\nThis 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.\n\n### Configure a load balancer with exported resources\n\nInstall and configure an HAProxy service listening on port 8140 and balanced against all collected nodes:\n\n~~~puppet\nnode 'haproxy-server' {\n  include ::haproxy\n  haproxy::listen { 'puppet00':\n    ipaddress =\u003e $facts['networking']['ip'],\n    ports     =\u003e 8140,\n  }\n}\n\nnode /^server\\d+/ {\n  @@haproxy::balancermember { $facts['networking']['fqdn']:\n    listening_service =\u003e 'puppet00',\n    server_names      =\u003e $facts['networking']['hostname'],\n    ipaddresses       =\u003e $facts['networking']['ip'],\n    ports             =\u003e 8140,\n    options           =\u003e 'check',\n  }\n}\n~~~\n\nThe 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 Server, which then distributes them to the HAProxy server.\n\n### Set up a frontend service\n\nThis example routes traffic from port 8140 to all balancermembers added to a backend with the title 'puppet_backend00':\n\n~~~puppet\nhaproxy::frontend { 'puppet00':\n  ipaddress     =\u003e $facts['networking']['ip'],\n  ports         =\u003e 8140,\n  mode          =\u003e 'tcp',\n  bind_options  =\u003e 'accept-proxy',\n  options       =\u003e {\n    'default_backend' =\u003e 'puppet_backend00',\n    'timeout client'  =\u003e '30s',\n    'option'          =\u003e [\n      'tcplog',\n      'accept-invalid-http-request',\n    ],\n  },\n}\n~~~\n\nIf option order is important, pass an array of hashes to the `options` parameter:\n\n~~~puppet\nhaproxy::frontend { 'puppet00':\n  ipaddress     =\u003e $facts['networking']['ip'],\n  ports         =\u003e [8140],\n  mode          =\u003e 'tcp',\n  bind_options  =\u003e 'accept-proxy',\n  options       =\u003e [\n    { 'default_backend' =\u003e 'puppet_backend00' },\n    { 'timeout client'  =\u003e '30s' },\n    { 'option'          =\u003e [\n        'tcplog',\n        'accept-invalid-http-request',\n      ],\n    }\n  ],\n}\n~~~\n\nThis adds the frontend options to the configuration block in the same order as they appear within your array.\n\n### Set up a backend service\n\n~~~puppet\nhaproxy::backend { 'puppet00':\n  options =\u003e {\n    'option'  =\u003e [\n      'tcplog',\n    ],\n    'balance' =\u003e 'roundrobin',\n  },\n}\n~~~\n\nIf option order is important, pass an array of hashes to the `options` parameter:\n\n~~~puppet\nhaproxy::backend { 'puppet00':\n  options =\u003e [\n    { 'option'  =\u003e [\n        'tcplog',\n      ]\n    },\n    { 'balance' =\u003e 'roundrobin' },\n    { 'cookie'  =\u003e 'C00 insert' },\n  ],\n}\n~~~\n\n### Set up a resolver\n\nNote: This is only available on haproxy 1.6+\n\n~~~puppet\n# Need to start with an init-addr parameter set to none and enable runtime DNS resolution.\nclass { 'haproxy':\n...\n  defaults_options =\u003e {\n    'default-server' =\u003e 'init-addr none',\n...\n  },\n}\n\n# Declare the resolver\nhaproxy::resolver { 'puppet00':\n  nameservers           =\u003e {\n    'dns1' =\u003e '192.168.56.1:53',\n    'dns2' =\u003e '192.168.56.2:53'\n  },\n  hold                  =\u003e {\n    'nx'    =\u003e '30s',\n    'valid' =\u003e '10s'\n  },\n  resolve_retries       =\u003e 3,\n  timeout               =\u003e {\n    'retry' =\u003e '1s'\n  },\n  accepted_payload_size =\u003e 512,\n}\n\n# Setup the balancermember to use the resolver for DNS resolution\nhaproxy::balancermember { 'haproxy':\n  listening_service =\u003e 'puppet00',\n  ports             =\u003e 8140,\n  server_names      =\u003e ['server01', 'server02'],\n  ipaddresses       =\u003e ['server01', 'server02'],\n  options           =\u003e 'check resolvers puppet00 resolve-prefer ipv4',\n}\n~~~\n\n### Set up stick-tables for a frontend (or a backend)\n\n~~~puppet\nhaproxy::backend { 'backend01':\n  options =\u003e [\n    { 'stick-table' =\u003e 'type ip size 1 nopurge peers LB' },\n    { 'stick'       =\u003e 'on dst' },\n  ],\n}\n~~~\n\nThis adds the backend options to the configuration block in the same order as they appear within the array.\n\n### Configure multiple haproxy instances on one machine\n\nThis is an advanced feature typically only used at large sites.\n\nIt is possible to run multiple haproxy processes (\"instances\") on the\nsame machine. This has the benefit that each is a distinct failure domain,\neach can be restarted independently, and each can run a different binary.\n\nIn this use case, instead of using `Class['haproxy']`, each process\nis started using `haproxy::instance{'inst'}` where `inst` is the\nname of the instance.  It assumes there is a matching `Service['inst']`\nthat will be used to manage service.  Different sites may have\ndifferent requirements for how the `Service[]` is constructed.\nHowever, `haproxy::instance_service` exists as an example of one\nway to do this, and may be sufficient for most sites.\n\nIn this example, two instances are created. The first uses the standard\nclass and uses `haproxy::instance` to add an additional instance called\n`beta`.\n\n~~~puppet\n   include ::haproxy\n   haproxy::listen { 'puppet00':\n     instance         =\u003e 'haproxy',\n     collect_exported =\u003e false,\n     ipaddress        =\u003e $facts['networking']['ip'],\n     ports            =\u003e 8800,\n   }\n\n   haproxy::instance { 'beta': }\n   -\u003e\n   haproxy::instance_service { 'beta':\n     haproxy_package     =\u003e 'custom_haproxy',\n     haproxy_init_source =\u003e \"puppet:///modules/${module_name}/haproxy-beta.init\",\n   }\n   -\u003e\n   haproxy::listen { 'puppet00':\n     instance         =\u003e 'beta',\n     collect_exported =\u003e false,\n     ipaddress        =\u003e $facts['networking']['ip'],\n     ports            =\u003e 9900,\n   }\n~~~\n\nIn this example, two instances are created called `group1` and `group2`.\nThe second uses a custom package.\n\n~~~puppet\n   haproxy::instance { 'group1': }\n   -\u003e\n   haproxy::instance_service { 'group1':\n     haproxy_init_source =\u003e \"puppet:///modules/${module_name}/haproxy-group1.init\",\n   }\n   -\u003e\n   haproxy::listen { 'group1-puppet00':\n     section_name     =\u003e 'puppet00',\n     instance         =\u003e 'group1',\n     collect_exported =\u003e false,\n     ipaddress        =\u003e $facts['networking']['ip'],\n     ports            =\u003e 8800,\n   }\n   haproxy::instance { 'group2': }\n   -\u003e\n   haproxy::instance_service { 'group2':\n     haproxy_package     =\u003e 'custom_haproxy',\n     haproxy_init_source =\u003e \"puppet:///modules/${module_name}/haproxy-group2.init\",\n   }\n   -\u003e\n   haproxy::listen { 'group2-puppet00':\n     section_name     =\u003e 'puppet00',\n     instance         =\u003e 'group2',\n     collect_exported =\u003e false,\n     ipaddress        =\u003e $facts['networking']['ip'],\n     ports            =\u003e 9900,\n   }\n~~~\n\n### Manage a map file\n\n~~~puppet\nhaproxy::mapfile { 'domains-to-backends':\n  ensure   =\u003e 'present',\n  mappings =\u003e [\n    { 'app01.example.com' =\u003e 'bk_app01' },\n    { 'app02.example.com' =\u003e 'bk_app02' },\n    { 'app03.example.com' =\u003e 'bk_app03' },\n    { 'app04.example.com' =\u003e 'bk_app04' },\n    'app05.example.com bk_app05',\n    'app06.example.com bk_app06',\n  ],\n}\n~~~\n\nThis creates a file `/etc/haproxy/domains-to-backends.map` containing the mappings specified in the `mappings` array.\n\nThe map file can then be used in a frontend to map `Host:` values to backends, implementing name-based virtual hosting:\n\n```\nfrontend ft_allapps\n  [...]\n  use_backend %[req.hdr(host),lower,map(/etc/haproxy/domains-to-backends.map,bk_default)]\n```\n\nOr expressed using `haproxy::frontend`:\n\n~~~puppet\nhaproxy::frontend { 'ft_allapps':\n  ipaddress =\u003e '0.0.0.0',\n  ports     =\u003e ['80'],\n  mode      =\u003e 'http',\n  options   =\u003e {\n    'use_backend' =\u003e '%[req.hdr(host),lower,map(/etc/haproxy/domains-to-backends.map,bk_default)]'\n  }\n}\n~~~\n\n## Reference\n\nFor information on the classes and types, see the [REFERENCE.md](https://github.com/puppetlabs/puppetlabs-haproxy/blob/main/REFERENCE.md)\n\n## Limitations\n\nFor an extensive list of supported operating systems, see [metadata.json](https://github.com/puppetlabs/puppetlabs-haproxy/blob/main/metadata.json)\n\n## License\n\nThis codebase is licensed under the Apache2.0 licensing, however due to the nature of the codebase the open source dependencies may also use a combination of [AGPL](https://opensource.org/license/agpl-v3/), [BSD-2](https://opensource.org/license/bsd-2-clause/), [BSD-3](https://opensource.org/license/bsd-3-clause/), [GPL2.0](https://opensource.org/license/gpl-2-0/), [LGPL](https://opensource.org/license/lgpl-3-0/), [MIT](https://opensource.org/license/mit/) and [MPL](https://opensource.org/license/mpl-2-0/) Licensing.\n\n## Development\n\nAcceptance tests for this module leverage [puppet_litmus](https://github.com/puppetlabs/puppet_litmus).\nTo run the acceptance tests follow the instructions [here](https://github.com/puppetlabs/puppet_litmus/wiki/Tutorial:-use-Litmus-to-execute-acceptance-tests-with-a-sample-module-(MoTD)#install-the-necessary-gems-for-the-module).\nYou can also find a tutorial and walkthrough of using Litmus and the PDK on [YouTube](https://www.youtube.com/watch?v=FYfR7ZEGHoE).\n\nIf you run into an issue with this module, or if you would like to request a feature, please [file a ticket](https://github.com/puppetlabs/puppetlabs-haproxy/issues).\nEvery Monday the Puppet IA Content Team has [office hours](https://puppet.com/community/office-hours) in the [Puppet Community Slack](http://slack.puppet.com/), alternating between an EMEA friendly time (1300 UTC) and an Americas friendly time (0900 Pacific, 1700 UTC).\n\nIf you have problems getting this module up and running, please [contact Support](http://puppetlabs.com/services/customer-support).\n\nIf you submit a change to this module, be sure to regenerate the reference documentation as follows:\n\n```bash\npuppet strings generate --format markdown --out REFERENCE.md\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuppetlabs%2Fpuppetlabs-haproxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpuppetlabs%2Fpuppetlabs-haproxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuppetlabs%2Fpuppetlabs-haproxy/lists"}