HAProxy

Installs and configures HAProxy as a layer-7 domain-based reverse proxy, routing HTTP and HTTPS traffic to backends by hostname.

Requirements

None.

Variables

Variable	Default	Description
ha_connections	[]	List of backend routing rules. Required (must be non-empty). See Connections below.
ha_uninstall	false	Stops, disables, and purges HAProxy.

Connections

Each entry in ha_connections defines one backend:

Key	Required	Description
urls	Yes	List of hostnames to route to this backend.
ip	Yes	Backend IPv4 address.
is_fallback	No	If true, this backend receives all traffic that matches no other rule. At most one entry may be true.
proxy_protocol	No	If false, don't send PROXY protocol v2 to this backend (default true). See Notes — only for backends with no PROXY protocol support.

Usage

Minimal setup:

ha_connections:
  - urls:
      - example.com
      - www.example.com
    ip: 1.2.3.4

With a fallback backend:

ha_connections:
  - urls:
      - app.example.com
    ip: 1.2.3.4
  - urls:
      - other.example.com
    ip: 5.6.7.8
    is_fallback: true

Uninstall

To stop, disable, and purge HAProxy:

ha_uninstall: true

Notes

• Both HTTP (:80) and HTTPS (:443) frontends are configured. HTTPS routing uses TCP mode with SNI inspection — TLS is not terminated at HAProxy.
• Backends use PROXY protocol v2 (send-proxy-v2) by default to forward the original client IP. Because HTTPS is TCP-passthrough (no TLS termination), this is the only way a backend learns the real client IP — there's no X-Forwarded-For fallback. The backend must explicitly trust and parse it (e.g. Traefik with entryPoints.*.proxyProtocol.trustedIPs set to this host's IP) or the connection will be silently dropped. Set proxy_protocol: false on a connection if its backend has no PROXY protocol support at all.
• The generated config is validated with haproxy -c -f before being applied. HAProxy is reloaded gracefully on config change.