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

Update README.md

Browse source
This commit is contained in:
Joao M 2022-08-17 09:59:18 -05:00 • committed by GitHub
parent 48e5ea340f
commit c96f7362ea
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 36 additions and 35 deletions
Download patch file Download diff file Expand all files Collapse all files

71
README.md
View file

@ -8,26 +8,26 @@
Service discovery for HAProxy. Service discovery for HAProxy.
This Docker image will create dynamically the `haproxy.cfg` based on the labels defined in docker containers or from This Docker image will dynamically create the `haproxy.cfg` based on the labels defined in docker containers or from
a simple Yaml. a simple Yaml.
## Features ## Features
EasyHAProxy will discover the services based on the Docker Tags of the running containers in a Docker host or Docker Swarm cluster and setup the `haproxy.cfg` dynamically. The configurations can be set are: EasyHAProxy will discover the services based on the Docker Tags of the running containers in a Docker host or Docker Swarm cluster and dynamically set up the `haproxy.cfg`. Below, EasyHAProxy main features::
- Use Letsencrypt with HAProxy. - Use Letsencrypt with HAProxy.
- Balance traffic between multiple replicas - Balance traffic between multiple replicas
- Set SSL according the most recent definitions to improve security and with - Set SSL with three different levels of validations and according to the most recent definitions.
- Include your own SSL certificate. - Include your SSL certificate.
- Setup HAProxy to listen TCP. - Setup HAProxy to listen to TCP.
- Add redirects. - Add redirects.
- Enable/disable Stats on port 1936 with custom password. - Enable/disable Stats on port 1936 with a custom password.
- Enable/disable custom errors. - Enable/disable custom errors.
Also it is possible setup HAProxy from a simple Yaml file instead of setup `haproxy.cfg` dynamically. Also, it is possible to set up HAProxy from a simple Yaml file instead of creating `haproxy.cfg` file.
## Basic Usage ## Basic Usage
The Easy HAProxy will create the `haproxy.cfg` automatically based on the containers or from a YAML provided. The Easy HAProxy will automatically create the `haproxy.cfg` file based on the containers or a YAML provided.
The basic command line to run is: The basic command line to run is:
@ -48,15 +48,15 @@ The environment variables will setup the HAProxy.
| Environment Variable | Description | | Environment Variable | Description |
|-------------------------------|-------------------------------------------------------------------------------| |-------------------------------|-------------------------------------------------------------------------------|
| EASYHAPROXY_DISCOVER | How `haproxy.cfg` will be created: `static`, `docker` or `swarm` | | EASYHAPROXY_DISCOVER | How `haproxy.cfg` will be created: `static`, `docker` or `swarm` |
| EASYHAPROXY_LABEL_PREFIX | (Optional) The key will search to match resources. Default: `easyhaproxy`. | | EASYHAPROXY_LABEL_PREFIX | (Optional) The key will search for matching resources. Default: `easyhaproxy`. |
| EASYHAPROXY_LETSENCRYPT_EMAIL | (Optional) The email will be used to request certificate to letsencrypt | | EASYHAPROXY_LETSENCRYPT_EMAIL | (Optional) The email will be used to request the certificate to Letsencrypt |
| EASYHAPROXY_SSL_MODE | (Optional) `STRICT` supports only the most recent TLS version; `DEFAULT` good SSL integration with recent browsers; `LOOSE` support all old SSL protocols for old browsers (not recommended). | | EASYHAPROXY_SSL_MODE | (Optional) `STRICT` supports only the most recent TLS version; `DEFAULT` good SSL integration with recent browsers; `LOOSE` supports all old SSL protocols for old browsers (not recommended). |
| HAPROXY_USERNAME | (Optional) The HAProxy username to the statistics. Default: `admin` | | HAPROXY_USERNAME | (Optional) The HAProxy username to the statistics. Default: `admin` |
| HAPROXY_PASSWORD | The HAProxy password to the statistics. If not set disable stats. | | HAPROXY_PASSWORD | The HAProxy password to the statistics. If not set, it will disable stats. |
| HAPROXY_STATS_PORT | (Optional) The HAProxy port to the statistics. Default: `1936` | | HAPROXY_STATS_PORT | (Optional) The HAProxy port to the statistics. Default: `1936` |
| HAPROXY_CUSTOMERRORS | (Optional) If HAProxy will use custom HTML errors. true/false. Default: false | | HAPROXY_CUSTOMERRORS | (Optional) If HAProxy will use custom HTML errors. true/false. Default: false |
The environment variable `EASYHAPROXY_DISCOVER` will define where is located your containers (see below more details): The environment variable `EASYHAPROXY_DISCOVER` will define where is located your containers (see below for more details):
- docker - docker
- swarm - swarm
@ -64,15 +64,15 @@ The environment variable `EASYHAPROXY_DISCOVER` will define where is located you
## Automatic Discover Services ## Automatic Discover Services
Easy HAProxy can discover automatically the container services running in the same network of Docker or in a Docker Swarm cluster. Easy HAProxy can automatically discover the container services running in the same network of Docker or in a Docker Swarm cluster.
### EASYHAPROXY_DISCOVER: docker ### EASYHAPROXY_DISCOVER: docker
This method will use a regular docker installation to discover the containers and configure the HAProxy. This method will use a standard 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 only requirement is that containers and easy-haproxy must be in the same docker network.
The discover will occur every minute. The discovery will occur every minute.
e.g.: e.g.:
@ -89,11 +89,11 @@ docker run --network easyhaproxy myimage
This method requires a functional Docker Swarm Cluster. The system will search for the labels in all containers on all This method requires a functional Docker Swarm Cluster. The system will search for the labels in all containers on all
swarm nodes. swarm nodes.
The discover will occur every minute. The discovery will occur every minute.
Important: easyhaproxy needs to be in the same network of the containers or otherwise will not access. 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 (Swarm or Docker) ### Docker Container (Swarm or Docker) tags:
| Tag | Description | Example | | Tag | Description | Example |
|---------------------------------------|---------------------------------------------------------------------------------------------------------|--------------| |---------------------------------------|---------------------------------------------------------------------------------------------------------|--------------|
@ -101,7 +101,7 @@ Important: easyhaproxy needs to be in the same network of the containers or othe
| easyhaproxy.[definition].mode | (Optional) Is this `http` or `tcp` mode in HAProxy. (Defaults to http) | http | | easyhaproxy.[definition].mode | (Optional) Is this `http` or `tcp` mode in HAProxy. (Defaults to http) | http |
| easyhaproxy.[definition].port | (Optional) Port HAProxy will listen for the host. (Defaults to 80) | 80 | | easyhaproxy.[definition].port | (Optional) Port HAProxy will listen for the host. (Defaults to 80) | 80 |
| easyhaproxy.[definition].localport | (Optional) Port container is listening. (Defaults to 80) | 8080 | | easyhaproxy.[definition].localport | (Optional) Port container is listening. (Defaults to 80) | 8080 |
| easyhaproxy.[definition].redirect | (Optional) JSON containing key/value pair from host/to url redirect. | {"foo.com":"https://bla.com", "bar.com":"https://bar.org"} | | easyhaproxy.[definition].redirect | (Optional) JSON containing key/value pair from host/to URL redirect. | {"foo.com":"https://bla.com", "bar.com":"https://bar.org"} |
| easyhaproxy.[definition].sslcert | (Optional) Cert PEM Base64 encoded. Do not use this if letsencrypt is enabled. | | | easyhaproxy.[definition].sslcert | (Optional) Cert PEM Base64 encoded. Do not use this if letsencrypt is enabled. | |
| easyhaproxy.[definition].ssl | (Optional) If `true` you need to provide certificate as a file. See below. Do not use with `sslcert`. | true | | easyhaproxy.[definition].ssl | (Optional) If `true` you need to provide certificate as a file. See below. Do not use with `sslcert`. | true |
| easyhaproxy.[definition].health-check | (Optional) `ssl`, enable health check via SSL in `mode tcp` (Defaults to "empty") | ssl | | easyhaproxy.[definition].health-check | (Optional) `ssl`, enable health check via SSL in `mode tcp` (Defaults to "empty") | ssl |
@ -110,7 +110,7 @@ Important: easyhaproxy needs to be in the same network of the containers or othe
### Defining the labels in Docker Swarm ### Defining the labels in Docker Swarm
if you are deploying a stack in a Docker Swarm cluster set labels at the `deploy` level: if you are deploying a stack in a Docker Swarm cluster, set labels at the `deploy` level:
```yaml ```yaml
services: services:
@ -148,7 +148,7 @@ docker run \
### TLS passthrough ### TLS passthrough
Used to pass on SSL-termination to a backend. Alternatively, you can enable health-check via SSL on the backend with the optional `health-check` label: Used to pass on SSL termination to a backend. Alternatively, you can enable health-check via SSL on the backend with the optional `health-check` label:
```bash ```bash
docker run \ docker run \
@ -244,15 +244,17 @@ Caveats:
- Your container **must** listen to the port 80. Besides no error, the certificate won't be issued if in a different port. - Your container **must** listen to the port 80. Besides no error, the certificate won't be issued if in a different port.
- The port 2080 is reserved for the certbot and should not be exposed. - The port 2080 is reserved for the certbot and should not be exposed.
- You cannot set the port 443 for the container with the Letsencrypt. EasyHAProxy will handle this automatically once the certificate is issued. - You cannot set the port 443 for the container with the Letsencrypt because EasyHAProxy will handle this automatically once the certificate is issued.
- If you don't run the EasyHAProxy with the parameter `EASYHAPROXY_LETSENCRYPT_EMAIL` no certificate will be issued. - If you don't run the EasyHAProxy with the parameter `EASYHAPROXY_LETSENCRYPT_EMAIL` no certificate will be issued.
- Be aware about issue limits - https://letsencrypt.org/docs/duplicate-certificate-limit/ and https://letsencrypt.org/docs/rate-limits/ - Be aware of Letsencrypt issue limits - https://letsencrypt.org/docs/duplicate-certificate-limit/ and https://letsencrypt.org/docs/rate-limits/
## Exposing Ports ## Exposing Ports
- You need to expose at least the ports `80` and `443` when you run the `byjg/easy-haproxy` image. You must expose some ports on the EasyHAProxy container and in the firewall. However, you don't need to expose the other container ports because EasyHAProxy will handle that.
- If you enable the HAProxy statistics you must also expose the port defined in `HAPROXY_STATS_PORT` environment variable.
- Every port defined in `easyhaproxy.[definitions].port` also should be enabel. - The ports `80` and `443`.
- If you enable the HAProxy statistics, you must also expose the port defined in `HAPROXY_STATS_PORT` environment variable.
- Every port defined in `easyhaproxy.[definitions].port` also should be exposed.
e.g. e.g.
@ -265,11 +267,10 @@ docker run \
-d byjg/easy-haproxy -d byjg/easy-haproxy
``` ```
Also, you need to expose these ports in the firewall.
## Mapping custom .cfg files ## Mapping custom .cfg files
Map a folder containing valid HAProxy `.cfg` files to `/etc/haproxy/conf.d`. It will be concatenated to your HAProxy CFG. You can concatenate valid HAProxy `.cfg` files to the dynamically generated `haproxy.cfg` by mapping the folder `/etc/haproxy/conf.d`.
```bash ```bash
docker run \ docker run \
@ -278,11 +279,11 @@ docker run \
-d byjg/easy-haproxy -d byjg/easy-haproxy
``` ```
## Mapping ssl certificates volumes ## Mapping SSL certificates volumes
EasyHAProxy stores the certificates inside the folder `/certs/haproxy` and `/certs/letsencrypt`. EasyHAProxy stores the certificates inside the folder `/certs/haproxy` and `/certs/letsencrypt`.
- If you want to preserve the letsencrypt certificates between reloads, just map the folder `/certs/letsencrypt` to your volume. - If you want to preserve the letsencrypt certificates between reloads, map the folder `/certs/letsencrypt` to your volume.
- If you want to provide your own certificates as a file instead a Base64 parameter, just map the folder `/certs/haproxy` to your volume and instead of use `easyhaproxy.[definition].sslcert` use `easyhaproxy.[definition].ssl: true` - If you want to provide your certificates as a file instead of a Base64 parameter, map the folder `/certs/haproxy` to your volume, and instead of use `easyhaproxy.[definition].sslcert`, use `easyhaproxy.[definition].ssl: true`
```bash ```bash
docker run \ docker run \
@ -295,7 +296,7 @@ docker run \
You can attach a valid SSL certificate to the request. You can attach a valid SSL certificate to the request.
1. First Create a single PEM file including CA. 1. First, Create a single PEM file including CA.
```bash ```bash
cat example.com.crt example.com.key > single.pem cat example.com.crt example.com.key > single.pem
@ -324,7 +325,7 @@ cat single.pem | base64 -w0
## Setting Custom Errors ## Setting Custom Errors
If enabled, map the volume : `/etc/haproxy/errors-custom/` to your container and put a file named `ERROR_NUMBER.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) where ERROR_NUMBER is the HTTP error code (e.g., `503.http`)
## Build ## Build
@ -336,8 +337,8 @@ docker build -t byjg/easy-haproxy .
## Limitations ## Limitations
EasyHAProxy has some limitations when there is more than one easy-haproxy container running: EasyHAProxy has some limitations when there is more than one easy-haproxy container running:
- Replicas can be out-of-sync for a few seconds, because each replica will discover the pods separatedly. - Replicas can be out-of-sync for a few seconds because each replica will discover the pods separately.
- Each replica will request a Letsencrypt certificate and it can fail because the letsencrypt challenge can be directed to the other replica. - Each replica will request a Letsencrypt certificate and can fail because the letsencrypt challenge can be directed to the other replica.
---- ----
[Open source ByJG](http://opensource.byjg.com) [Open source ByJG](http://opensource.byjg.com)