6.0.0

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.