5abacbd0031f247887d5cb4693a426ffe6e73619
[puppet_haproxy.git] / README.md
1 PuppetLabs Module for haproxy
2 =============================
3
4 HAProxy is an HA proxying daemon for load-balancing to clustered services. It
5 can proxy TCP directly, or other kinds of traffic such as HTTP.
6
7 Basic Usage
8 -----------
9
10 This haproxy uses storeconfigs to collect and realize balancer member servers
11 on a load balancer server. 
12
13 *To install and configure HAProxy server listening on port 8140*
14
15 ```puppet
16 node 'haproxy-server' {
17   class { 'haproxy': }
18   haproxy::listen { 'puppet00':
19     ipaddress => $::ipaddress,
20     ports     => '8140',
21   }
22 }
23 ```
24
25 *To add backend loadbalance members*
26
27 ```puppet
28 node 'webserver01' {
29   @@haproxy::balancermember { $fqdn:
30     listening_service => 'puppet00',
31     server_names      => $::hostname,
32     ipaddresses       => $::ipaddress,
33     ports             => '8140',
34     options           => 'check'
35   }
36 }
37 ```
38
39 Configuring haproxy options
40 ---------------------------
41
42 The base `haproxy` class can accept two parameters which will configure basic
43 behaviour of the haproxy server daemon:
44
45 - `global_options` to configure the `global` section in `haproxy.cfg`
46 - `defaults_options` to configure the `defaults` section in `haproxy.cfg`
47
48 Configuring haproxy daemon listener
49 -----------------------------------
50
51 One `haproxy::listen` defined resource should be defined for each HAProxy loadbalanced set of backend servers. The title of the `haproxy::listen` resource is the key to which balancer members will be proxied to. The `ipaddress` field should be the public ip address which the loadbalancer will be contacted on. The `ports` attribute can accept an array or comma-separated list of ports which should be proxied to the `haproxy::balancermemeber` nodes.
52
53 Configuring haproxy loadbalanced member nodes
54 ---------------------------------------------
55
56 The `haproxy::balacemember` defined resource should be exported from each node
57 which is serving loadbalanced traffic. the `listening_service` attribute will
58 associate it with `haproxy::listen` directives on the haproxy node.
59 `ipaddresses` and `ports` will be assigned to the member to be contacted on. If an array of `ipaddresses` and `server_names` are provided then they will be added to the config in lock-step.
60
61 Dependencies
62 ------------
63
64 Tested and built on Ubuntu and CentOS
65
66 Currently requires the ripienaar/concat module on the Puppet Forge and uses storeconfigs on the Puppet Master to export/collect resources
67 from all balancer members.
68
69 Copyright and License
70 ---------------------
71
72 Copyright (C) 2012 [Puppet Labs](https://www.puppetlabs.com/) Inc
73
74 Puppet Labs can be contacted at: info@puppetlabs.com
75
76 Licensed under the Apache License, Version 2.0 (the "License");
77 you may not use this file except in compliance with the License.
78 You may obtain a copy of the License at
79
80   http://www.apache.org/licenses/LICENSE-2.0
81
82 Unless required by applicable law or agreed to in writing, software
83 distributed under the License is distributed on an "AS IS" BASIS,
84 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
85 See the License for the specific language governing permissions and
86 limitations under the License.