badblocks/docker-easy-haproxy
1
0
Fork 0
Code Activity

Update Documentation

Browse source
This commit is contained in:
Joao Gilberto Magalhaes 2019-07-17 23:39:14 -05:00
parent b7ec691e8f
commit 174dc4ac9f
2 changed files with 126 additions and 63 deletions
Download patch file Download diff file Expand all files Collapse all files

186
README.md
View file

@ -1,50 +1,93 @@
# Easy HAProxy
This Docker image will create dynamically the `haproxy.cfg` based on very simple Yaml.
This Docker image will create dynamically the `haproxy.cfg` based on the labels defined in docker containers or from
a simple Yaml instead docker
# Features
- Enable or disable Stats on port 1936 with custom password
- Discover and setup haproxy from Docker Tag
- Discover and setup haproxy redirect from Docker Tag
- Setup HAProxy CFG from a Yaml file.
# Basic Usage
Docker run:
The Easy HAProxy will create the `haproxy.cfg` automatically based on the containers or from a YAML provided.
The basic command line to run is:
```bash
docker run \
-p 80:80 \
-p 8080:8080 \
-p 1936:1936 \
--name easy-haproxy-instance \
-e DISCOVER=swarm \
-e HAPROXY_USERNAME=admin \
-e HAPROXY_PASSWORD=password \
-e HAPROXY_STATS_PORT=1936 \
docker run -d \
--name easy-haproxy-container \
-v /var/run/docker.sock:/var/run/docker.sock \
-d byjg/easy-haproxy
# + Environment Variables \
# + ports mapped to the host \
byjg/easy-haproxy
```
The `DISCOVER` environment variable will define where is located your containers (see below more details):
- swarm
- static (maps to /etc/haproxy/easyconfig.yml)
The mapping to `/var/run/docker.sock` is necessary to discover the docker containers and get the labels;
# Tags to defined:
The environment variables will setup the HAProxy.
| Environment Variable | Description |
|----------------------|------------------------------------------------------------------|
| DISCOVER | How `haproxy.cfg` will be created: `static`, `docker` or `swarm` |
| HAPROXY_USERNAME | The HAProxy username to the statistics |
| HAPROXY_PASSWORD | The HAProxy password to the statistics |
| HAPROXY_STATS_PORT | The HAProxy port to the statistics |
| HAPROXY_CUSTOMERRORS | If HAProxy will use custom HTML errors. true/false |
The environment variable `DISCOVER` will define where is located your containers (see below more details):
- docker
- swarm
- static
# DISCOVER: `docker`
This method will use a regular docker installation to discover the containers and configure the HAProxy.
The only requirement is that containers and easy-haproxy must be in the same docker network.
The discover will occur every minute.
e.g.:
```bash
docker create networkd easyhaproxy
docker run --network easyhaproxy byjg/easyhaproxy
docker run --network easyhaproxy myimage
```
# DISCOVER: `swarm`
This method requires a functional Docker Swarm Cluster. The system will search for the labels in all containers on all
swarm nodes.
The discover will occur every minute.
Important: easyhaproxy needs to be in the same network of the containers or otherwise will not access.
## Tags to be attached in the Docker Container
| Tag | Description |
|---------------------------------------------|---------------------------------------------------------------------------------------------------------|
| com.byjg.easyhaproxy.definitions | A Comma delimited list with the definitions. Each name requires the definition of the parameters below. |
| com.byjg.easyhaproxy.port.<definition> | What is the port that the HAProxy will listen to. |
| com.byjg.easyhaproxy.localport.<definition> | What is the port that the container is listening. |
| com.byjg.easyhaproxy.host.<definition> | What is the host that the HAProxy will listen to. (Defaults to 80) |
| com.byjg.easyhaproxy.localport.<definition> | What is the port that the container is listening. (Defaults to 80) |
| com.byjg.easyhaproxy.host.<definition> | What is the host that the HAProxy will listen to. |
| com.byjg.easyhaproxy.redirect.<definition> | Host redirects from connections in the port defined above. |
| com.byjg.easyhaproxy.sslcert.<definition> | Cert PEM Base64 encoded. |
E.g.
```
### Single Definition:
```bash
docker run \
-l com.byjg.easyhaproxy.definitions=http \
-l com.byjg.easyhaproxy.port.http=80\
@ -52,16 +95,70 @@ docker run \
....
```
## Redirect Example:
### Multiples Definitions on the same container:
```text
www.byjg.com.br=>http://byjg.com.br,byjg.com=>http://byjg.com.br
```bash
docker run \
-l com.byjg.easyhaproxy.definitions=express,admin \
-l com.byjg.easyhaproxy.port.express=80 \
-l com.byjg.easyhaproxy.localport.express=3000 \
-l com.byjg.easyhaproxy.host.express=express.byjg.com.br \
-l com.byjg.easyhaproxy.port.admin=80 \
-l com.byjg.easyhaproxy.localport.admin=3001 \
-l com.byjg.easyhaproxy.host.admin=admin.byjg.com.br \
....
```
### Redirect Example:
```bash
docker run \
-l com.byjg.easyhaproxy.redirect.<defintion>=www.byjg.com.br::http://byjg.com.br,byjg.com::http://byjg.com.br
```
# DISCOVER: `static`
This method expects a YAML file to setup the `haproxy.cfg`
Create a YAML file and map to `/etc/haproxy/easyconfig.yml`
```yaml
stats:
username: admin
password: password
port: 1936 # Optional (default 1936)
customerrors: true # Optional (default false)
easymapping:
- port: 80
hosts:
host1.com.br: container:5000
host2.com.br: other:3000
redirect:
www.host1.com.br: http://host1.com.br
- port: 443
ssl_cert: BASE64_PEM_CERTIFICATE
hosts:
host1.com.br: container:80
- port: 8080
hosts:
host3.com.br: domain:8181```
```
Running:
```bash
docker run -v /my/config.yml:/etc/haproxy/easyconfig.yml .... byjg/easyhaproxy
```
# Mapping custom .cfg files
Just create a folder and put files with the extension .cfg. and map the volume to the container.
This will concatenate your config into the main haproxy.cfg
Map a folder containing valid HAProxy `.cfg` files to `/etc/haproxy/conf.d`. It will be concatenated to your HAProxy CFG.
```bash
docker run \
@ -70,29 +167,6 @@ docker run \
-d byjg/easy-haproxy
```
Check if your config is ok:
```bash
docker run \
/* other parameters */
-v /your/local/conf.d:/etc/haproxy/conf.d \
-byjg/easy-haproxy -c -f /etc/haproxy/haproxy.cfg
```
# Docker Compose
```yaml
version: "3.4"
services:
front:
image: byjg/easy-haproxy
volume:
- /path/to/local:/etc/easyconfig
ports:
- 80:80
- 8080:8080
- 1936:1936
```
# Handling SSL
@ -110,8 +184,8 @@ Important: Different certificates need to be handled in different entries.
# Setting Custom Errors
Map the volume : `/etc/haproxy/errors-custom/` and put a file named `ERROR_NUMBER.http` where ERROR_NUMBER
is the http error code (e.g. 503.http)
If enabled, map the volume : `/etc/haproxy/errors-custom/` to your container and put a file named `ERROR_NUMBER.http`
where ERROR_NUMBER is the http error code (e.g. 503.http)
# Build
@ -120,17 +194,3 @@ docker build -t byjg/easy-haproxy .
```
# Docker Swarm
# AWS
Easy HAProxy will try to get tasks from the tasks running in the CLUSTER.
It is important that easy haproxy run in the ECS Cluster and can connect to the containers.
You'll have to pass also the `AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY` or setup a role in the instance in order and
the `ECS_CLUSTER` with the arn of the cluster