From facbaaabb6ce463b017d73943bace9174285d23b Mon Sep 17 00:00:00 2001 From: Joao Gilberto Magalhaes Date: Mon, 10 Nov 2025 16:36:05 -0500 Subject: [PATCH] Update documentation and examples - 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. --- README.md | 11 ++++++----- docs/container-labels.md | 8 ++++---- docs/kubernetes.md | 4 ++-- docs/static.md | 7 +++++-- docs/swarm.md | 2 +- 5 files changed, 18 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index a74c2af..e5b916a 100644 --- a/README.md +++ b/README.md @@ -11,18 +11,19 @@ ## 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: - Docker - Docker Swarm - Kubernetes +- Static YAML definitions (`EASYHAPROXY_DISCOVER=static`) ## Who is using? EasyHAProxy is part of some projects: -- Dokku +- Dokku - MicroK8s - DigitalOcean Marketplace @@ -34,12 +35,12 @@ Easy to set up and low configuration to numerous 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 - 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. - Add redirects. - Enable/disable Stats on port 1936 with a custom password. diff --git a/docs/container-labels.md b/docs/container-labels.md index ae05902..9b9bfe2 100644 --- a/docs/container-labels.md +++ b/docs/container-labels.md @@ -6,7 +6,7 @@ sidebar_position: 11 ## 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].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].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].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 | :::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. ::: -## Configuations +## Configurations ### Single Definition @@ -101,4 +101,4 @@ docker run \ ``` ---- -[Open source ByJG](http://opensource.byjg.com) \ No newline at end of file +[Open source ByJG](http://opensource.byjg.com) diff --git a/docs/kubernetes.md b/docs/kubernetes.md index a8921ed..c4b8b67 100644 --- a/docs/kubernetes.md +++ b/docs/kubernetes.md @@ -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.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.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. @@ -155,4 +155,4 @@ spec: ``` ---- -[Open source ByJG](http://opensource.byjg.com) \ No newline at end of file +[Open source ByJG](http://opensource.byjg.com) diff --git a/docs/static.md b/docs/static.md index 11189f0..f81077c 100644 --- a/docs/static.md +++ b/docs/static.md @@ -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" docker run -d \ --name easy-haproxy-container \ - -v /var/run/docker.sock:/var/run/docker.sock \ -v /my/static/:/etc/haproxy/static/ \ -e EASYHAPROXY_DISCOVER="static" \ # + Environment Variables \ @@ -78,7 +77,11 @@ docker run -d \ 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 diff --git a/docs/swarm.md b/docs/swarm.md index 9a133c8..348224e 100644 --- a/docs/swarm.md +++ b/docs/swarm.md @@ -35,7 +35,7 @@ version: "3" services: haproxy: - image: byjg/easy-haproxy:4.3.1-rc1 + image: byjg/easy-haproxy:4.6.0 volumes: - /var/run/docker.sock:/var/run/docker.sock deploy: