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