diff --git a/README.md b/README.md index adbcbd1c..b182c5e4 100644 --- a/README.md +++ b/README.md @@ -490,504 +490,7 @@ haproxy::frontend { 'ft_allapps': ## Reference -### Classes - -#### Public classes - -* [`haproxy`](#class-haproxy): Main configuration class. -* [`haproxy::globals`](#class-haproxy-globals): Global configuration options. - -#### 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`](#define-haproxylisten): Creates a listen entry in haproxy.cfg. -* [`haproxy::frontend`](#define-haproxyfrontend): Creates a frontend entry in haproxy.cfg. -* [`haproxy::backend`](#define-haproxybackend): Creates a backend entry in haproxy.cfg. -* [`haproxy::balancermember`](#define-haproxybalancermember): Creates server entries for listen or backend blocks in haproxy.cfg. -* [`haproxy::userlist`](#define-haproxyuserlist): Creates a userlist entry in haproxy.cfg. -* [`haproxy::peers`](#define-haproxypeers): Creates a peers entry in haproxy.cfg. -* [`haproxy::peer`](#define-haproxypeer): Creates server entries within a peers entry in haproxy.cfg. -* [`haproxy::mailers`](#define-haproxymailers): Creates a mailers entry in haproxy.cfg. -* [`haproxy::mailer`](#define-haproxymailer): Creates server entries within a mailers entry in haproxy.cfg. -* [`haproxy::instance`](#define-instance): Creates multiple instances of haproxy on the same machine. -* [`haproxy::instance_service`](#define-instanceservice): Example of one way to prepare environment for haproxy::instance. -* [`haproxy::mapfile`](#define-haproxymapfile): Manages an HAProxy [map file](https://cbonte.github.io/haproxy-dconv/configuration-1.5.html#7.3.1-map). -* [`haproxy::defaults`](#define-defaults): Option to use multipe defaults sections. - -#### Private defines - -* `haproxy::balancermember::collect_exported`: Collects exported balancermembers. -* `haproxy::peer::collect_exported`: Collects exported peers. -* `haproxy::mailer::collect_exported`: Collects exported mailers. - -#### Class: `haproxy` - -Main class, includes all other classes. - -##### Parameters (all optional) - -* `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 of `option => 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: - - ```puppet - { - '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 set `defaults_options` to a hash of the `option => 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 to `undef`. Example: - - ```puppet - { - '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 of `option => 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: - - ```puppet - { - '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 set `global_options` to a hash of the `option => 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 to `undef`. Example: - - ```puppet - { - '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-supplied `global_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 to `false`, but will default to `true` in future releases. - -* `package_ensure`: Ensure the package is present (installed), absent or a specific version. 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 the `restart` parameter to Puppet's native [`service` resource](https://docs.puppetlabs.com/references/latest/type.html#service). Valid options: a string. Default: undef (if not specified, Puppet uses the `service` 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_name`: Specifies the name of the HAProxy service. Valid options: a string. Default: 'haproxy'. - -* `service_options`: Contents for the `/etc/defaults/haproxy` file on Debian. Defaults to "ENABLED=1\n" on Debian, and is ignored on other systems. - -* `sysconfig_options`: Contents for the `/etc/sysconfig/haproxy` file on RedHat(-based) systems. Defaults to OPTIONS="" on RedHat(-based) systems and is ignored on others - -* `config_dir`: Path to the directory in which the main configuration file `haproxy.cfg` resides. Will also be used for storing any managed map files (see [`haproxy::mapfile`](#define-haproxymapfile). Default depends on platform. - -#### Class: `haproxy::globals` - -For global configuration options used by all haproxy instances. - -##### Parameters (all optional) - -* `sort_options_alphabetic`: Sort options either alphabetic or custom like haproxy internal sorts them. Defaults to true. - -#### Define: `haproxy::balancermember` - -Configures a service inside a listening or backend service configuration block in haproxy.cfg. - -##### Parameters - -* `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 the `server_names` parameter. For each pair of entries in the `ipaddresses` and `server_names` arrays, Puppet creates server entries in haproxy.cfg targeting each port specified in the `ports` parameter. Default: the value of the `$::ipaddress` fact. - -* `listening_service`: *Required.* Associates the balancermember with an `haproxy::listen` resource. Valid options: a string matching the title of a declared `haproxy::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 unless `collect_exported` is set to `true`.* 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 the `ipaddresses` parameter. For each pair of entries in the `ipaddresses` and `server_names` arrays, Puppet creates server entries in haproxy.cfg targeting each port specified in the `ports` parameter. Default: the value of the `$::hostname` fact. - -* `instance`: *Optional.* When using `haproxy::instance` to run multiple instances of Haproxy on the same machine, this indicates which instance. Defaults to "haproxy". - -* `defaults`: *Optional.* Name of the defaults section the backend or listener use. Defaults to undef. - -* `config_file`: *Optional.* Path of the config file where this entry will be added. Assumes that the parent directory exists. Defaults to `haproxy::params::config_file`. - -* `verifyhost`: *Optional.* Will add the verifyhost option to the server line, using the specific host from server_names as an argument. Defaults to false - -* `weight`: *Optional.* Will add the weight option to the server line. Defaults to undef - -#### Define: `haproxy::backend` - -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](#define-haproxybalancermember)). - -##### Parameters - -* `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 the `haproxy::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: - -* `config_file`: *Optional.* Path of the config file where this entry will be added. Assumes that the parent directory exists. Defaults to `haproxy::params::config_file`. - - ```puppet - { - - 'option' => [ - 'tcplog', - 'ssl-hello-chk' - ], - 'balance' => 'roundrobin' - } - ``` - -* `instance`: *Optional.* When using `haproxy::instance` to run multiple instances of Haproxy on the same machine, this indicates which instance. Defaults to "haproxy". - -* `sort_options_alphabetic`: Sort options either alphabetic or custom like haproxy internal sorts them. Defaults to `haproxy::globals::sort_options_alphabetic`. - -* `defaults`: *Optional* Name of the defaults section this backend will use. Defaults to undef which means the global defaults section will be used. - -#### Define: `haproxy::frontend` - -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](#define-haproxybalancermember)). - -##### Parameters - -* `bind`: *Required unless `ports` and `ipaddress` 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: - - ```puppet - 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](http://cbonte.github.io/haproxy-dconv/configuration-1.5.html#4.2-bind). - -* `bind_options`: Deprecated. This setting has never functioned in any version of the haproxy module. Use `bind` instead. - -* `ipaddress`: *Required unless `bind` 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. - - ```puppet - { - 'option' => [ - 'tcplog', - ], - } - ``` - -* `ports`: *Required unless `bind` is specified.* Specifies which ports to listen on for the address specified in `ipaddress`. 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 using `haproxy::instance` to run multiple instances of Haproxy on the same machine, this indicates which instance. Defaults to "haproxy". - -* `sort_options_alphabetic`: Sort options either alphabetic or custom like haproxy internal sorts them. Defaults to `haproxy::globals::sort_options_alphabetic`. - -* `defaults`: *Optional* Name of the defaults section this frontend will use. Defaults to undef which means the global defaults section will be used. - -* `defaults_use_backend`: If defaults are used and a default backend is configured use the backend name for ordering. This means that the frontend is placed in the configuration file before the backend configuration. Defaults to true. - -* `config_file`: *Optional.* Path of the config file where this entry will be added. Assumes that the parent directory exists. Defaults to `haproxy::params::config_file`. - -#### Define: `haproxy::listen` - -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](#define-haproxybalancermember)). - -##### Parameters - -* `bind`: *Required unless `ports` and `ipaddress` 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: - - ```puppet - 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](http://cbonte.github.io/haproxy-dconv/configuration-1.5.html#4.2-bind). - -* `bind_options`: Deprecated. This setting has never functioned in any version of the haproxy module. Use `bind` 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 the `haproxy::balancermembers` define. Default: 'true'. - -* `ipaddress`: *Required unless `bind` 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 unless `bind` is specified.* Specifies which ports to listen on for the address specified in `ipaddress`. 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). - -* `sort_options_alphabetic`: Sort options either alphabetic or custom like haproxy internal sorts them. Defaults to `haproxy::globals::sort_options_alphabetic`. - -* `defaults`: *Optional* Name of the defaults section this listen section will use. Defaults to undef which means the global defaults section will be used. - -* `config_file`: *Optional.* Path of the config file where this entry will be added. Assumes that the parent directory exists. Defaults to `haproxy::params::config_file`. - -#### Define: `haproxy::userlist` - -Sets up a [userlist configuration block](http://cbonte.github.io/haproxy-dconv/configuration-1.4.html#3.4) inside haproxy.cfg. - -##### Parameters - -* `groups`: *Required unless `users` is specified.* Adds groups to the userlist. For more information, see the [HAProxy Configuration Manual](http://cbonte.github.io/haproxy-dconv/configuration-1.4.html#3.4-group). 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 unless `groups` is specified.* Adds users to the userlist. For more information, see the [HAProxy Configuration Manual](http://cbonte.github.io/haproxy-dconv/configuration-1.4.html#3.4-user). Valid options: an array of usernames. Default: undef. - -* `instance`: *Optional.* When using `haproxy::instance` to run multiple instances of Haproxy on the same machine, this indicates which instance. Defaults to "haproxy". - -* `config_file`: *Optional.* Path of the config file where this entry will be added. Assumes that the parent directory exists. Defaults to `haproxy::params::config_file`. - -#### Define: `haproxy::peers` - -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. - -##### Parameters - -* `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 using `haproxy::instance` to run multiple instances of Haproxy on the same machine, this indicates which instance. Defaults to "haproxy". - -* `config_file`: *Optional.* Path of the config file where this entry will be added. Assumes that the parent directory exists. Defaults to `haproxy::params::config_file`. - -#### Define: `haproxy::peer` - -Sets up a peer entry inside the peers configuration block in haproxy.cfg. - -##### Parameters - -* `ipaddresses`: *Required unless the `collect_exported` parameter of your `haproxy::peers` resource is set to `true`.* 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 the `server_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 the `collect_exported` parameter of your `haproxy::peers` resource is set to `true`.* 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 to `ipaddresses`. 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 using `haproxy::instance` to run multiple instances of Haproxy on the same machine, this indicates which instance. Defaults to "haproxy". - -#### Define: `haproxy::mailers` - -Sets up a mailers entry in haproxy.cfg on the load balancer to send email to each mailer that is configured in a mailers section alerts when the state of servers changes. - -##### Parameters - -* `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 mailers entry in haproxy.cfg. Valid options: a string. Default: the title of your declared resource. - -* `instance`: *Optional.* When using `haproxy::instance` to run multiple instances of Haproxy on the same machine, this indicates which instance. Defaults to "haproxy". - -#### Define: `haproxy::mailer` - -Sets up a mailer entry inside the mailers configuration block in haproxy.cfg. - -##### Parameters -* `ipaddresses`: *Required unless the `collect_exported` parameter of your `haproxy::mailers` resource is set to `true`.* Specifies the IP address used to contact the mailer email 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 the `server_names` parameter. Puppet pairs up the elements from both arrays and creates a mailer for each pair of values. Default: the value of the `$::ipaddress` fact. - -* `mailers_name`: *Required.* Specifies the name of a valid `haproxy::mailers` resource. Valid options: a string containing the name of an HAProxy mailer. - -* `port`: *Required.* Specifies the port to which the load balancer makes its smtp connection. Valid options: a string containing a port number. - -* `server_names`: *Required unless the `collect_exported` parameter of your `haproxy::mailers` resource is set to `true`.* Sets the name of the email server as listed in the mailers 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 to `ipaddresses`. Puppet pairs up the elements from both arrays and creates a mailer for each pair of values. Default: the value of the `$::hostname` fact. - -* `instance`: *Optional.* When using `haproxy::instance` to run multiple instances of Haproxy on the same machine, this indicates which instance. Defaults to "haproxy". - -* `config_file`: *Optional.* Path of the config file where this entry will be added. Assumes that the parent directory exists. Defaults to `haproxy::params::config_file`. - -#### Define: `haproxy::instance` - -Runs multiple instances of haproxy on the same machine. Normally users -use the Class['haproxy'], which runs a single haproxy daemon on a machine. - -##### Parameters - -* `package_ensure`: Ensure the package is present (installed), absent or a -specific version. 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 - -* `service_name`: -The service name for haproxy. Defaults to undef. If no name is given then -the value computed for $instance_name will be used. -NOTE: Class['haproxy'] has a different default. - -* `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. - -#### Define: `haproxy::instance_service` - -Example manifest that shows one way to create the Service[] environment needed -by haproxy::instance. - -##### Parameters - -* `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. - -#### Define: `haproxy::mapfile` - -Manages an HAProxy [map file](https://cbonte.github.io/haproxy-dconv/configuration-1.5.html#7.3.1-map). 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/ - -##### Parameters - -* `namevar`: The namevar of the defined resource type is the filename of the map file (without any extension), relative to the `haproxy::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: - - ```puppet - 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' ]` - -#### Define: `haproxy::defaults` - -This type will setup a additional defaults configuration block inside the haproxy.cfg file on an haproxy load balancer. A new default configuration block resets all defaults of prior defaults configuration blocks. [Further documentation](https://cbonte.github.io/haproxy-dconv/configuration-1.5.html#4) of what options are allowed in defaults sections. Listener, Backends, Frontends and Balancermember can be configured behind a default configuration block by setting the defaults parameter to the corresponding defaults name. - -##### Parameters (all optional) - -* `options`: A hash or array of hashes of options that are inserted into the defaults configuration block. - -* `sort_options_alphabetic`: Sort options either alphabetic or custom like haproxy internal sorts them. Defaults to true. - -* `instance`: When using `haproxy::instance` to run multiple instances of Haproxy on the same machine, this indicates which instance. Defaults to "haproxy". +For information on the classes and types, see the [REFERENCE.md](https://github.com/puppetlabs/puppetlabs-haproxy/blob/master/REFERENCE.md) ## Limitations diff --git a/REFERENCE.md b/REFERENCE.md new file mode 100644 index 00000000..82f2eb50 --- /dev/null +++ b/REFERENCE.md @@ -0,0 +1,1739 @@ +# Reference + + +## Table of Contents + +**Classes** + +* [`haproxy`](#haproxy): A Puppet module, using storeconfigs, to model an haproxy configuration. Currently VERY limited - assumes Redhat/CentOS setup. Pull requests a +* [`haproxy::globals`](#haproxyglobals): For global configuration options used by all haproxy instances. +* [`haproxy::params`](#haproxyparams): This is a container class holding default parameters for for haproxy class. + +**Defined types** + +_Public Defined types_ + +* [`haproxy::backend`](#haproxybackend): This type will setup a backend service configuration block inside the +haproxy.cfg file on an haproxy load balancer. +* [`haproxy::balancermember`](#haproxybalancermember): This type will setup a balancer member inside a listening service +configuration block in /etc/haproxy/haproxy.cfg on the load balancer. +* [`haproxy::defaults`](#haproxydefaults): This type will setup a additional defaults configuration block inside the +haproxy.cfg file on an haproxy load balancer. +* [`haproxy::frontend`](#haproxyfrontend): This type will setup a frontend service configuration block inside +the haproxy.cfg file on an haproxy load balancer. +* [`haproxy::instance`](#haproxyinstance): Manages haproxy permitting multiple instances to run on the same machine. +* [`haproxy::instance_service`](#haproxyinstance_service): Set up the environment for an haproxy service. +* [`haproxy::listen`](#haproxylisten): This type will setup a listening service configuration block inside +the haproxy.cfg file on an haproxy load balancer. +* [`haproxy::mailer`](#haproxymailer): This type will set up a mailer entry inside the mailers configuration block in +haproxy.cfg on the load balancer. +* [`haproxy::mailers`](#haproxymailers): This type will set up a mailers entry in haproxy.cfg on the load balancer. +* [`haproxy::mapfile`](#haproxymapfile): Manage an HAProxy map file as documented in +https://cbonte.github.io/haproxy-dconv/configuration-1.5.html#7.3.1-map +* [`haproxy::peer`](#haproxypeer): This type will set up a peer entry inside the peers configuration block in haproxy.cfg on the load balancer. +* [`haproxy::peer::collect_exported`](#haproxypeercollect_exported): Private define +* [`haproxy::peers`](#haproxypeers): This type will set up a peers entry in haproxy.cfg +* [`haproxy::resolver`](#haproxyresolver): This type will setup resolvers configuration block inside +the haproxy.cfg file on an haproxy load balancer. +* [`haproxy::userlist`](#haproxyuserlist): This type will set up a userlist configuration block inside the haproxy.cfg +file on an haproxy load balancer. + +_Private Defined types_ + +* `haproxy::balancermember::collect_exported`: +* `haproxy::config`: HAProxy configuration +* `haproxy::install`: Install haproxy +* `haproxy::mailer::collect_exported`: +* `haproxy::service`: HAProxy service + +## Classes + +### haproxy + +A Puppet module, using storeconfigs, to model an haproxy configuration. +Currently VERY limited - assumes Redhat/CentOS setup. Pull requests accepted! + +Currently requires the puppetlabs/concat module on the Puppet Forge and + uses storeconfigs on the Puppet Master to export/collect resources + from all balancer members. + +#### Examples + +##### + +```puppet +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' + }, +} +``` + +#### Parameters + +The following parameters are available in the `haproxy` class. + +##### `package_ensure` + +Data type: `String[1]` + +Ensure the package is present (installed), absent or a specific version. +Defaults to 'present' + +Default value: 'present' + +##### `package_name` + +Data type: `String` + +The package name of haproxy. Defaults to 'haproxy' +NOTE: haproxy::instance has a different default. + +Default value: $haproxy::params::package_name + +##### `service_ensure` + +Data type: `Variant[Enum['running', 'stopped'], Boolean]` + +Chooses whether the haproxy service should be running & enabled at boot, or +stopped and disabled at boot. Defaults to 'running' + +Default value: 'running' + +##### `service_manage` + +Data type: `Boolean` + +Chooses whether the haproxy service state should be managed by puppet at +all. Defaults to true + +Default value: `true` + +##### `service_name` + +Data type: `String` + +The service name for haproxy. Defaults to 'haproxy' +NOTE: haproxy::instance has a different default. + +Default value: $haproxy::params::service_name + +##### `service_options` + +Data type: `String` + +Contents for the `/etc/defaults/haproxy` file on Debian. Defaults to "ENABLED=1\n" on Debian, and is ignored on other systems. + +Default value: $haproxy::params::service_options + +##### `sysconfig_options` + +Data type: `Any` + +Contents for the `/etc/sysconfig/haproxy` file on RedHat(-based) systems. +Defaults to OPTIONS="" on RedHat(-based) systems and is ignored on others + +Default value: $haproxy::params::sysconfig_options + +##### `global_options` + +Data type: `Hash` + +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. + +Default value: $haproxy::params::global_options + +##### `defaults_options` + +Data type: `Hash` + +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. + +Default value: $haproxy::params::defaults_options + +##### `merge_options` + +Data type: `Boolean` + +Whether to merge the user-supplied `global_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 to +false, but will default to true in future releases. + +Default value: $haproxy::params::merge_options + +##### `restart_command` + +Data type: `Any` + +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. + +Default value: `undef` + +##### `custom_fragment` + +Data type: `Any` + +Allows arbitrary HAProxy configuration to be passed through to support +additional configuration not available via parameters, or to short-circute +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 + +Default value: `undef` + +##### `config_dir` + +Data type: `Stdlib::Absolutepath` + +Path to the directory in which the main configuration file `haproxy.cfg` +resides. Will also be used for storing any managed map files (see +`haproxy::mapfile`). Default depends on platform. + +Default value: $haproxy::params::config_dir + +##### `config_file` + +Data type: `Optional[Stdlib::Absolutepath]` + +Optional. Path to the haproxy config file. +Default depends on platform. + +Default value: $haproxy::params::config_file + +##### `config_validate_cmd` + +Data type: `Any` + +Optional. Command used by concat validate_cmd to validate new +config file concat is a valid haproxy config. +Default /usr/sbin/haproxy -f % -c + +Default value: $haproxy::params::config_validate_cmd + +##### `manage_config_dir` + +Data type: `Any` + +Optional. + +Default value: $haproxy::params::manage_config_dir + +##### `manage_service` + +Data type: `Any` + +Deprecated + +Default value: `undef` + +##### `enable` + +Data type: `Any` + +Deprecated + +Default value: `undef` + +### haproxy::globals + +For global configuration options used by all haproxy instances. + +#### Parameters + +The following parameters are available in the `haproxy::globals` class. + +##### `sort_options_alphabetic` + +Data type: `Boolean` + +Sort options either alphabetic or custom like haproxy internal sorts them. +Defaults to true. + +Default value: `true` + +### haproxy::params + +This is a container class holding default parameters for for haproxy class. + +* **Note** Currently, only the Redhat family is supported, but this can be easily +extended by changing package names and configuration file paths. + +## Defined types + +### haproxy::backend + +=== Authors + +Gary Larizza +Jeremy Kitchen + +* **Note** Each backend service needs one +or more backend member servers (that can be declared with the +haproxy::balancermember defined resource type). Using storeconfigs, you can +export the haproxy::balancermember resources on all load balancer member +servers and then collect them on a single haproxy load balancer server. + +#### Examples + +##### + +```puppet +haproxy::backend { 'puppet00': + options => { + 'option' => [ + 'tcplog', + 'ssl-hello-chk' + ], + 'balance' => 'roundrobin' + }, +} +``` + +#### Parameters + +The following parameters are available in the `haproxy::backend` defined type. + +##### `section_name` + +Data type: `Any` + +This name goes right after the 'backend' statement in haproxy.cfg +Default: $name (the namevar of the resource). + +Default value: $name + +##### `mode` + +Data type: `Any` + +The mode of operation for the backend service. Valid values are undef, + 'tcp', 'http', and 'health'. + +Default value: `undef` + +##### `options` + +Data type: `Any` + +A hash of options that are inserted into the backend configuration block. + +Default value: { + 'option' => [ + 'tcplog', + ], + 'balance' => 'roundrobin', + } + +##### `collect_exported` + +Data type: `Any` + +Boolean, default 'true'. True means 'collect exported @@balancermember + resources' (for the case when every balancermember node exports itself), + false means 'rely on the existing declared balancermember resources' (for + the case when you know the full set of balancermember in advance and use + haproxy::balancermember with array arguments, which allows you to deploy + everything in 1 run) + +Default value: `true` + +##### `config_file` + +Data type: `Optional[Stdlib::Absolutepath]` + +Optional. Path of the config file where this entry will be added. +Assumes that the parent directory exists. +Default: $haproxy::params::config_file + +Default value: `undef` + +##### `sort_options_alphabetic` + +Data type: `Any` + +Sort options either alphabetic or custom like haproxy internal sorts them. +Defaults to true. + +Default value: `undef` + +##### `defaults` + +Data type: `Any` + +Name of the defaults section this backend will use. +Defaults to undef which means the global defaults section will be used. + +Default value: `undef` + +##### `instance` + +Data type: `Any` + +Optional. Defaults to 'haproxy' + +Default value: 'haproxy' + +### haproxy::balancermember + +This type will setup a balancer member inside a listening service +configuration block in /etc/haproxy/haproxy.cfg on the load balancer. + +* **Note** Currently it only has the ability to specify the instance name, +ip address, port, and whether or not it is a backup. More features +can be added as needed. The best way to implement this is to export +this resource for all haproxy balancer member servers, and then collect +them on the main haproxy load balancer. + +#### Examples + +##### + +```puppet +Exporting the resource for a balancer member: + +@@haproxy::balancermember { 'haproxy': + listening_service => 'puppet00', + ports => '8140', + server_names => $::hostname, + ipaddresses => $::ipaddress, + options => 'check', +} + +Collecting the resource on a load balancer + +Haproxy::Balancermember <<| listening_service == 'puppet00' |>> +``` + +##### + +```puppet +Creating the resource for multiple balancer members at once +(for single-pass installation of haproxy without requiring a first +pass to export the resources if 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', +} +``` + +##### + +```puppet +Implemented in HAPROXY 1.8: +Set a template to initialize servers with shared parameters. +The names of these servers are built from and parameters. + + Initializes 5 servers with srv1, srv2, srv3, srv4 and srv5 as names, + myserver.example.com as FQDN, 8140 as port, and health-check enabled. + +haproxy::balancermember { 'haproxy': + listening_service => 'puppet00', + type => 'server-template' + port => '8140', + prefix => 'srv', + amount => '1-5', + fqdn => 'myserver.example.com', + options => 'check', +} + +(this resource can be declared anywhere) +``` + +#### Parameters + +The following parameters are available in the `haproxy::balancermember` defined type. + +##### `listening_service` + +Data type: `Any` + +The haproxy service's instance name (or, the title of the + haproxy::listen resource). This must match up with a declared + haproxy::listen resource. + +##### `ports` + +Data type: `Any` + +An array or commas-separated list of ports for which the balancer member + will accept connections from the load balancer. Note that cookie values + aren't yet supported, but shouldn't be difficult to add to the + configuration. If you use an array in server_names and ipaddresses, the + same port is used for all balancermembers. + +Default value: `undef` + +##### `port` + +Data type: `Any` + +A port for server-template. It is an optional specification. + +Default value: `undef` + +##### `server_names` + +Data type: `Any` + +The name of the balancer member server as known to haproxy in the + listening service's configuration block. This defaults to the + hostname. Can be an array of the same length as ipaddresses, + in which case a balancermember is created for each pair of + server_names and ipaddresses (in lockstep). + +Default value: $::hostname + +##### `ipaddresses` + +Data type: `Any` + +The ip address used to contact the balancer member server. + Can be an array, see documentation to server_names. + +Default value: $::ipaddress + +##### `prefix` + +Data type: `Any` + +A prefix for the server-template for the server names to be built. + +Default value: 'server' + +##### `amount` + +Data type: `Any` + +If "amount" is provided, the server-template initializes servers + with 1 up to as server name suffixes. A range of numbers + - may also be used to use up to + as server name suffixes. + +Default value: '1' + +##### `fqdn` + +Data type: `Any` + +A FQDN for all the servers the server-template initializes. + +Default value: '' + +##### `options` + +Data type: `Any` + +An array of options to be specified after the server declaration + in the listening service's configuration block. + +Default value: '' + +##### `define_cookies` + +Data type: `Any` + +If true, then add "cookie SERVERID" stickiness options. + Default false. + +Default value: `false` + +##### `defaults` + +Data type: `Any` + +Name of the defaults section the backend or listener use. +Defaults to undef. + +Default value: `undef` + +##### `config_file` + +Data type: `Optional[Stdlib::Absolutepath]` + +Optional. Path of the config file where this entry will be added. +Assumes that the parent directory exists. +Default: $haproxy::params::config_file + +Default value: `undef` + +##### `verifyhost` + +Data type: `Any` + +Optional. Will add the verifyhost option to the server line, using the +specific host from server_names as an argument. +Default: false + +Default value: `false` + +##### `weight` + +Data type: `Any` + +Optional. Will add the weight option to the server line +Default: undef + +Default value: `undef` + +##### `instance` + +Data type: `Any` + +Optional. Defaults to 'haproxy' + +Default value: 'haproxy' + +##### `type` + +Data type: `Any` + +Optional. Defaults to 'server' + +Default value: 'server' + +### haproxy::defaults + +This type will setup a additional defaults configuration block inside the +haproxy.cfg file on an haproxy load balancer. + +* **Note** A new default configuration block resets all defaults of prior defaults configuration blocks. +Listener, Backends, Frontends and Balancermember can be configured behind a default +configuration block by setting the defaults parameter to the corresponding +defaults name. + +#### Parameters + +The following parameters are available in the `haproxy::defaults` defined type. + +##### `options` + +Data type: `Any` + +A hash of options that are inserted into the defaults configuration block. + +Default value: {} + +##### `sort_options_alphabetic` + +Data type: `Any` + +Sort options either alphabetic or custom like haproxy internal sorts them. +Defaults to true. + +Default value: `undef` + +##### `instance` + +Data type: `Any` + +Optional. Defaults to 'haproxy'. + +Default value: 'haproxy' + +### haproxy::frontend + +=== Authors + +Gary Larizza + +* **Note** Currently requires the puppetlabs/concat module on the Puppet Forge and +uses storeconfigs on the Puppet Master to export/collect resources +from all balancer members. + +#### Examples + +##### + +```puppet +Exporting the resource for a balancer member: + +haproxy::frontend { 'puppet00': + ipaddress => $::ipaddress, + ports => '18140', + mode => 'tcp', + bind_options => 'accept-proxy', + options => { + 'option' => [ + 'tcplog', + 'accept-invalid-http-request', + ], + 'timeout client' => '30s', + 'balance' => 'roundrobin' + }, +} +``` + +#### Parameters + +The following parameters are available in the `haproxy::frontend` defined type. + +##### `section_name` + +Data type: `Any` + +This name goes right after the 'frontend' statement in haproxy.cfg +Default: $name (the namevar of the resource). + +Default value: $name + +##### `ports` + +Data type: `Any` + +Ports on which the proxy will listen for connections on the ip address + specified in the ipaddress parameter. Accepts either a single + comma-separated string or an array of strings which may be ports or + hyphenated port ranges. + +Default value: `undef` + +##### `bind` + +Data type: `Optional[Hash]` + +Set of ip addresses, port and bind options +$bind = { '10.0.0.1:80' => ['ssl', 'crt', '/path/to/my/crt.pem'] } + +Default value: `undef` + +##### `ipaddress` + +Data type: `Any` + +The ip address the proxy binds to. + Empty addresses, '*', and '0.0.0.0' mean that the proxy listens + to all valid addresses on the system. + +Default value: `undef` + +##### `mode` + +Data type: `Any` + +The mode of operation for the frontend service. Valid values are undef, + 'tcp', 'http', and 'health'. + +Default value: `undef` + +##### `bind_options` + +Data type: `Any` + +(Deprecated) An array of options to be specified after the bind declaration + in the listening serivce's configuration block. + +Default value: '' + +##### `options` + +Data type: `Any` + +A hash of options that are inserted into the frontend service + configuration block. + +Default value: { + 'option' => [ + 'tcplog', + ], + } + +##### `sort_options_alphabetic` + +Data type: `Any` + +Sort options either alphabetic or custom like haproxy internal sorts them. +Defaults to true. + +Default value: `undef` + +##### `defaults` + +Data type: `Any` + +Name of the defaults section this backend will use. +Defaults to undef which means the global defaults section will be used. + +Default value: `undef` + +##### `defaults_use_backend` + +Data type: `Any` + +If defaults are used and a default backend is configured use the backend +name for ordering. This means that the frontend is placed in the +configuration file before the backend configuration. +Defaults to true. + +Default value: `true` + +##### `config_file` + +Data type: `Optional[Stdlib::Absolutepath]` + +Optional. Path of the config file where this entry will be added. +Assumes that the parent directory exists. +Default: $haproxy::params::config_file + +Default value: `undef` + +##### `collect_exported` + +Data type: `Any` + +Boolean. Default true + +Default value: `true` + +##### `instance` + +Data type: `Any` + +Optional. Defaults to 'haproxy' + +Default value: 'haproxy' + +### haproxy::instance + +template() function). Defaults to undef + +* **Note** Normally users use the Class['haproxy'], which runs a single haproxy +daemon on a machine. + +#### Examples + +##### + +```puppet +A single instance of haproxy with all defaults +i.e. emulate Class['haproxy'] + package{ 'haproxy': ensure => present }->haproxy::instance { 'haproxy': }-> + haproxy::listen { 'puppet00': + instance => 'haproxy', + collect_exported => false, + ipaddress => $::ipaddress, + ports => '8140', + } +``` + +##### + +```puppet +Multiple instances of haproxy: + haproxy::instance { 'group1': } + haproxy::instance_service { 'group1': + haproxy_init_source => "puppet:///modules/${module_name}/haproxy-group1.init", + } + haproxy::listen { 'puppet00': + instance => 'group1', + collect_exported => false, + ipaddress => $::ipaddress, + ports => '8800', + requires => Package['haproxy'], + } + haproxy::instance { 'group2': } + haproxy::instance_service { 'group2': + haproxy_init_source => "puppet:///modules/${module_name}/haproxy-group1.init", + } + haproxy::listen { 'puppet00': + instance => 'group2', + collect_exported => false, + ipaddress => $::ipaddress, + ports => '9900', + requires => Package['haproxy'], + } +``` + +##### + +```puppet +Multiple instances of haproxy, one with a custom haproxy package: + haproxy::instance { 'group1': } + haproxy::instance_service { 'group1': + haproxy_init_source => "puppet:///modules/${module_name}/haproxy-group1.init", + } + haproxy::listen { 'puppet00': + instance => 'group1', + collect_exported => false, + ipaddress => $::ipaddress, + ports => '8800', + requires => Package['haproxy'], + } + haproxy::instance { 'group2': } + haproxy::instance_service { 'group2': + haproxy_package => 'custom_haproxy', + haproxy_init_source => "puppet:///modules/${module_name}/haproxy-group2.init", + } + haproxy::listen { 'puppet00': + instance => 'group2', + collect_exported => false, + ipaddress => $::ipaddress, + ports => '9900', + requires => Package['haproxy'], + } +``` + +#### Parameters + +The following parameters are available in the `haproxy::instance` defined type. + +##### `package_ensure` + +Data type: `String[1]` + +Ensure the package is present (installed), absent or a specific version. +Defaults to 'present' + +Default value: 'present' + +##### `package_name` + +Data type: `Optional[String]` + +The package name of haproxy. Defaults to undef, and no package is installed. +NOTE: Class['haproxy'] has a different default. + +Default value: `undef` + +##### `service_ensure` + +Data type: `Variant[Enum['running', 'stopped'], Boolean]` + +Chooses whether the haproxy service should be running & enabled at boot, or +stopped and disabled at boot. Defaults to 'running' + +Default value: 'running' + +##### `service_manage` + +Data type: `Boolean` + +Chooses whether the haproxy service state should be managed by puppet at +all. Defaults to true + +Default value: `true` + +##### `service_name` + +Data type: `Optional[String]` + +The service name for haproxy. Defaults to undef. If no name is given then +the value computed for $instance_name will be used. +NOTE: Class['haproxy'] has a different default. + +Default value: `undef` + +##### `global_options` + +Data type: `Optional[Hash]` + +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. + +Default value: `undef` + +##### `defaults_options` + +Data type: `Optional[Hash]` + +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. + +Default value: `undef` + +##### `restart_command` + +Data type: `Any` + +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. + +Default value: `undef` + +##### `custom_fragment` + +Data type: `Any` + +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 + +Default value: `undef` + +##### `config_file` + +Data type: `Optional[Stdlib::Absolutepath]` + +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. + +Default value: `undef` + +##### `config_validate_cmd` + +Data type: `Any` + +Command used by concat validate_cmd to validate new +config file concat is a valid haproxy config. +Default /usr/sbin/haproxy -f % -c + +Default value: $haproxy::params::config_validate_cmd + +##### `config_dir` + +Data type: `Any` + +Optional. Default undef. + +Default value: `undef` + +##### `merge_options` + +Data type: `Any` + + + +Default value: $haproxy::params::merge_options + +##### `service_options` + +Data type: `Any` + + + +Default value: $haproxy::params::service_options + +##### `sysconfig_options` + +Data type: `Any` + + + +Default value: $haproxy::params::sysconfig_options + +### haproxy::instance_service + +Set up the environment for an haproxy service. + +* **Note** * Associate an haproxy instance with the haproxy package it should use. +* Create the start/restart/stop functions needed by Service[]. +In other words: sets things up so that Service[$instance_name] will work. + +In particular: +* Create a link to the binary an instance will be using. This + way each instance can link to a different binary. + If you have an instance called "foo", you know "haproxy-foo" + is a link to the binary it should be using. +* Create an init.d file named after the instance. This way + Service[$instance] can start/restart the service. + +#### Parameters + +The following parameters are available in the `haproxy::instance_service` defined type. + +##### `haproxy_package` + +Data type: `String` + +The name of the package to be installed. This is useful if +you package your own custom version of haproxy. +Defaults to 'haproxy' + +Default value: 'haproxy' + +##### `bindir` + +Data type: `Stdlib::Absolutepath` + +Where to put symlinks to the binary used for each instance. +Defaults to '/opt/haproxy' + +Default value: '/opt/haproxy/bin' + +##### `haproxy_init_source` + +Data type: `Optional[String]` + +The init.d script that will start/restart/reload this instance. + +Default value: `undef` + +##### `haproxy_unit_template` + +Data type: `Optional[String]` + + + +Default value: `undef` + +### haproxy::listen + +=== Authors + +Gary Larizza + +* **Note** Each listening service +configuration needs one or more load balancer member server (that can be +declared with the haproxy::balancermember defined resource type). Using +storeconfigs, you can export the haproxy::balancermember resources on all +load balancer member servers, and then collect them on a single haproxy +load balancer server. + +#### Examples + +##### + +```puppet +haproxy::listen { 'puppet00': + ipaddress => $::ipaddress, + ports => '18140', + mode => 'tcp', + options => { + 'option' => [ + 'tcplog', + 'ssl-hello-chk' + ], + 'balance' => 'roundrobin' + }, +} +``` + +#### Parameters + +The following parameters are available in the `haproxy::listen` defined type. + +##### `section_name` + +Data type: `Any` + +This name goes right after the 'listen' statement in haproxy.cfg +Default: $name (the namevar of the resource). + +Default value: $name + +##### `ports` + +Data type: `Any` + +Ports on which the proxy will listen for connections on the ip address + specified in the ipaddress parameter. Accepts either a single + comma-separated string or an array of strings which may be ports or + hyphenated port ranges. + +Default value: `undef` + +##### `ipaddress` + +Data type: `Any` + +The ip address the proxy binds to. + Empty addresses, '*', and '0.0.0.0' mean that the proxy listens + to all valid addresses on the system. + +Default value: `undef` + +##### `bind` + +Data type: `Optional[Hash]` + +Set of ip addresses, port and bind options +$bind = { '10.0.0.1:80' => ['ssl', 'crt', '/path/to/my/crt.pem'] } + +Default value: `undef` + +##### `mode` + +Data type: `Any` + +The mode of operation for the listening service. Valid values are undef, + 'tcp', 'http', and 'health'. + +Default value: `undef` + +##### `options` + +Data type: `Any` + +A hash of options that are inserted into the listening service + configuration block. + +Default value: { + 'option' => [ + 'tcplog', + ], + 'balance' => 'roundrobin' + } + +##### `bind_options` + +Data type: `Any` + +(Deprecated) An array of options to be specified after the bind declaration + in the listening serivce's configuration block. + +Default value: '' + +##### `collect_exported` + +Data type: `Any` + +Boolean, default 'true'. True means 'collect exported @@balancermember resources' + (for the case when every balancermember node exports itself), false means + 'rely on the existing declared balancermember resources' (for the case when you + know the full set of balancermembers in advance and use haproxy::balancermember + with array arguments, which allows you to deploy everything in 1 run) + +Default value: `true` + +##### `sort_options_alphabetic` + +Data type: `Any` + +Sort options either alphabetic or custom like haproxy internal sorts them. +Defaults to true. + +Default value: `undef` + +##### `defaults` + +Data type: `Any` + +Name of the defaults section this backend will use. +Defaults to undef which means the global defaults section will be used. + +Default value: `undef` + +##### `config_file` + +Data type: `Optional[Stdlib::Absolutepath]` + +Optional. Path of the config file where this entry will be added. +Assumes that the parent directory exists. +Default: $haproxy::params::config_file + +Default value: `undef` + +##### `instance` + +Data type: `Any` + +Optional. Defaults to 'haproxy' + +Default value: 'haproxy' + +### haproxy::mailer + +This type will set up a mailer entry inside the mailers configuration block in +haproxy.cfg on the load balancer. + +* **Note** Currently, it has the ability to +specify the instance name, ip address, ports and server_names. +Automatic discovery of mailer nodes may be implemented by exporting the mailer +resource for all HAProxy balancer servers that are configured in the same HA +block and then collecting them on all load balancers. + +#### Parameters + +The following parameters are available in the `haproxy::mailer` defined type. + +##### `mailers_name` + +Data type: `Any` + +Specifies the mailer in which this load balancer needs to be added. + +##### `server_names` + +Data type: `Any` + +Sets the name of the mailer server in the mailers 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 mailer is created for each pair + of server\_names and ipaddresses in the array. + +Default value: $::hostname + +##### `ipaddresses` + +Data type: `Any` + +Specifies the IP address used to contact the mailer 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 mailer is created for each pair of address and server_name. + +Default value: $::ipaddress + +##### `port` + +Data type: `Any` + +Sets the port on which the mailer is going to share the state. + +##### `instance` + +Data type: `Any` + + + +Default value: 'haproxy' + +### haproxy::mailers + +This type will set up a mailers entry in haproxy.cfg on the load balancer. + +* **Note** This setting makes it possible to send emails during state changes. + +#### Parameters + +The following parameters are available in the `haproxy::mailers` defined type. + +##### `instance` + +Data type: `Any` + +Optional. Defaults to 'haproxy'. + +Default value: 'haproxy' + +##### `collect_exported` + +Data type: `Any` + +Boolean. Defaults to true. + +Default value: `true` + +### haproxy::mapfile + +Manage an HAProxy map file as documented in +https://cbonte.github.io/haproxy-dconv/configuration-1.5.html#7.3.1-map + +* **Note** A map file contains one key + value per line. These key-value pairs are +specified in the `mappings` array. + +#### Parameters + +The following parameters are available in the `haproxy::mapfile` defined type. + +##### `name` + +The namevar of the defined resource type is the filename of the map file +(without any extension), relative to the `haproxy::config_dir` directory. +A '.map' extension will be added automatically. + +##### `mappings` + +Data type: `Array` + +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: `[]` + +Default value: [] + +##### `ensure` + +Data type: `Enum['present', 'absent']` + +The state of the underlying file resource, either 'present' or 'absent'. +Default: 'present' + +Default value: 'present' + +##### `owner` + +Data type: `Any` + +The owner of the underlying file resource. Defaut: 'root' + +Default value: 'root' + +##### `group` + +Data type: `Any` + +The group of the underlying file resource. Defaut: 'root' + +Default value: 'root' + +##### `mode` + +Data type: `Any` + +The mode of the underlying file resource. Defaut: '0644' + +Default value: '0644' + +##### `instances` + +Data type: `Array` + +Array of managed HAproxy instance names 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. Default: `[ 'haproxy' ]` + +Default value: [ 'haproxy' ] + +### haproxy::peer + +This type will set up a peer entry inside the peers configuration block in haproxy.cfg on the load balancer. + +* **Note** Currently, it has the ability to +specify the instance name, ip address, ports and server_names. + +#### Parameters + +The following parameters are available in the `haproxy::peer` defined type. + +##### `peers_name` + +Data type: `Any` + +Specifies the peer in which this load balancer needs to be added. + +##### `server_names` + +Data type: `Any` + +Sets the name of the peer server in the peers 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 peer is created for each pair +of server\_names and ipaddresses in the array. + +Default value: $::hostname + +##### `ipaddresses` + +Data type: `Any` + +Specifies the IP address used to contact the peer 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 peer is created for each pair of address and server_name. + +Default value: $::ipaddress + +##### `port` + +Data type: `Any` + +Sets the port on which the peer is going to share the state. + +##### `config_file` + +Data type: `Optional[Stdlib::Absolutepath]` + +Optional. Path of the config file where this entry will be added. +Assumes that the parent directory exists. +Default: $haproxy::params::config_file + +Default value: `undef` + +##### `instance` + +Data type: `Any` + + + +Default value: 'haproxy' + +### haproxy::peer::collect_exported + +Private define + +### haproxy::peers + +on the load balancer. This setting is required to share the +current state of HAproxy with other HAproxy in High available +configurations. + +#### Parameters + +The following parameters are available in the `haproxy::peers` defined type. + +##### `name` + +Sets the peers' name. Generally it will be the namevar of the + defined resource type. This value appears right after the + 'peers' statement in haproxy.cfg + +##### `config_file` + +Data type: `Optional[Stdlib::Absolutepath]` + +Optional. Path of the config file where this entry will be added. +Assumes that the parent directory exists. +Default: $haproxy::params::config_file + +Default value: `undef` + +##### `instance` + +Data type: `String` + +Optional. Defaults to 'haproxy' + +Default value: 'haproxy' + +##### `collect_exported` + +Data type: `Boolean` + +Boolean. Defaults to true + +Default value: `true` + +### haproxy::resolver + +=== Authors + +Gary Larizza +Ricardo Rosales + +* **Note** Currently requires the puppetlabs/concat module on the Puppet Forge and +uses storeconfigs on the Puppet Master to export/collect resources +from all balancer members. + +#### Examples + +##### + +```puppet +Exporting the resource for a balancer member: + +haproxy::resolver { 'puppet00': + nameservers => { + 'dns1' => '10.0.0.1:53', + 'dns2' => '10.0.0.2:53' + }, + hold => { + 'nx' => '30s', + 'valid' => '10s' + }, + resolve_retries => 3, + timeout => { + 'retry' => '1s' + }, + accepted_payload_size => 512, +} +``` + +#### Parameters + +The following parameters are available in the `haproxy::resolver` defined type. + +##### `section_name` + +Data type: `Any` + +This name goes right after the 'resolvers' statement in haproxy.cfg +Default: $name (the namevar of the resource). + +Default value: $name + +##### `nameservers` + +Data type: `Any` + +Set of id, ip addresses and port options. +$nameservers = { 'dns1' => '10.0.0.1:53', 'dns2' => '10.0.0.2:53' } + +Default value: `undef` + +##### `hold` + +Data type: `Any` + +Defines during which the last name resolution should be kept + based on last valid resolution status. +$hold = { 'nx' => '30s', 'valid' => '10s' } + +Default value: `undef` + +##### `resolve_retries` + +Data type: `Any` + +Defines the number of queries to send to resolve a server name before + giving up. +$resolve_retries = 3 + +Default value: `undef` + +##### `timeout` + +Data type: `Any` + +Defines timeouts related to name resolution in the listening serivce's + configuration block. +$timeout = { 'retry' => '1s' } + +Default value: `undef` + +##### `accepted_payload_size` + +Data type: `Any` + +Defines the maximum payload size accepted by HAProxy and announced to all the +name servers configured in this resolvers section. + is in bytes. If not set, HAProxy announces 512. (minimal value defined +by RFC 6891) +Note: the maximum allowed value is 8192. + +Default value: `undef` + +##### `collect_exported` + +Data type: `Any` + +Boolean, default 'true'. True means 'collect exported @@balancermember + resources' (for the case when every balancermember node exports itself), + false means 'rely on the existing declared balancermember resources' (for + the case when you know the full set of balancermember in advance and use + haproxy::balancermember with array arguments, which allows you to deploy + everything in 1 run) + +Default value: `true` + +##### `config_file` + +Data type: `Any` + +Optional. Path of the config file where this entry will be added. +Assumes that the parent directory exists. +Default: $haproxy::params::config_file + +Default value: `undef` + +##### `sort_options_alphabetic` + +Data type: `Any` + +Sort options either alphabetic or custom like haproxy internal sorts them. +Defaults to true. + +Default value: `undef` + +##### `defaults` + +Data type: `Any` + +Name of the defaults section this backend will use. +Defaults to undef which means the global defaults section will be used. + +Default value: `undef` + +##### `instance` + +Data type: `Any` + +Optional. Defaults to 'haproxy' + +Default value: 'haproxy' + +### haproxy::userlist + +=== Authors + +Jeremy Kitchen + +* **Note** See http://cbonte.github.io/haproxy-dconv/configuration-1.4.html#3.4 for more info + +#### Parameters + +The following parameters are available in the `haproxy::userlist` defined type. + +##### `section_name` + +Data type: `String` + +This name goes right after the 'userlist' statement in haproxy.cfg +Default: $name (the namevar of the resource). + +Default value: $name + +##### `users` + +Data type: `Any` + +An array of users in the userlist. +See http://cbonte.github.io/haproxy-dconv/configuration-1.4.html#3.4-user + +Default value: `undef` + +##### `groups` + +Data type: `Any` + +An array of groups in the userlist. +See http://cbonte.github.io/haproxy-dconv/configuration-1.4.html#3.4-group + +Default value: `undef` + +##### `config_file` + +Data type: `Optional[Stdlib::Absolutepath]` + +Optional. Path of the config file where this entry will be added. +Assumes that the parent directory exists. +Default: $haproxy::params::config_file + +Default value: `undef` + +##### `instance` + +Data type: `String` + +Optional. Defaults to 'haproxy' + +Default value: 'haproxy' + diff --git a/manifests/backend.pp b/manifests/backend.pp index 8f833fb1..63609e78 100644 --- a/manifests/backend.pp +++ b/manifests/backend.pp @@ -1,32 +1,30 @@ -# == Define Resource Type: haproxy::backend -# -# This type will setup a backend service configuration block inside the -# haproxy.cfg file on an haproxy load balancer. Each backend service needs one -# or more backend member servers (that can be declared with the -# haproxy::balancermember defined resource type). Using storeconfigs, you can -# export the haproxy::balancermember resources on all load balancer member -# servers and then collect them on a single haproxy load balancer server. -# -# === Requirement/Dependencies: -# -# Currently requires the puppetlabs/concat module on the Puppet Forge and -# uses storeconfigs on the Puppet Master to export/collect resources -# from all backend members. -# -# === Parameters -# -# [*section_name*] +# @summary +# This type will setup a backend service configuration block inside the +# haproxy.cfg file on an haproxy load balancer. +# @note +# Each backend service needs one +# or more backend member servers (that can be declared with the +# haproxy::balancermember defined resource type). Using storeconfigs, you can +# export the haproxy::balancermember resources on all load balancer member +# servers and then collect them on a single haproxy load balancer server. +# +# @note +# Currently requires the puppetlabs/concat module on the Puppet Forge and +# uses storeconfigs on the Puppet Master to export/collect resources +# from all backend members. +# +# @param section_name # This name goes right after the 'backend' statement in haproxy.cfg # Default: $name (the namevar of the resource). # -# [*mode*] +# @param mode # The mode of operation for the backend service. Valid values are undef, # 'tcp', 'http', and 'health'. # -# [*options*] +# @param options # A hash of options that are inserted into the backend configuration block. # -# [*collect_exported*] +# @param collect_exported # Boolean, default 'true'. True means 'collect exported @@balancermember # resources' (for the case when every balancermember node exports itself), # false means 'rely on the existing declared balancermember resources' (for @@ -34,23 +32,23 @@ # haproxy::balancermember with array arguments, which allows you to deploy # everything in 1 run) # -# [*config_file*] +# @param config_file # Optional. Path of the config file where this entry will be added. # Assumes that the parent directory exists. # Default: $haproxy::params::config_file # -# [*sort_options_alphabetic*] +# @param sort_options_alphabetic # Sort options either alphabetic or custom like haproxy internal sorts them. # Defaults to true. # -# [*defaults*] +# @param defaults # Name of the defaults section this backend will use. # Defaults to undef which means the global defaults section will be used. +# +# @param instance +# Optional. Defaults to 'haproxy' # -# === Examples -# -# Exporting the resource for a backend member: -# +# @example # haproxy::backend { 'puppet00': # options => { # 'option' => [ diff --git a/manifests/balancermember.pp b/manifests/balancermember.pp index a7139b0e..0e299c9b 100644 --- a/manifests/balancermember.pp +++ b/manifests/balancermember.pp @@ -1,87 +1,91 @@ -# == Define Resource Type: haproxy::balancermember -# -# This type will setup a balancer member inside a listening service +# @summary +# This type will setup a balancer member inside a listening service # configuration block in /etc/haproxy/haproxy.cfg on the load balancer. -# currently it only has the ability to specify the instance name, +# +# @note +# Currently it only has the ability to specify the instance name, # ip address, port, and whether or not it is a backup. More features # can be added as needed. The best way to implement this is to export # this resource for all haproxy balancer member servers, and then collect # them on the main haproxy load balancer. # -# === Requirement/Dependencies: -# -# Currently requires the puppetlabs/concat module on the Puppet Forge and +# @note +# Currently requires the puppetlabs/concat module on the Puppet Forge and # uses storeconfigs on the Puppet Master to export/collect resources # from all balancer members. # -# === Parameters # -# [*listening_service*] +# @param listening_service # The haproxy service's instance name (or, the title of the # haproxy::listen resource). This must match up with a declared # haproxy::listen resource. # -# [*ports*] +# @param ports # An array or commas-separated list of ports for which the balancer member # will accept connections from the load balancer. Note that cookie values # aren't yet supported, but shouldn't be difficult to add to the # configuration. If you use an array in server_names and ipaddresses, the # same port is used for all balancermembers. # -# [*port*] +# @param port # A port for server-template. It is an optional specification. # -# [*server_names*] +# @param server_names # The name of the balancer member server as known to haproxy in the # listening service's configuration block. This defaults to the # hostname. Can be an array of the same length as ipaddresses, # in which case a balancermember is created for each pair of # server_names and ipaddresses (in lockstep). # -# [*ipaddresses*] +# @param ipaddresses # The ip address used to contact the balancer member server. # Can be an array, see documentation to server_names. # -# [*prefix*] +# @param prefix # A prefix for the server-template for the server names to be built. # -# [*amount*] +# @param amount # If "amount" is provided, the server-template initializes servers # with 1 up to as server name suffixes. A range of numbers # - may also be used to use up to # as server name suffixes. # -# [*fqdn*] +# @param fqdn # A FQDN for all the servers the server-template initializes. # -# [*options*] +# @param options # An array of options to be specified after the server declaration # in the listening service's configuration block. # -# [*define_cookies*] +# @param define_cookies # If true, then add "cookie SERVERID" stickiness options. # Default false. # -# [*defaults*] +# @param defaults # Name of the defaults section the backend or listener use. # Defaults to undef. # -# [*config_file*] +# @param config_file # Optional. Path of the config file where this entry will be added. # Assumes that the parent directory exists. # Default: $haproxy::params::config_file # -# [*verifyhost*] +# @param verifyhost # Optional. Will add the verifyhost option to the server line, using the # specific host from server_names as an argument. # Default: false # -# [*weight*] +# @param weight # Optional. Will add the weight option to the server line # Default: undef # -# === Examples +# @param instance +# Optional. Defaults to 'haproxy' +# +# @param type +# Optional. Defaults to 'server' # +# @example # Exporting the resource for a balancer member: # # @@haproxy::balancermember { 'haproxy': @@ -97,6 +101,7 @@ # # Haproxy::Balancermember <<| listening_service == 'puppet00' |>> # +# @example # Creating the resource for multiple balancer members at once # (for single-pass installation of haproxy without requiring a first # pass to export the resources if you know the members in advance): @@ -109,6 +114,7 @@ # options => 'check', # } # +# @example # Implemented in HAPROXY 1.8: # Set a template to initialize servers with shared parameters. # The names of these servers are built from and parameters. diff --git a/manifests/balancermember/collect_exported.pp b/manifests/balancermember/collect_exported.pp index f32696e4..ca94ec4c 100644 --- a/manifests/balancermember/collect_exported.pp +++ b/manifests/balancermember/collect_exported.pp @@ -1,4 +1,4 @@ -# Private define +# @api private define haproxy::balancermember::collect_exported { if $caller_module_name != $module_name { fail("Use of private class ${name} by ${caller_module_name}") diff --git a/manifests/config.pp b/manifests/config.pp index ac596235..c257802e 100644 --- a/manifests/config.pp +++ b/manifests/config.pp @@ -1,5 +1,6 @@ -# Private class -# +# @summary +# HAProxy configuration +# @api private define haproxy::config ( # lint:ignore:140chars $instance_name, diff --git a/manifests/defaults.pp b/manifests/defaults.pp index b8384cce..af8a5484 100644 --- a/manifests/defaults.pp +++ b/manifests/defaults.pp @@ -1,21 +1,24 @@ -# == Define Resource Type: haproxy::defaults +# @summary +# This type will setup a additional defaults configuration block inside the +# haproxy.cfg file on an haproxy load balancer. # -# This type will setup a additional defaults configuration block inside the -# haproxy.cfg file on an haproxy load balancer. A new default configuration -# block resets all defaults of prior defaults configuration blocks. Listener, -# Backends, Frontends and Balancermember can be configured behind a default +# @note +# A new default configuration block resets all defaults of prior defaults configuration blocks. +# Listener, Backends, Frontends and Balancermember can be configured behind a default # configuration block by setting the defaults parameter to the corresponding # defaults name. # -# === Parameters: # -# [*options*] +# @param options # A hash of options that are inserted into the defaults configuration block. # -# [*sort_options_alphabetic*] +# @param sort_options_alphabetic # Sort options either alphabetic or custom like haproxy internal sorts them. # Defaults to true. - +# +# @param instance +# Optional. Defaults to 'haproxy'. +# define haproxy::defaults ( $options = {}, $sort_options_alphabetic = undef, diff --git a/manifests/frontend.pp b/manifests/frontend.pp index 24db454c..cd300b13 100644 --- a/manifests/frontend.pp +++ b/manifests/frontend.pp @@ -1,68 +1,69 @@ -# == Define Resource Type: haproxy::frontend +# @summary +# This type will setup a frontend service configuration block inside +# the haproxy.cfg file on an haproxy load balancer. # -# This type will setup a frontend service configuration block inside -# the haproxy.cfg file on an haproxy load balancer. +# @note +# Currently requires the puppetlabs/concat module on the Puppet Forge and +# uses storeconfigs on the Puppet Master to export/collect resources +# from all balancer members. # -# === Requirement/Dependencies: -# -# Currently requires the puppetlabs/concat module on the Puppet Forge and -# uses storeconfigs on the Puppet Master to export/collect resources -# from all balancer members. -# -# === Parameters -# -# [*section_name*] +# @param section_name # This name goes right after the 'frontend' statement in haproxy.cfg # Default: $name (the namevar of the resource). # -# [*ports*] +# @param ports # Ports on which the proxy will listen for connections on the ip address # specified in the ipaddress parameter. Accepts either a single # comma-separated string or an array of strings which may be ports or # hyphenated port ranges. # -# [*bind*] +# @param bind # Set of ip addresses, port and bind options # $bind = { '10.0.0.1:80' => ['ssl', 'crt', '/path/to/my/crt.pem'] } # -# [*ipaddress*] +# @param ipaddress # The ip address the proxy binds to. # Empty addresses, '*', and '0.0.0.0' mean that the proxy listens # to all valid addresses on the system. # -# [*mode*] +# @param mode # The mode of operation for the frontend service. Valid values are undef, # 'tcp', 'http', and 'health'. # -# [*bind_options*] +# @param bind_options # (Deprecated) An array of options to be specified after the bind declaration # in the listening serivce's configuration block. # -# [*options*] +# @param options # A hash of options that are inserted into the frontend service # configuration block. # -# [*sort_options_alphabetic*] +# @param sort_options_alphabetic # Sort options either alphabetic or custom like haproxy internal sorts them. # Defaults to true. # -# [*defaults*] +# @param defaults # Name of the defaults section this backend will use. # Defaults to undef which means the global defaults section will be used. # -# [*defaults_use_backend*] +# @param defaults_use_backend # If defaults are used and a default backend is configured use the backend # name for ordering. This means that the frontend is placed in the # configuration file before the backend configuration. # Defaults to true. # -# [*config_file*] +# @param config_file # Optional. Path of the config file where this entry will be added. # Assumes that the parent directory exists. # Default: $haproxy::params::config_file # -# === Examples +# @param collect_exported +# Boolean. Default true +# +# @param instance +# Optional. Defaults to 'haproxy' # +# @example # Exporting the resource for a balancer member: # # haproxy::frontend { 'puppet00': diff --git a/manifests/globals.pp b/manifests/globals.pp index cb60cdc4..d51d081f 100644 --- a/manifests/globals.pp +++ b/manifests/globals.pp @@ -1,10 +1,7 @@ -# == Class: haproxy::globals +# @summary +# For global configuration options used by all haproxy instances. # -# For global configuration options used by all haproxy instances. -# -# === Parameters -# -# [*sort_options_alphabetic*] +# @param sort_options_alphabetic # Sort options either alphabetic or custom like haproxy internal sorts them. # Defaults to true. # diff --git a/manifests/init.pp b/manifests/init.pp index c9e18f9d..eb117f10 100644 --- a/manifests/init.pp +++ b/manifests/init.pp @@ -1,89 +1,92 @@ -# == Class: haproxy -# +# @summary # A Puppet module, using storeconfigs, to model an haproxy configuration. # Currently VERY limited - assumes Redhat/CentOS setup. Pull requests accepted! # -# === Requirement/Dependencies: +# @note # # Currently requires the puppetlabs/concat module on the Puppet Forge and # uses storeconfigs on the Puppet Master to export/collect resources # from all balancer members. # -# === Parameters # -# [*package_ensure*] +# @param package_ensure # Ensure the package is present (installed), absent or a specific version. # Defaults to 'present' # -# [*package_name*] +# @param package_name # The package name of haproxy. Defaults to 'haproxy' # NOTE: haproxy::instance has a different default. # -# [*service_ensure*] +# @param service_ensure # Chooses whether the haproxy service should be running & enabled at boot, or # stopped and disabled at boot. Defaults to 'running' # -# [*service_manage*] +# @param service_manage # Chooses whether the haproxy service state should be managed by puppet at # all. Defaults to true # -# [*service_name*] +# @param service_name # The service name for haproxy. Defaults to 'haproxy' # NOTE: haproxy::instance has a different default. # -# [*service_options*] +# @param service_options # Contents for the `/etc/defaults/haproxy` file on Debian. Defaults to "ENABLED=1\n" on Debian, and is ignored on other systems. # -# [*sysconfig_options*] +# @param sysconfig_options # Contents for the `/etc/sysconfig/haproxy` file on RedHat(-based) systems. # Defaults to OPTIONS="" on RedHat(-based) systems and is ignored on others # -# [*global_options*] +# @param 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*] +# @param 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. # -# [*merge_options*] +# @param merge_options # Whether to merge the user-supplied `global_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 to # false, but will default to true in future releases. # -# [*restart_command*] +# @param 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*] +# @param custom_fragment # Allows arbitrary HAProxy configuration to be passed through to support # additional configuration not available via parameters, or to short-circute # 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_dir*] +# @param config_dir # Path to the directory in which the main configuration file `haproxy.cfg` # resides. Will also be used for storing any managed map files (see # `haproxy::mapfile`). Default depends on platform. # -# [*config_file*] +# @param config_file # Optional. Path to the haproxy config file. # Default depends on platform. # -# [*config_validate_cmd*] +# @param config_validate_cmd # Optional. Command used by concat validate_cmd to validate new # config file concat is a valid haproxy config. # Default /usr/sbin/haproxy -f % -c # -# === Examples -# +# @param manage_config_dir +# Optional. +# @param manage_service +# Deprecated +# @param enable +# Deprecated +# @example # class { 'haproxy': # global_options => { # 'log' => "${::ipaddress} local0", diff --git a/manifests/install.pp b/manifests/install.pp index 172674fb..f5d44478 100644 --- a/manifests/install.pp +++ b/manifests/install.pp @@ -1,4 +1,6 @@ -# Private class +# @summary +# Install haproxy +# @api private define haproxy::install ( # lint:ignore:140chars $package_ensure, diff --git a/manifests/instance.pp b/manifests/instance.pp index 91e04bdb..31ae5723 100644 --- a/manifests/instance.pp +++ b/manifests/instance.pp @@ -1,82 +1,89 @@ -# == Define Resource Type: haproxy::instance +# @summary +# Manages haproxy permitting multiple instances to run on the same machine. +# +# @note +# Normally users use the Class['haproxy'], which runs a single haproxy +# daemon on a machine. # -# Manages haproxy permitting multiple instances to run on the same machine. -# Normally users use the Class['haproxy'], which runs a single haproxy -# daemon on a machine. +# @note +# Currently requires the puppetlabs/concat module on the Puppet Forge and +# uses storeconfigs on the Puppet Master to export/collect resources +# from all balancer members. # -# === Requirement/Dependencies: # -# Currently requires the puppetlabs/concat module on the Puppet Forge and -# uses storeconfigs on the Puppet Master to export/collect resources -# from all balancer members. -# -# === Parameters -# -# [*package_ensure*] +# @param package_ensure # Ensure the package is present (installed), absent or a specific version. # Defaults to 'present' # -# [*package_name*] +# @param package_name # The package name of haproxy. Defaults to undef, and no package is installed. # NOTE: Class['haproxy'] has a different default. # -# [*service_ensure*] +# @param service_ensure # Chooses whether the haproxy service should be running & enabled at boot, or # stopped and disabled at boot. Defaults to 'running' # -# [*service_manage*] +# @param service_manage # Chooses whether the haproxy service state should be managed by puppet at # all. Defaults to true # -# [*service_name*] +# @param service_name # The service name for haproxy. Defaults to undef. If no name is given then # the value computed for $instance_name will be used. # NOTE: Class['haproxy'] has a different default. # -# [*global_options*] +# @param 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*] +# @param 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*] +# @param 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 +# @param 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. -# -# [*config_validate_cmd*] +# @param 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. +# +# @param config_validate_cmd # Command used by concat validate_cmd to validate new # config file concat is a valid haproxy config. # Default /usr/sbin/haproxy -f % -c # -# === Examples +# @param config_dir +# Optional. Default undef. +# +# @param merge_options +# +# @param service_options +# +# @param sysconfig_options # -# A single instance of haproxy with all defaults -# i.e. emulate Class['haproxy'] +# @example +# A single instance of haproxy with all defaults +# i.e. emulate Class['haproxy'] # package{ 'haproxy': ensure => present }->haproxy::instance { 'haproxy': }-> # haproxy::listen { 'puppet00': # instance => 'haproxy', @@ -85,7 +92,8 @@ # ports => '8140', # } # -# Multiple instances of haproxy: +# @example +# Multiple instances of haproxy: # haproxy::instance { 'group1': } # haproxy::instance_service { 'group1': # haproxy_init_source => "puppet:///modules/${module_name}/haproxy-group1.init", @@ -109,7 +117,8 @@ # requires => Package['haproxy'], # } # -# Multiple instances of haproxy, one with a custom haproxy package: +# @example +# Multiple instances of haproxy, one with a custom haproxy package: # haproxy::instance { 'group1': } # haproxy::instance_service { 'group1': # haproxy_init_source => "puppet:///modules/${module_name}/haproxy-group1.init", @@ -134,15 +143,16 @@ # requires => Package['haproxy'], # } # -# When running multiple instances on one host, there must be a Service[] for -# each instance. One way to create the situation where Service[] works is -# using haproxy::instance_service. -# However you may want to do it some other way. For example, you may -# not have packages for your custom haproxy binary. Or, you may wish -# to use the standard haproxy package but not create links to it, or -# you may have different init.d scripts. In these cases, write your own -# puppet code that will result in Service[] working for you and do not -# call haproxy::instance_service. +# @note +# When running multiple instances on one host, there must be a Service[] for +# each instance. One way to create the situation where Service[] works is +# using haproxy::instance_service. +# However you may want to do it some other way. For example, you may +# not have packages for your custom haproxy binary. Or, you may wish +# to use the standard haproxy package but not create links to it, or +# you may have different init.d scripts. In these cases, write your own +# puppet code that will result in Service[] working for you and do not +# call haproxy::instance_service. # define haproxy::instance ( Optional[String] $package_name = undef, diff --git a/manifests/instance_service.pp b/manifests/instance_service.pp index fe667015..00d89a78 100644 --- a/manifests/instance_service.pp +++ b/manifests/instance_service.pp @@ -1,40 +1,40 @@ -# == Define: haproxy::instance_service +# @summary +# Set up the environment for an haproxy service. # -# Set up the environment for an haproxy service. +# @note # * Associate an haproxy instance with the haproxy package it should use. # * Create the start/restart/stop functions needed by Service[]. -# In other words: sets things up so that Service[$instance_name] will work. +# In other words: sets things up so that Service[$instance_name] will work. # -# In particular: -# * Create a link to the binary an instance will be using. This -# way each instance can link to a different binary. -# If you have an instance called "foo", you know "haproxy-foo" -# is a link to the binary it should be using. -# * Create an init.d file named after the instance. This way -# Service[$instance] can start/restart the service. +# In particular: +# * Create a link to the binary an instance will be using. This +# way each instance can link to a different binary. +# If you have an instance called "foo", you know "haproxy-foo" +# is a link to the binary it should be using. +# * Create an init.d file named after the instance. This way +# Service[$instance] can start/restart the service. # -# NOTE: -# This manifest is just one example of how to set up Service[$instance]. -# Other sites may choose to do it very differently. In that case, do -# not call haproxy::instance_service; write your own module. The only -# requirement is that before haproxy::instance{$instance:} is called, -# Service[$instance] must be defined. +# @note +# This manifest is just one example of how to set up Service[$instance]. +# Other sites may choose to do it very differently. In that case, do +# not call haproxy::instance_service; write your own module. The only +# requirement is that before haproxy::instance{$instance:} is called, +# Service[$instance] must be defined. # -# FIXME: This hasn't been tested on FreeBSD. -# FIXME: This should take advantage of systemd when available. +# FIXME: This hasn't been tested on FreeBSD. +# FIXME: This should take advantage of systemd when available. # -# === Parameters # -# [*haproxy_package*] +# @param 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*] +# @param bindir # Where to put symlinks to the binary used for each instance. # Defaults to '/opt/haproxy' # -# [*haproxy_init_source*] +# @param haproxy_init_source # The init.d script that will start/restart/reload this instance. # define haproxy::instance_service ( diff --git a/manifests/listen.pp b/manifests/listen.pp index 2c895ea0..e3ef4015 100644 --- a/manifests/listen.pp +++ b/manifests/listen.pp @@ -1,76 +1,76 @@ -# == Define Resource Type: haproxy::listen +# @summary +# This type will setup a listening service configuration block inside +# the haproxy.cfg file on an haproxy load balancer. # -# This type will setup 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 (that can be -# declared with the haproxy::balancermember defined resource type). Using -# storeconfigs, you can export the haproxy::balancermember resources on all -# load balancer member servers, and then collect them on a single haproxy -# load balancer server. +# @note +# Each listening service +# configuration needs one or more load balancer member server (that can be +# declared with the haproxy::balancermember defined resource type). Using +# storeconfigs, you can export the haproxy::balancermember resources on all +# load balancer member servers, and then collect them on a single haproxy +# load balancer server. # -# === Requirement/Dependencies: +# @note +# Currently requires the puppetlabs/concat module on the Puppet Forge and +# uses storeconfigs on the Puppet Master to export/collect resources +# from all balancer members. # -# Currently requires the puppetlabs/concat module on the Puppet Forge and -# uses storeconfigs on the Puppet Master to export/collect resources -# from all balancer members. # -# === Parameters -# -# [*section_name*] +# @param section_name # This name goes right after the 'listen' statement in haproxy.cfg # Default: $name (the namevar of the resource). # -# [*ports*] +# @param ports # Ports on which the proxy will listen for connections on the ip address # specified in the ipaddress parameter. Accepts either a single # comma-separated string or an array of strings which may be ports or # hyphenated port ranges. # -# [*ipaddress*] +# @param ipaddress # The ip address the proxy binds to. # Empty addresses, '*', and '0.0.0.0' mean that the proxy listens # to all valid addresses on the system. # -# [*bind*] +# @param bind # Set of ip addresses, port and bind options # $bind = { '10.0.0.1:80' => ['ssl', 'crt', '/path/to/my/crt.pem'] } # -# [*mode*] +# @param mode # The mode of operation for the listening service. Valid values are undef, # 'tcp', 'http', and 'health'. # -# [*options*] +# @param options # A hash of options that are inserted into the listening service # configuration block. # -# [*bind_options*] +# @param bind_options # (Deprecated) An array of options to be specified after the bind declaration # in the listening serivce's configuration block. # -# [*collect_exported*] +# @param collect_exported # Boolean, default 'true'. True means 'collect exported @@balancermember resources' # (for the case when every balancermember node exports itself), false means # 'rely on the existing declared balancermember resources' (for the case when you # know the full set of balancermembers in advance and use haproxy::balancermember # with array arguments, which allows you to deploy everything in 1 run) # -# [*sort_options_alphabetic*] +# @param sort_options_alphabetic # Sort options either alphabetic or custom like haproxy internal sorts them. # Defaults to true. # -# [*defaults*] +# @param defaults # Name of the defaults section this backend will use. # Defaults to undef which means the global defaults section will be used. # -# [*config_file*] +# @param config_file # Optional. Path of the config file where this entry will be added. # Assumes that the parent directory exists. # Default: $haproxy::params::config_file # -# === Examples -# -# Exporting the resource for a balancer member: +# @param instance +# Optional. Defaults to 'haproxy' # +# @example # haproxy::listen { 'puppet00': # ipaddress => $::ipaddress, # ports => '18140', diff --git a/manifests/mailer.pp b/manifests/mailer.pp index ebb9a393..b8a949a1 100644 --- a/manifests/mailer.pp +++ b/manifests/mailer.pp @@ -1,39 +1,35 @@ -# == Define Resource Type: haproxy::mailer +# @summary +# This type will set up a mailer entry inside the mailers configuration block in +# haproxy.cfg on the load balancer. # -# This type will set up a mailer entry inside the mailers configuration block in -# haproxy.cfg on the load balancer. Currently, it has the ability to -# specify the instance name, ip address, ports and server_names. +# @note +# Currently, it has the ability to +# specify the instance name, ip address, ports and server_names. +# Automatic discovery of mailer nodes may be implemented by exporting the mailer +# resource for all HAProxy balancer servers that are configured in the same HA +# block and then collecting them on all load balancers. # -# Automatic discovery of mailer nodes may be implemented by exporting the mailer -# resource for all HAProxy balancer servers that are configured in the same HA -# block and then collecting them on all load balancers. # -# === Parameters: -# -# [*mailers_name*] +# @param mailers_name # Specifies the mailer in which this load balancer needs to be added. # -# [*server_names*] +# @param server_names # Sets the name of the mailer server in the mailers 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 mailer is created for each pair # of server\_names and ipaddresses in the array. # -# [*ipaddresses*] +# @param ipaddresses # Specifies the IP address used to contact the mailer 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 mailer is created for each pair of address and server_name. # -# [*ports*] +# @param port # Sets the port on which the mailer is going to share the state. # -# [*config_file*] -# Optional. Path of the config file where this entry will be added. -# Assumes that the parent directory exists. -# Default: $haproxy::params::config_file - +# define haproxy::mailer ( $mailers_name, $port, diff --git a/manifests/mailer/collect_exported.pp b/manifests/mailer/collect_exported.pp index 1d925ea3..1066ceaf 100644 --- a/manifests/mailer/collect_exported.pp +++ b/manifests/mailer/collect_exported.pp @@ -1,4 +1,4 @@ -# Private define +# @api private define haproxy::mailer::collect_exported { if $caller_module_name != $module_name { fail("Use of private class ${name} by ${caller_module_name}") diff --git a/manifests/mailers.pp b/manifests/mailers.pp index adb211b4..5c8cb019 100644 --- a/manifests/mailers.pp +++ b/manifests/mailers.pp @@ -1,20 +1,15 @@ -# == Defined Type: haproxy::mailers -# +# @summary # This type will set up a mailers entry in haproxy.cfg on the load balancer. +# @note # This setting makes it possible to send emails during state changes. # -# === Parameters # -# [*name*] -# Sets the mailers' name. Generally it will be the namevar of the -# defined resource type. This value appears right after the -# 'mailers' statement in haproxy.cfg +# @param instance +# Optional. Defaults to 'haproxy'. +# +# @param collect_exported +# Boolean. Defaults to true. # -# [*config_file*] -# Optional. Path of the config file where this entry will be added. -# Assumes that the parent directory exists. -# Default: $haproxy::params::config_file - define haproxy::mailers ( $collect_exported = true, $instance = 'haproxy', diff --git a/manifests/mapfile.pp b/manifests/mapfile.pp index 6938b12c..6ad00ae6 100644 --- a/manifests/mapfile.pp +++ b/manifests/mapfile.pp @@ -1,35 +1,35 @@ -# == Define Resource Type: haproxy::mapfile +# @summary +# Manage an HAProxy map file as documented in +# https://cbonte.github.io/haproxy-dconv/configuration-1.5.html#7.3.1-map # -# Manage an HAProxy map file as documented in -# https://cbonte.github.io/haproxy-dconv/configuration-1.5.html#7.3.1-map -# A map file contains one key + value per line. These key-value pairs are -# specified in the `mappings` array. +# @note +# A map file contains one key + value per line. These key-value pairs are +# specified in the `mappings` array. # -# === Parameters # -# [*name*] +# @param name # The namevar of the defined resource type is the filename of the map file # (without any extension), relative to the `haproxy::config_dir` directory. # A '.map' extension will be added automatically. # -# [*mappings*] +# @param 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: `[]` # -# [*ensure*] +# @param ensure # The state of the underlying file resource, either 'present' or 'absent'. # Default: 'present' # -# [*owner*] +# @param owner # The owner of the underlying file resource. Defaut: 'root' # -# [*group*] +# @param group # The group of the underlying file resource. Defaut: 'root' # -# [*mode*] +# @param mode # The mode of the underlying file resource. Defaut: '0644' # -# [*instances*] +# @param instances # Array of managed HAproxy instance names 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. Default: `[ 'haproxy' ]` diff --git a/manifests/params.pp b/manifests/params.pp index be206295..266d02c2 100644 --- a/manifests/params.pp +++ b/manifests/params.pp @@ -1,8 +1,9 @@ -# == Class: haproxy::params +# @summary +# This is a container class holding default parameters for for haproxy class. # -# This is a container class holding default parameters for for haproxy class. -# currently, only the Redhat family is supported, but this can be easily -# extended by changing package names and configuration file paths. +# @note +# Currently, only the Redhat family is supported, but this can be easily +# extended by changing package names and configuration file paths. # class haproxy::params { # XXX: This will change to true in the next major release diff --git a/manifests/peer.pp b/manifests/peer.pp index 3a6cb589..a6f875b9 100644 --- a/manifests/peer.pp +++ b/manifests/peer.pp @@ -1,39 +1,39 @@ -# == Define Resource Type: haproxy::peer +# @summary This type will set up a peer entry inside the peers configuration block in haproxy.cfg on the load balancer. # -# This type will set up a peer entry inside the peers configuration block in -# haproxy.cfg on the load balancer. Currently, it has the ability to -# specify the instance name, ip address, ports and server_names. +# @note +# Currently, it has the ability to +# specify the instance name, ip address, ports and server_names. # -# Automatic discovery of peer nodes may be implemented by exporting the peer resource -# for all HAProxy balancer servers that are configured in the same HA block and -# then collecting them on all load balancers. # -# === Parameters: +# @param peers_name +# Specifies the peer in which this load balancer needs to be added. # -# [*peers_name*] -# Specifies the peer in which this load balancer needs to be added. -# -# [*server_names*] -# Sets the name of the peer server in the peers configuration block. +# @param server_names +# Sets the name of the peer server in the peers 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 peer is created for each pair # of server\_names and ipaddresses in the array. # -# [*ipaddresses*] -# Specifies the IP address used to contact the peer member server. +# @param ipaddresses +# Specifies the IP address used to contact the peer 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 peer is created for each pair of address and server_name. # -# [*ports*] -# Sets the port on which the peer is going to share the state. +# @param port +# Sets the port on which the peer is going to share the state. # -# [*config_file*] +# @param config_file # Optional. Path of the config file where this entry will be added. # Assumes that the parent directory exists. # Default: $haproxy::params::config_file - +# +# @note +# Automatic discovery of peer nodes may be implemented by exporting the peer resource +# for all HAProxy balancer servers that are configured in the same HA block and +# then collecting them on all load balancers. +# define haproxy::peer ( $peers_name, $port, diff --git a/manifests/peers.pp b/manifests/peers.pp index 10924c52..e443ad3b 100644 --- a/manifests/peers.pp +++ b/manifests/peers.pp @@ -1,22 +1,26 @@ -# == Defined Type: haproxy::peers +# @summary +# This type will set up a peers entry in haproxy.cfg +# on the load balancer. This setting is required to share the +# current state of HAproxy with other HAproxy in High available +# configurations. # -# This type will set up a peers entry in haproxy.cfg -# on the load balancer. This setting is required to share the -# current state of HAproxy with other HAproxy in High available -# configurations. # -# === Parameters -# -# [*name*] +# @param name # Sets the peers' name. Generally it will be the namevar of the # defined resource type. This value appears right after the # 'peers' statement in haproxy.cfg # -# [*config_file*] +# @param config_file # Optional. Path of the config file where this entry will be added. # Assumes that the parent directory exists. # Default: $haproxy::params::config_file - +# +# @param instance +# Optional. Defaults to 'haproxy' +# +# @param collect_exported +# Boolean. Defaults to true +# define haproxy::peers ( Boolean $collect_exported = true, String $instance = 'haproxy', diff --git a/manifests/resolver.pp b/manifests/resolver.pp index df470cbe..97f5a0e5 100644 --- a/manifests/resolver.pp +++ b/manifests/resolver.pp @@ -1,47 +1,44 @@ -# == Define Resource Type: haproxy::resolver -# -# This type will setup resolvers configuration block inside +# @summary +# This type will setup resolvers configuration block inside # the haproxy.cfg file on an haproxy load balancer. # -# === Requirement/Dependencies: -# -# Currently requires the puppetlabs/concat module on the Puppet Forge and +# @note +# Currently requires the puppetlabs/concat module on the Puppet Forge and # uses storeconfigs on the Puppet Master to export/collect resources # from all balancer members. # -# === Parameters # -# [*section_name*] +# @param section_name # This name goes right after the 'resolvers' statement in haproxy.cfg # Default: $name (the namevar of the resource). # -# [*nameservers*] +# @param nameservers # Set of id, ip addresses and port options. # $nameservers = { 'dns1' => '10.0.0.1:53', 'dns2' => '10.0.0.2:53' } # -# [*hold*] +# @param hold # Defines during which the last name resolution should be kept # based on last valid resolution status. # $hold = { 'nx' => '30s', 'valid' => '10s' } # -# [*resolve_retries*] +# @param resolve_retries # Defines the number of queries to send to resolve a server name before # giving up. # $resolve_retries = 3 # -# [*timeout*] +# @param timeout # Defines timeouts related to name resolution in the listening serivce's # configuration block. # $timeout = { 'retry' => '1s' } # -# [*accepted_payload_size*] +# @param accepted_payload_size # Defines the maximum payload size accepted by HAProxy and announced to all the # name servers configured in this resolvers section. # is in bytes. If not set, HAProxy announces 512. (minimal value defined # by RFC 6891) # Note: the maximum allowed value is 8192. # -# [*collect_exported*] +# @param collect_exported # Boolean, default 'true'. True means 'collect exported @@balancermember # resources' (for the case when every balancermember node exports itself), # false means 'rely on the existing declared balancermember resources' (for @@ -49,21 +46,23 @@ # haproxy::balancermember with array arguments, which allows you to deploy # everything in 1 run) # -# [*config_file*] +# @param config_file # Optional. Path of the config file where this entry will be added. # Assumes that the parent directory exists. # Default: $haproxy::params::config_file # -# [*sort_options_alphabetic*] +# @param sort_options_alphabetic # Sort options either alphabetic or custom like haproxy internal sorts them. # Defaults to true. # -# [*defaults*] +# @param defaults # Name of the defaults section this backend will use. # Defaults to undef which means the global defaults section will be used. +# +# @param instance +# Optional. Defaults to 'haproxy' # -# === Examples -# +# @example # Exporting the resource for a balancer member: # # haproxy::resolver { 'puppet00': diff --git a/manifests/service.pp b/manifests/service.pp index 7e19c551..40126911 100644 --- a/manifests/service.pp +++ b/manifests/service.pp @@ -1,4 +1,6 @@ -# Private class +# @summary +# HAProxy service +# @api private define haproxy::service ( # lint:ignore:140chars $instance_name, diff --git a/manifests/userlist.pp b/manifests/userlist.pp index 8dfa3388..1aac5203 100644 --- a/manifests/userlist.pp +++ b/manifests/userlist.pp @@ -1,32 +1,33 @@ -# == Define Resource Type: haproxy::userlist +# @summary +# This type will set up a userlist configuration block inside the haproxy.cfg +# file on an haproxy load balancer. # -# This type will set up a userlist configuration block inside the haproxy.cfg -# file on an haproxy load balancer. +# @note +# See http://cbonte.github.io/haproxy-dconv/configuration-1.4.html#3.4 for more info # -# See http://cbonte.github.io/haproxy-dconv/configuration-1.4.html#3.4 for more info +# @note +# Currently requires the puppetlabs/concat module on the Puppet Forge # -# === Requirement/Dependencies: # -# Currently requires the puppetlabs/concat module on the Puppet Forge -# -# === Parameters -# -# [*section_name*] +# @param section_name # This name goes right after the 'userlist' statement in haproxy.cfg # Default: $name (the namevar of the resource). # -# [*users*] +# @param users # An array of users in the userlist. # See http://cbonte.github.io/haproxy-dconv/configuration-1.4.html#3.4-user # -# [*groups*] +# @param groups # An array of groups in the userlist. # See http://cbonte.github.io/haproxy-dconv/configuration-1.4.html#3.4-group # -# [*config_file*] +# @param config_file # Optional. Path of the config file where this entry will be added. # Assumes that the parent directory exists. # Default: $haproxy::params::config_file +# +# @param instance +# Optional. Defaults to 'haproxy' # # === Authors #