A resource-driven cookbook for configuring HAProxy.
Cookbook builds on 2 core resources:
haproxy_instance: the "parent" resource, which maps to a complete configuration and (probably) a running haproxy daemonhaproxy_proxy: the "core" proxy resource, which maps to a specific proxy
Additional resources haproxy_peers, haproxy_userlist, haproxy_frontend,
haproxy_backend, haproxy_defaults, and haproxy_listen extend the haproxy_proxy
resource with additional validation for common configuration keywords for their respective
proxy types.
Suggested background reading:
- The Fine Manual
- This README, the modules in
libraries/00_helpers.rb, and the individual resources/providers - the test target and example wrapper cookbook 'test/fixtures/cookbooks/my-lb'
Configures a default instance, 'haproxy_instance[haproxy]', and corresponding
'haproxy' service via the config, tuning, and proxies cookbook attributes
(which are mapped onto the corresponding resource attributes).
This recipe also provides a useful example of using the provided helper,
Haproxy::Helpers#proxy, to map a list of proxies to their corresponding
resources in the resource collection. It also illustrates the recommended
pattern of proxying service reloads through a validating execute resource.
See wrapper cookbook example at 'test/fixtures/cookbooks/my-lb'.
Installs haproxy via the node['haproxy']['install_method'] method.
Supports 'package', 'source', and 'ppa'.
Configures a default-named ("haproxy") service resource.
Useful for typical installs running a single haproxy daemon under the default 'haproxy' service name. Service providers, or those running multiple haproxy daemons on a single host will most likely want to configure a service instance per haproxy_instance.
| Attribute | Description | Default Value |
|---|---|---|
| install_method | One of: 'package', 'source', 'ppa' | package |
| proxies | Array of proxy names for the default haproxy_instance[haproxy]. Useful when used in conjunction with a wrapper cookbook that includes the default recipe. | [] |
| config | Array of global configuration keywords passed to the `config` attribute of the haproxy_instance[haproxy] resource in the default recipe. | See `attributes/default.rb` |
| tuning | Array of global configuration keywords passed to the `tuning` attribute of the haproxy_instance[haproxy] resource in the default recipe. | See `attributes/default.rb` |
The "parent" resource. Maps 1-to-1 with a generated haproxy config file, and most likely to a running service.
| Attribute | Description | Default Value |
|---|---|---|
| config | Array of global keywords relevant to process management. See `libraries/00_helpers.rb` or haproxy manual for permissible keywords. | ['daemon'] |
| tuning | Array of global keywords relevant to performance tuning. See `libraries/00_helpers.rb` or haproxy manual for permissible keywords. | ['maxconn 256'] |
| debug | Global keyword string relevant to debugging (either 'debug', or 'quiet'). | app |
| proxies | Array of Chef::Resource::HaproxyProxy instances (`haproxy_{peers,userlist,defaults,frontend,backend,listen}` included). See the `default` recipe for an example of using the provided `Haproxy::Helpers#proxy` method to generate this list from the resource_collection. | [] |
The simplest proxy representation and base class for the other proxy resources (peers, userlist, defaults, frontend, backend, listen).
| Attribute | Description | Default Value |
|---|---|---|
| type | String representing the proxy type. One of: defaults, frontend, backend, listen, peers, userlist. | nil |
| config | Array of proxy keywords, validated against specified proxy type. See `libraries/00_helpers.rb` or haproxy manual for permissible keywords. | [] |
Maps to a peers block in haproxy configuration. Not actually a proxy, but treating it like one is useful for code reusability. Don't judge me.
| Attribute | Description | Default Value |
|---|---|---|
| peers | Array of Hashes. Hashes require keys 'name', 'config'. | [] |
| config | Array of peers keywords, validated against valid peers keywords. See `libraries/00_helpers.rb` or haproxy manual for permissible keywords. | [] |
Maps to a userlist block in haproxy configuration. Also not actually a proxy, as such.
| Attribute | Description | Default Value |
|---|---|---|
| groups | Array of Hashes. Hashes require keys 'name', 'config. | [] |
| users | Array of Hashes. Hashes require keys 'name', 'config'. | [] |
| config | Array of userlist keywords, validated against valid userlist keywords. See `libraries/00_helpers.rb` or haproxy manual for permissible keywords. | [] |
Maps to a 'defaults' block in haproxy configuration. Convention suggests that resource names be capitalized (e.g. haproxy_defaults[HTTP]).
| Attribute | Description | Default Value |
|---|---|---|
| mode | String specifying listener mode. One of: http, tcp, health. | nil |
| default_backend | String specifying argument to `default_backend` keyword. | nil |
| balance | String specifying the desired load-balancing algorithm. See `BALANCE_ALGORITHMS` in libraries/00_helpers.rb or haproxy manual for permissible `balance` keyword arguments. | nil |
| source | `String` specifying arguments to the 'source' keyword. | nil |
| config | Array of proxy keywords, validated against 'defaults' proxy type. See `libraries/00_helpers.rb` or haproxy manual for permissible keywords. | [] |
Maps to a frontend block in the instance configuration, and typically to one or more listening ports or sockets.
| Attribute | Description | Default Value |
|---|---|---|
| mode | String specifying listener mode. One of: http, tcp, health. | nil |
| acls | Array of hashes. Each hash must contain keys `name`, and `criterion`. | [] |
| description | A `String` describing the related proxy. | nil |
| bind | `String` or `Array` of strings containing arguments to `bind` keyword. | nil |
| default_backend | String specifying argument to `default_backend` keyword. | nil |
| use_backends | Array of Hashes mapping to a list of `use_backend` directives. Each hash is verified to have keys `backend` and `condition`. | [] |
| config | Array of proxy keywords, validated against 'frontend' proxy type. See `libraries/00_helpers.rb` or haproxy manual for permissible keywords. | [] |
Maps to a backend configuration block in haproxy configuration.
| Attribute | Description | Default Value |
|---|---|---|
| mode | String specifying proxy mode. One of: http, tcp, health. | nil |
| acls | Array of hashes. Each hash must contain keys `name`, and `criterion`. | [] |
| description | A `String` describing the related proxy. | nil |
| balance | String specifying the desired load-balancing algorithm. See `BALANCE_ALGORITHMS` in libraries/00_helpers.rb or haproxy manual for permissible `balance` keyword arguments. | nil |
| source | `String` specifying arguments to the 'source' keyword. | nil |
| servers | Array of `Hashes`. Each `Hash` must contain keys `name`, `address`, `port`, and optionally `config`. | [] |
| config | Array of proxy keywords, validated against 'backend' proxy type. See `libraries/00_helpers.rb` or haproxy manual for permissible keywords. | [] |
Maps to a listen configuration block, combines frontend and backend config blocks into a single proxy. Less flexible, but more concise. Typically used for tcp-mode proxies with a 1:1 frontend:backend mapping.
| Attribute | Description | Default Value |
|---|---|---|
| mode | String specifying proxy mode. One of: http, tcp, health. | nil |
| acls | Array of hashes. Each hash must contain keys `name`, and `criterion`. | [] |
| description | A `String` describing the related proxy. | nil |
| balance | String specifying the desired load-balancing algorithm. See `BALANCE_ALGORITHMS` in libraries/00_helpers.rb or haproxy manual for permissible `balance` keyword arguments. | nil |
| source | `String` specifying arguments to the 'source' keyword. | nil |
| servers | Array of `Hashes`. Each `Hash` must contain keys `name`, `address`, `port`, and optionally `config`. | [] |
| bind | `String` or `Array` of strings containing arguments to `bind` keyword. | nil |
| default_backend | String specifying argument to `default_backend` keyword. | nil |
| use_backends | Array of `Hash`es mapping to a list of `use_backend` directives. Each hash is verified to have keys `backend` and `condition`. | [] |
| config | Array of proxy keywords, validated against 'backend' proxy type. See `libraries/00_helpers.rb` or haproxy manual for permissible keywords. | [] |