What's New

Real-Time Monitoring Dashboard

EasyHAProxy now ships a built-in monitoring dashboard — no extra containers, no Prometheus, no Grafana required.

• Zero-dependency: runs inside the EasyHAProxy process as a Python daemon thread, served via an embedded HTTP server on 127.0.0.1:9190 and proxied through a dedicated frontend dashboard / backend srv_dashboard
• Live view: frontends, backends, servers, bytes in/out, active sessions, request rate — all updating in real time
• Charts: Traffic Volume and Request Rate & Sessions plotted over time
• Enable with one env var: set HAPROXY_PASSWORD and open http://<host>:11936/

See the Monitoring Dashboard guide for setup details.

Health Checks for Internal Backends

srv_stats and srv_dashboard internal backends now carry check, so HAProxy actively monitors them and the stats page reflects their real status.

Note: certbot_backend intentionally has no check — the certbot listener is ephemeral and only runs during ACME challenges.

Bug Fixes

• Fixed ACME e2e test fixture leaking containers when docker compose --wait failed. The docker_compose_acme fixture now guarantees fixture.down() is called even when fixture.up() raises.
• Fixed stale cached Docker image being used by the ACME test compose. The compose now references byjg/easy-haproxy:local — the same image built by the main test suite.

Documentation

• New Monitoring Dashboard guide with screenshots, login dialog explanation, and environment variable reference
• HAPROXY_STATS_CORS_ORIGIN now documented as required for the dashboard to function (browser enforces CORS between the dashboard port and the stats API port)
• README updated with dashboard feature highlight and thumbnail

Environment Variables

Full Changelog

6.0.0...6.0.1

EasyHAProxy Release Notes

Version 6.0.0

Scope

• Focus: IngressClass support, ingress status updates, proxy-awareness headers, pip installability, code modularization, comprehensive E2E test suite, and Helm chart v2.

Highlights

• IngressClass support: replaced the deprecated kubernetes.io/ingress.class annotation with the standard spec.ingressClassName field, compatible with Kubernetes v1.22+. The Helm chart now creates an IngressClass resource (byjg.com/easyhaproxy) by default and exposes ingressClass.* values to configure it.
• Ingress status updates: EasyHAProxy can now patch the status.loadBalancer field on Ingress objects so that kubectl get ingress shows a real address. Controlled by new env vars: EASYHAPROXY_UPDATE_INGRESS_STATUS, EASYHAPROXY_DEPLOYMENT_MODE (auto/daemonset/nodeport/clusterip), EASYHAPROXY_EXTERNAL_HOSTNAME, and EASYHAPROXY_STATUS_UPDATE_INTERVAL.
• Proxy-awareness headers: HAProxy now forwards X-Forwarded-For, X-Forwarded-Port, X-Forwarded-Proto, X-Forwarded-Host, and X-Request-ID to backends, enabling correct IP and protocol propagation behind reverse proxies.
• CORS support on the HAProxy stats dashboard.
• Pip-installable package: EasyHAProxy is now available as a Python package (pip install easyhaproxy), with a standalone easyhaproxy entrypoint and full pyproject.toml / uv build setup.
• Config path consolidated to /etc/easyhaproxy across container, tests, docs, and examples (previously split between /etc/haproxy and /etc/easyhaproxy).
• Helm chart version raised to 2.0.0 (appVersion 6.0.0); added ingressClass and ingressStatus sections to values.yaml; clusterrole now covers ingressclasses and ingresses/status.
• Comprehensive E2E test suite across all deployment modes: Docker Compose, Docker Swarm, Kubernetes, static, and proxy-headers — each running in its own CI job with proper readiness polling and fixture teardown.

Code

• Python source split into focused modules: src/functions/certbot.py, src/functions/haproxy.py, src/functions/container_env.py, src/functions/consts.py, src/functions/filter.py, src/functions/functions.py, src/functions/loggers.py; mapping logic moved to src/easymapping/config_generator.py and src/easymapping/label_handler.py; top-level entrypoint at src/easyhaproxy/main.py.
• Ingress processor updated to read spec.ingressClassName first, falling back to the legacy kubernetes.io/ingress.class annotation for backward compatibility.
• New IngressClass Kubernetes resource created and managed by the Helm chart (helm/easyhaproxy/templates/ingressclass.yaml).
• Ingress status patching logic added to support auto-detection of deployment mode and optional external hostname override.
• Proxy-header injection and CORS handling added to HAProxy config generation.
• Dockerfile migrated to a multi-stage build under deploy/docker/Dockerfile; old build/ directory removed.
• Build system switched to uv + pyproject.toml; setup.py and .gitpod.yml removed.
• Codebase modernized: deprecated patterns replaced, type hints added throughout.

Documentation

• New docs/pip.md covering pip installation, the standalone entrypoint, and Python API usage.
• docs/kubernetes.md expanded with IngressClass setup, spec.ingressClassName usage, ingress status configuration, and deployment-mode guidance.
• docs/volumes.md updated with the new /etc/easyhaproxy layout and cert path structure.
• docs/environment-variable.md updated with all new env vars (EASYHAPROXY_UPDATE_INGRESS_STATUS, EASYHAPROXY_DEPLOYMENT_MODE, EASYHAPROXY_EXTERNAL_HOSTNAME, EASYHAPROXY_STATUS_UPDATE_INTERVAL).
• docs/ssl.md and docs/acme.md improved with current path references and clearer instructions.
• All plugin docs refreshed for the /etc/easyhaproxy path change; docs/Plugins/jwt-validator.md significantly expanded.
• deploy/kubernetes/README.md added with end-to-end deployment instructions.

Examples

• All Kubernetes examples (easyhaproxy-clusterip.yml, easyhaproxy-daemonset.yml, easyhaproxy-nodeport.yml) updated to use spec.ingressClassName: easyhaproxy and the new IngressClass resource.
• Docker Compose and Swarm examples updated for the /etc/easyhaproxy path layout.
• Examples relocated from examples/ into tests_e2e/ subdirectories so they serve as both documentation and live test fixtures.
• New deploy/kubernetes/README.md providing a step-by-step Kubernetes quick-start.

Tests & CI

• New end-to-end test files: tests_e2e/test_docker_compose.py, tests_e2e/test_kubernetes.py, tests_e2e/test_swarm.py, tests_e2e/test_static.py, tests_e2e/test_proxy_headers.py, backed by a shared tests_e2e/utils.py with DockerComposeFixture, wait_for_json_response, and other helpers.
• Swarm E2E tests cover both basic SSL/redirect services and the combined-plugins scenario (JWT + Cloudflare + IP-whitelist + deny-pages) deployed as real Swarm stacks.
• Kubernetes E2E tests cover basic service, TLS, IP whitelist, JWT validator (via Secret), and combined-plugins scenarios using a kind cluster; wait_for_easyhaproxy_discovery polls for non-503 responses to properly detect backend readiness.
• ACME/Certbot E2E tests added using a local Pebble ACME server.
• CI workflow reorganized into parallel jobs: Tests-E2E-Docker, Tests-E2E-Kubernetes, Tests-E2E-Additional (static + proxy-headers), and Tests-E2E-Swarm — all required before the Build job runs.
• Swarm CI job pre-builds the Docker image with DOCKER_BUILDKIT=0 before pytest to avoid a BuildKit layer-export hang that affected GitHub Actions runners.
• Pytest fixtures scoped to class for efficient per-class stack lifecycle management.

Version 5.0.0

Scope

• Focus: new plugin framework, documentation overhaul, examples, tests, and chart version bump

Highlights

• Introduced a full plugin framework (global and domain plugins) with built-in plugins: cleanup, cloudflare, deny-pages, fastcgi, ip-whitelist, and jwt-validator.
• HAProxy config generation now injects plugin output and supports backend proto definitions (e.g., fcgi/h2) alongside existing label/annotation parsing.
• Helm chart version raised to 1.0.0; release automation now updates Swarm docs during tagging.
• Added comprehensive plugin documentation and a plugin development guide, plus a full release guide for maintainers.
• Expanded examples for Docker, Swarm, Kubernetes, and static setups covering plugin usage; added PHP app sample and key-generation helper.
• Test suite enlarged with plugin coverage, new fixtures/expected outputs, and updated test entrypoint (cd src && pytest tests/ -vv).

Code

• Added plugin runtime: src/plugins/__init__.py, builtin plugins under src/plugins/builtin/, and wiring in HaproxyConfigGenerator to execute global/domain plugins and merge their HAProxy snippets.
• Enabled plugin configuration via env vars (EASYHAPROXY_PLUGINS_*), YAML (static), and labels/annotations; domain configs propagate into the generated backend blocks.
• HAProxy template renders global plugin blocks and per-domain plugin snippets; server lines now honor proto when provided.
• Container processing and label handling extended to capture plugin configs and plugin-generated metadata.

Documentation

• README now indexes plugin guides and built-in plugin pages.
• New/expanded docs: docs/plugins.md, docs/plugin-development.md, and detailed pages for each builtin plugin under docs/Plugins/.
• Updated deployment docs (Kubernetes, Swarm, etc.) and config references (labels, env vars, other settings) to reflect plugin support and current defaults.
• Release process documented in RELEASE.md; environment variable docs clarify stats behavior.

Examples

• Added plugin-enabled examples for Docker, Swarm, Kubernetes, and static configurations, plus combined plugin scenarios.
• New PHP demo app and helper script examples/generate-keys.sh; removed placeholder certificates from examples.
• Refreshed docker-compose and manifest samples to include plugin labels/annotations and updated image tags.

Tests & CI

• Large plugin test suite added (src/tests/test_plugins.py) with new fixtures/expected outputs for plugin flows and fcgi support.
• Test runner target now executes from src/ with verbose output.
• Build workflow updates keep Swarm docs in sync when tagging releases.

EasyHAProxy Release Notes

Scope

• Focus: new plugin framework, documentation overhaul, examples, tests, and chart version bump

Highlights

• Introduced a full plugin framework (global and domain plugins) with built-in plugins: cleanup, cloudflare, deny-pages, fastcgi, ip-whitelist, and jwt-validator.
• HAProxy config generation now injects plugin output and supports backend proto definitions (e.g., fcgi/h2) alongside existing label/annotation parsing.
• Helm chart version raised to 1.0.0; release automation now updates Swarm docs during tagging.
• Added comprehensive plugin documentation and a plugin development guide, plus a full release guide for maintainers.
• Expanded examples for Docker, Swarm, Kubernetes, and static setups covering plugin usage; added PHP app sample and key-generation helper.
• Test suite enlarged with plugin coverage, new fixtures/expected outputs, and updated test entrypoint (cd src && pytest tests/ -vv).

Code

• Added plugin runtime: src/plugins/__init__.py, builtin plugins under src/plugins/builtin/, and wiring in HaproxyConfigGenerator to execute global/domain plugins and merge their HAProxy snippets.
• Enabled plugin configuration via env vars (EASYHAPROXY_PLUGINS_*), YAML (static), and labels/annotations; domain configs propagate into the generated backend blocks.
• HAProxy template renders global plugin blocks and per-domain plugin snippets; server lines now honor proto when provided.
• Container processing and label handling extended to capture plugin configs and plugin-generated metadata.

Documentation

• README now indexes plugin guides and built-in plugin pages.
• New/expanded docs: docs/plugins.md, docs/plugin-development.md, and detailed pages for each builtin plugin under docs/Plugins/.
• Updated deployment docs (Kubernetes, Swarm, etc.) and config references (labels, env vars, other settings) to reflect plugin support and current defaults.
• Release process documented in RELEASE.md; environment variable docs clarify stats behavior.

Examples

• Added plugin-enabled examples for Docker, Swarm, Kubernetes, and static configurations, plus combined plugin scenarios.
• New PHP demo app and helper script examples/generate-keys.sh; removed placeholder certificates from examples.
• Refreshed docker-compose and manifest samples to include plugin labels/annotations and updated image tags.

Tests & CI

• Large plugin test suite added (src/tests/test_plugins.py) with new fixtures/expected outputs for plugin flows and fcgi support.
• Test runner target now executes from src/ with verbose output.
• Build workflow updates keep Swarm docs in sync when tagging releases.

What's Changed

• Improve ACME and Docker documentation with fixes by @byjg in #61

Full Changelog: 4.5.0...4.6.0

What's Changed

• Add prometheus metrics by @zasdaym in #53
• #56 prototyped manual-auth-hook and different preferred-challenges support by @ThaDaVos in #57
• Improve documentation for issue #54 by @byjg in #55
• Log Refactor by @byjg in #58

New Contributors

• @zasdaym made their first contribution in #53
• @ThaDaVos made their first contribution in #57

Full Changelog: 4.4.0...4.5.0

What's Changed

• Issue #36 - Fix Swarm Connection when container is not in the same network as EasyHAProxy by @byjg in #46
• Issue #38 Add HTTP 2.0 Support for SSL by @byjg in #45
• Issue #43 - Customize Load Balance method + Custom HAProxy config by @byjg in #44
• Issue #41 - Add support to various Certificate Authorities (CA) using the protocol ACME (e.g. Let's Encrypt, ZeroSSL, BuyPass, etc) by @byjg in #42

Full Changelog: 4.3.0...4.4.0

What's Changed

• Issue #32 Added parameter EASYHAPROXY_LETSENCRYPT_SERVER. Default is empty. If set as staging allow get the certificate from the staging server. Also allows to set a specific URL to get the certificates.
• Issue #33 Use the container IP instead the container name. It resolves issues in different network.
• Minor Bug Fixes

Full Changelog: 4.2.0...4.3.0

Major Feature: Kubernetes

• Discover from Ingress
• Letsencrypt
• HELM and Helm Repository

Other Features

• Log Level and Log per application
• Reorganization of the Documentation
• Several other minor improvements.

Read changes from release 4.0.0 plus new changes:

• Enable letsencrypt

-l easyhaproxy.[definition].letsencrypt=true

• Redirect hosts now is a JSON parameter

-l easyhaproxy.[definition].redirect='{"old.host1.com", "https://www.host1.com"}'

• Add multiple hosts using a single definition.

-l easyhaproxy.[definition].host=www.host1.com,host1.com

• Add parameter redirect_ssl (true/false) to redirect to HTTPS.
• Add environment variable EASYHAPROXY_SSL_MODE to set up the SSL protocols HAProxy will work.
• Add parameter ssl (true/false) to provide SSL Certs as a file
• Statistics are enabled by default with no password. To disable it set HAPROXY_STATS_PORT to false or create a password with HAPROXY_PASSWORD

This version implements a major refactory. As a result, it breaks compatibility with the previous versions.

Do not upgrade to this version before upgrading your definitions according to the features below:

• Renamed the environment variable DISCOVER to EASYHAPROXY_DISCOVER
• Enabled the possibility to change the easyhaproxy docker label with the environment variable EASYHAPROXY_LABEL_PREFIX
• Implemented dynamic definition and removed easyhaproxy.definitions docker label
• Changed docker label order from easyhaproxy.[property].[definition] to easyhaproxy.[definition].[property]
• Upgrade alpine from 3.14 to 3.16
• Upgrade HAProxy from 2.4.15 to 2.4.17

Issues: #11 , #16
PRs: #14 , #16