HAProxy (haproxy)
Load balancer of the replicated services: frontends and backends described as JSON, statistics page and Prometheus metrics.
Generated from catalog/services/haproxy.yaml: do not edit by hand.
Summary
| Version | 3.2.9 |
| Use | install and configure |
| Layer | infrastructure (shown apart) |
| Category | Gateways and load balancing |
| Installation methods | package, podman |
| External connection | no |
| Sandbox only | no |
Licence
| SPDX identifier | GPL-2.0-or-later |
| Licence policy | licence exception |
| Licence exception | LEX-004 (pending, awaiting the client) |
| Platform component | haproxy |
Packages and artifacts
A package the project of the service publishes (its image, its binary archive, its Python or OS package) carries the licence of the service; a third-party package carries the licence written on its row, read from the official upstream metadata.
| Kind | Package | Version | Licence | Details |
|---|---|---|---|---|
| container image | docker.io/library/haproxy | 3.2.9 | GPL-2.0-or-later | image key haproxy, used by haproxy, digest sha256:7eb80a6c4555dd64fd5b01c078b33637b1af1871d636570624ef0b079857527e |
| OS package | haproxy | version of the configured repository | GPL-2.0-or-later | RHEL family (dnf) |
| OS package | haproxy | version of the configured repository | GPL-2.0-or-later | Debian family (apt) |
Images are pinned by tag in the descriptor, and by digest when the descriptor declares one (the offline bundle then refuses a pulled image that does not carry it); the digest is recorded in the mirror of the Manager when the offline bundle is imported, and every pull or load is checked against it.
Supported systems and architectures
| Method | Operating systems | Architectures |
|---|---|---|
package | RHEL family (dnf), Debian family (apt) | x86_64, aarch64 (not restricted by the descriptor) |
podman | RHEL family (dnf), Debian family (apt), Arch Linux (pacman) | x86_64, aarch64 (not restricted by the descriptor) |
Certified host systems: RHEL 8/9/10, Rocky Linux 8/9/10, AlmaLinux 8/9/10, Oracle Linux 8/9, CentOS Stream 9/10, Ubuntu 22.04/24.04, Debian 12, Arch Linux (rolling). The host preflight accepts these systems (other releases of a known family give a warning, end of life releases are refused) and the x86_64 and aarch64 architectures.
Prerequisites
Host
The descriptor declares no host preflight check.
Programs the commands and checks of the service start on the host, outside the managed roots: add them to allowed_commands of the agent (see Security of the Navin agent), else the agent refuses them with command_not_allowed: /usr/sbin/haproxy.
Network and ports
| Component | Port name | Port | Opened in the host firewall |
|---|---|---|---|
haproxy | stats | 8404/tcp | yes |
haproxy | frontend | frontends[].bind_port/tcp | yes |
Kernel parameters
| Parameter | Value |
|---|---|
net.core.somaxconn | 4096 |
net.ipv4.ip_nonlocal_bind | 1 |
Services and connections needed
This service has no dependency.
Installation methods and modes
| Method | Default | What the method uses |
|---|---|---|
package | yes | the OS packages of the descriptor, installed by the package manager of the host |
podman | - | the container images of the descriptor, run by Podman under systemd |
Components
| Component | Kind | Installation methods | Ports |
|---|---|---|---|
HAProxy (haproxy) | master | package, podman | 8404/tcp, frontends[].bind_port/tcp |
Single (single) (default)
One load balancer.
What the mode deploys:
| Component | Placement |
|---|---|
haproxy | min 1, max 1 |
Active and standby pair (pair)
Two identical load balancers sharing a virtual IP held by keepalived.
What the mode deploys:
| Component | Placement |
|---|---|
haproxy | min 2, max 2 |
Install this service
The install wizard of the Navin Manager plans, validates and runs the installation; you need the services:install permission on the cluster.
-
Open the wizard. In Clusters, choose the row action Install services of the target cluster. The wizard opens on its first step, Service.
-
Choose the service. On the Service step, select HAProxy. The card shows the licence
GPL-2.0-or-later. Pick the Method amongpackage,podman(defaultpackage). -
Choose the hosts and the mode. On the Hosts step, tick the hosts, then choose the Mode:
single(default),pair. Each mode deploys the components listed in Installation methods and modes. -
Bindings. This service has no dependency: the Bindings step has nothing to bind.
-
Configure. On the Configure step, review the parameters (see Configuration parameters). Passwords left empty with a generated default are generated and sealed by the Manager.
-
Review and install. On the Install step the Manager validates the plan and shows the installation order; when it says "The plan is valid. Ready to install.", choose Install. A highly available mode is installed only when its HA checks pass.
-
Verify. The operation ends when the health checks of every instance pass (see Health checks); the service then shows as running in Services.
High availability
| Cluster | replicas (replication) |
| High availability | external (external) |
| Failover | virtual IP (vip) |
| Replication | none (none) |
| Quorum | VRRP (vrrp) |
| Discovery | static (static) |
| Entry point | virtual IP (vip) |
| Official documentation | https://docs.haproxy.org/3.2/configuration.html |
Prerequisites
| Prerequisite | Must be highly available | Modes | Description |
|---|---|---|---|
| keepalived | yes | pair | keepalived on the same two hosts moves the virtual IP (VRRP). |
Topology per mode
| Modes | Highest catalog level | Distribution | Quorum component | Fault domains | Description |
|---|---|---|---|---|---|
single | standalone (standalone) | single (single) | - | 1 | One load balancer: a single point of failure. |
pair | ha (ha) | active-passive (active-passive) | - | 2 | Two identical load balancers; keepalived holds the virtual IP on one of them. |
Notes
- HAProxy does not share its state between the two instances: connections in progress on the failed instance are cut, clients reconnect through the virtual IP.
Configuration parameters
Routing
| Parameter | Type | Default | Allowed values | Required | Secret | Restart | Description |
|---|---|---|---|---|---|---|---|
Frontends and backends (frontends) | json | [] | - | no | no | no | List of {name, bind_port, mode http|tcp, backend {balance, check_path, servers [host:port]}}; one frontend per entry, its bind_port published on the host. With the podman method, 127.0.0.1 in servers is the container itself: give the address of the host. |
Statistics port (stats_port) | port | 8404 | - | no | no | no | Port of the statistics page, /health and the Prometheus /metrics. |
Tuning
| Parameter | Type | Default | Allowed values | Required | Secret | Restart | Description |
|---|---|---|---|---|---|---|---|
Maximum connections (maxconn) | int | 20000 | min 256, max 1000000 | no | no | yes | Global connection limit. |
Client timeout (timeout_client) | duration | 300s | - | no | no | no | Inactivity timeout on the client side (long for streamed completions). |
Server timeout (timeout_server) | duration | 300s | - | no | no | no | Inactivity timeout on the server side. |
Security
| Parameter | Type | Default | Allowed values | Required | Secret | Restart | Description |
|---|---|---|---|---|---|---|---|
Statistics user (stats_user) | string | navin-stats | - | no | no | no | Login of the statistics page (stats auth); /health and /metrics stay open to the probes. |
Statistics password (stats_password) | password | generated | - | no | yes | no | Password of the statistics page, generated at each install and kept in the Manager vault. |
TLS (tls_enabled) | bool | false | - | no | no | yes | Serve the statistics page, /health and /metrics over TLS with a certificate issued by the manager CA (the certificate and its key are joined at start in a 0600 file of the run directory, the form HAProxy reads). |
Endpoints
| Endpoint | Scheme | Component | Port | Path | TLS parameter | Binding parameters | Binding secrets | Provisioning command |
|---|---|---|---|---|---|---|---|---|
stats | http | haproxy | 8404 (stats_port) | - | tls_enabled | - | - | - |
Commands
| Command | Component | Target | Description |
|---|---|---|---|
Validate the configuration (validate) | haproxy | every host | Runs haproxy -c on the rendered configuration. |
Reload (reload) | haproxy | every host | Reloads the configuration without dropping connections. |
Health checks
Liveness (per instance)
| Component | Check | Details |
|---|---|---|
haproxy | HTTP {{ ('https://' ~ host.fqdn) if config.tls_enabled else ('http://' ~ (host.ip or '127.0.0.1')) }}:{{ config.stats_port }}/health | Expected 200; 20 retries; interval 1 s; timeout 3 s |
Preflight checks
| Check | Type | Meaning | Severity | Components |
|---|---|---|---|---|
stats_port_free | port_free {"param": "stats_port"} | port 8404 free on the host | blocking | every component |
Uninstall
Paths removed when the data is purged: {{ paths.log }}.
Quick links
- Statistics:
{{ 'https' if config.tls_enabled else 'http' }}://{{ host.fqdn }}:{{ config.stats_port }}/stats
Upstream documentation
- Homepage: https://www.haproxy.org
- Source: https://github.com/haproxy/haproxy
- High availability: https://docs.haproxy.org/3.2/configuration.html