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

Update documentation and examples

Browse source 
- Improved container labels documentation formatting and fixed typos.
- Clarified static discovery mode requirements in static.md.
- Updated Kubernetes annotations explanations.
- Enhanced README.md with details about supported platforms and features.
- Bumped Swarm example image to version 4.6.0.
This commit is contained in:
Joao Gilberto Magalhaes 2025-11-10 16:36:05 -05:00
parent aee9645b43
commit facbaaabb6
5 changed files with 18 additions and 14 deletions
Download patch file Download diff file Expand all files Collapse all files

11
README.md
View file

@ -11,18 +11,19 @@
## Service discovery for HAProxy ## Service discovery for HAProxy
EasyHAProxy dynamically creates the `haproxy.cfg` based on the labels defined in docker containers. EasyHAProxy dynamically creates the `haproxy.cfg` based on metadata collected from your workloads (Docker labels, Swarm service labels, or Kubernetes ingress annotations).
EasyHAProxy can detect and configure HAProxy automatically on the following platforms: EasyHAProxy can detect and configure HAProxy automatically on the following platforms:
- Docker - Docker
- Docker Swarm - Docker Swarm
- Kubernetes - Kubernetes
- Static YAML definitions (`EASYHAPROXY_DISCOVER=static`)
## Who is using? ## Who is using?
EasyHAProxy is part of some projects: EasyHAProxy is part of some projects:
- Dokku - Dokku
- MicroK8s - MicroK8s
- DigitalOcean Marketplace - DigitalOcean Marketplace
@ -34,12 +35,12 @@ Easy to set up and low configuration to numerous features.
## Features ## Features
EasyHAProxy will discover the services based on the Docker Tags of the containers running on a Docker host or Docker Swarm cluster and dynamically set up the `haproxy.cfg`. Below, EasyHAProxy main features: EasyHAProxy will discover services based on Docker (or Swarm) labels and Kubernetes ingress annotations, then dynamically build the `haproxy.cfg`. Below, EasyHAProxy main features:
- Support Automatic Certificate Management Environment (ACME) protocol compatible with Let's encrypt and others CA. - Support Automatic Certificate Management Environment (ACME) protocol compatible with Let's Encrypt and other CAs.
- Set your custom SSL certificates - Set your custom SSL certificates
- Balance traffic between multiple replicas - Balance traffic between multiple replicas
- Set SSL with three different levels of validations and according to the most recent definitions. - Set SSL policies (`strict`, `default`, `loose`) via `EASYHAPROXY_SSL_MODE`.
- Set up HAProxy to listen to TCP. - Set up HAProxy to listen to TCP.
- Add redirects. - Add redirects.
- Enable/disable Stats on port 1936 with a custom password. - Enable/disable Stats on port 1936 with a custom password.

8
docs/container-labels.md
View file

@ -6,7 +6,7 @@ sidebar_position: 11
## Container (Docker or Swarm) labels ## Container (Docker or Swarm) labels
| Tag | Description | Default | Example | | Label | Description | Default | Example |
|---------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|--------------|------------------------------------------------------------------------------------------------------------------| |---------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|--------------|------------------------------------------------------------------------------------------------------------------|
| easyhaproxy.[definition].host | Host(s) HAProxy is listening. More than one host use comma as delimiter | **required** | somehost.com OR host1.com,host2.com | | easyhaproxy.[definition].host | Host(s) HAProxy is listening. More than one host use comma as delimiter | **required** | somehost.com OR host1.com,host2.com |
| easyhaproxy.[definition].mode | (Optional) Is this `http` or `tcp` mode in HAProxy. | http | http or tcp | | easyhaproxy.[definition].mode | (Optional) Is this `http` or `tcp` mode in HAProxy. | http | http or tcp |
@ -18,7 +18,7 @@ sidebar_position: 11
| easyhaproxy.[definition].ssl-check | (Optional) `ssl`, enable health check via SSL in `mode tcp` | *empty* | ssl | | easyhaproxy.[definition].ssl-check | (Optional) `ssl`, enable health check via SSL in `mode tcp` | *empty* | ssl |
| easyhaproxy.[definition].certbot | (Optional) Generate certificate with certbot. Do not use with `sslcert` parameter. More info [here](acme.md). | false | true OR false | | easyhaproxy.[definition].certbot | (Optional) Generate certificate with certbot. Do not use with `sslcert` parameter. More info [here](acme.md). | false | true OR false |
| easyhaproxy.[definition].redirect_ssl | (Optional) Redirect all requests to https | false | true OR false | | easyhaproxy.[definition].redirect_ssl | (Optional) Redirect all requests to https | false | true OR false |
| easyhaproxy.[definition].clone_to_ssl | (Optional) It copies the configuration to HTTPS(443) and disable SSL from the current config. **Do not use* this with `ssl` or `certbot` parameters | false | true OR false | | easyhaproxy.[definition].clone_to_ssl | (Optional) It copies the configuration to HTTPS(443) and disable SSL from the current config. **Do not use** this with `ssl` or `certbot` parameters | false | true OR false |
| easyhaproxy.[definition].balance | (Optional) HAProxy balance algorithm. See [HAProxy documentation](https://cbonte.github.io/haproxy-dconv/1.8/configuration.html#4.2-balance) | roundrobin | roundrobin, source, uri, url_param, hdr, rdp-cookie, leastconn, first, static-rr, rdp-cookie, hdr_dom, map-based | | easyhaproxy.[definition].balance | (Optional) HAProxy balance algorithm. See [HAProxy documentation](https://cbonte.github.io/haproxy-dconv/1.8/configuration.html#4.2-balance) | roundrobin | roundrobin, source, uri, url_param, hdr, rdp-cookie, leastconn, first, static-rr, rdp-cookie, hdr_dom, map-based |
:::info Understanding Definitions :::info Understanding Definitions
@ -27,7 +27,7 @@ The `[definition]` is a string identifier that groups related configuration labe
A single container can have multiple definitions to expose different services or ports. A single container can have multiple definitions to expose different services or ports.
::: :::
## Configuations ## Configurations
### Single Definition ### Single Definition
@ -101,4 +101,4 @@ docker run \
``` ```
---- ----
[Open source ByJG](http://opensource.byjg.com) [Open source ByJG](http://opensource.byjg.com)

4
docs/kubernetes.md
View file

@ -97,7 +97,7 @@ You don't need to expose any port in your container.
| easyhaproxy.certbot | (optional) Boolean. It will request certbot certificates for the ingresses domains. | false | true or false | | easyhaproxy.certbot | (optional) Boolean. It will request certbot certificates for the ingresses domains. | false | true or false |
| easyhaproxy.redirect | (optional) JSON. Key pair with a domain and its destination. | *empty* | \{"domain":"redirect_url"} | | easyhaproxy.redirect | (optional) JSON. Key pair with a domain and its destination. | *empty* | \{"domain":"redirect_url"} |
| easyhaproxy.mode | (optional) Set the HTTP mode for that connection. | http | http or tcp | | easyhaproxy.mode | (optional) Set the HTTP mode for that connection. | http | http or tcp |
| easyhaproxy.listen_port | (optional) Set the an additional port for that ingress | http | http or tcp | | easyhaproxy.listen_port | (optional) Override the HTTP listen port created for that ingress | 80 | 8081 |
**Important**: The annotations are per ingress and applied to all hosts in that ingress configuration. **Important**: The annotations are per ingress and applied to all hosts in that ingress configuration.
@ -155,4 +155,4 @@ spec:
``` ```
---- ----
[Open source ByJG](http://opensource.byjg.com) [Open source ByJG](http://opensource.byjg.com)

7
docs/static.md
View file

@ -67,7 +67,6 @@ Then map this file to `/etc/haproxy/static/config.yml` in your EasyHAProxy conta
```bash title="Run EasyHAProxy with static configuration" ```bash title="Run EasyHAProxy with static configuration"
docker run -d \ docker run -d \
--name easy-haproxy-container \ --name easy-haproxy-container \
-v /var/run/docker.sock:/var/run/docker.sock \
-v /my/static/:/etc/haproxy/static/ \ -v /my/static/:/etc/haproxy/static/ \
-e EASYHAPROXY_DISCOVER="static" \ -e EASYHAPROXY_DISCOVER="static" \
# + Environment Variables \ # + Environment Variables \
@ -78,7 +77,11 @@ docker run -d \
byjg/easy-haproxy byjg/easy-haproxy
``` ```
You can find other informations on [docker label configuration](container-labels.md) and [environment variable guide](environment-variable.md) :::tip Docker Socket Optional
Mounting `/var/run/docker.sock` is not required in static discovery mode. Add it only if you are simultaneously discovering Docker containers.
:::
You can find other information on [docker label configuration](container-labels.md) and [environment variable guide](environment-variable.md)
## Yaml Definition ## Yaml Definition

2
docs/swarm.md
View file

@ -35,7 +35,7 @@ version: "3"
services: services:
haproxy: haproxy:
image: byjg/easy-haproxy:4.3.1-rc1 image: byjg/easy-haproxy:4.6.0
volumes: volumes:
- /var/run/docker.sock:/var/run/docker.sock - /var/run/docker.sock:/var/run/docker.sock
deploy: deploy: