← Back to branch summary

~dpb/charms/trusty/haproxy/merge-services-fix

« back to all changes in this revision

Viewing changes to README.md

  • Committer: Jorge O. Castro
  • Date: 2014-01-07 19:03:41 UTC
  • Revision ID: jorge@ubuntu.com-20140107190341-083497xm4zpuff6g
README updates as part of charm audit.

Show diffs side-by-side

added added

removed removed

Lines of Context:
README.md
1
 
Juju charm for HAProxy
2
 
======================
3
 
 
4
 
HAProxy is a free, very fast and reliable solution offering high availability,
5
 
load balancing, and proxying for TCP and HTTP-based applications. It is
6
 
particularly suited for web sites crawling under very high loads while needing
7
 
persistence or Layer7 processing. Supporting tens of thousands of connections
8
 
is clearly realistic with todays hardware. Its mode of operation makes its
9
 
integration into existing architectures very easy and riskless, while still
10
 
offering the possibility not to expose fragile web servers to the Net.
11
 
 
12
 
Development
13
 
-----------
14
 
The following steps are needed for testing and development of the charm,
15
 
but **not** for deployment:
16
 
 
17
 
    sudo apt-get install python-software-properties
18
 
    sudo add-apt-repository ppa:cjohnston/flake8
19
 
    sudo apt-get update
20
 
    sudo apt-get install python-mock python-flake8 python-nose python-nosexcover
21
 
 
22
 
To run the tests:
23
 
 
24
 
    make build
25
 
 
26
 
... will run the unit tests, run flake8 over the source to warn about
27
 
formatting issues and output a code coverage summary of the 'hooks.py' module.
28
 
 
29
 
How to deploy the charm
30
 
-----------------------
 
1
# Overview
 
2
 
 
3
This charm deploys a reverse proxy in front of other servies. You can use this to load balance existing deployments.
 
4
 
 
5
# Usage
 
6
 
31
7
    juju deploy haproxy
32
8
    juju deploy my-web-app
33
9
    juju add-relation my-web-app:website haproxy:reverseproxy
34
10
    juju add-unit my-web-app
35
11
    ...
36
12
 
37
 
Reverseproxy Relation
38
 
---------------------
 
13
## Reverse Proxy Relation
39
14
 
40
15
The reverse proxy relation is used to distribute connections from one frontend
41
16
port to many backend services (typically different Juju _units_).  You can use
47
22
which can be used to notify haproxy about what services you are running.
48
23
1) Single-service proxying or 2) Multi-service or relation-driven proxying.
49
24
 
50
 
** 1) Single-Service Proxying **
 
25
1. Single-Service Proxying
51
26
 
52
27
In this case, your website relation will join underneath a single `listen`
53
28
stanza in haproxy.  This stanza will have one `service` entry for each unit
76
51
    set each item as an option under the listen stanza.
77
52
 
78
53
 
79
 
** 2) Relation-Driven Proxying **
 
54
2. Relation-Driven Proxying 
80
55
 
81
56
In this relation style, your charm should specify these relation settings
82
57
directly as relation variables when joining reverseproxy.  Your charm's
101
76
`service-options` and `server_options` will be overwritten, so ensure they
102
77
are set uniformly on all services with the same name.
103
78
 
104
 
Website Relation
105
 
----------------
 
79
## Website Relation
 
80
 
106
81
 
107
82
The website relation is the other side of haproxy.  It can communicate with
108
83
charms written like apache2 that can act as a front-end for haproxy to take of
114
89
traffic goes to the correct haproxy listener which will in turn forward the
115
90
traffic to the correct backend server/port
116
91
 
117
 
Configuration
118
 
-------------
 
92
## Development
 
93
 
 
94
The following steps are needed for testing and development of the charm,
 
95
but **not** for deployment:
 
96
 
 
97
    sudo apt-get install python-software-properties
 
98
    sudo add-apt-repository ppa:cjohnston/flake8
 
99
    sudo apt-get update
 
100
    sudo apt-get install python-mock python-flake8 python-nose python-nosexcover
 
101
 
 
102
To run the tests:
 
103
 
 
104
    make build
 
105
 
 
106
... will run the unit tests, run flake8 over the source to warn about
 
107
formatting issues and output a code coverage summary of the 'hooks.py' module.
 
108
 
 
109
 
 
110
## Known Limitations and Issues
 
111
 
 
112
- Expand Single-Service section as I have not tested that mode fully.
 
113
- Trigger website-relation-changed when the reverse-proxy relation changes
 
114
 
 
115
 
 
116
# Configuration
 
117
 
119
118
Many of the haproxy settings can be altered via the standard juju configuration
120
119
settings.  Please see the config.yaml file as each is fairly clearly documented.
121
120
 
122
 
TODO:
123
 
-----
 
121
## HAProxy Project Information
124
122
 
125
 
  * Expand Single-Service section as I have not tested that mode fully.
126
 
  * Trigger website-relation-changed when the reverse-proxy relation changes
 
123
- [HAProxy Homepage](http://haproxy.1wt.eu/)
 
124
- [HAProxy mailing list](http://haproxy.1wt.eu/#tact)