Skip to content

All about HAProxy listens

An HAProxy listen exposes a backing service (MariaDB, PostgreSQL, Meilisearch, SingleStore, or RabbitMQ) on a port or socket, load-balanced across the cluster's nodes that run that service.

This article explains the source/destination model, the port-vs-socket choice, and the cross-cluster pattern.

What a listen does

A listen tells HAProxy: "for traffic arriving on this port (or socket), proxy to all nodes with this group, in this cluster."

Applications don't connect directly to MariaDB, PostgreSQL, etc. — they connect to the HAProxy listen, which spreads connections across all eligible backend nodes and fails over automatically if one is down.

Where to find HAProxy listens

In Core, HAProxy listens are managed per cluster.

Fields

Nodes Group — which backend service

'Nodes Group' decides which group of nodes the listen proxies to. Supported groups:

  • MariaDB
  • PostgreSQL
  • Meilisearch
  • SingleStore
  • RabbitMQ

Nodes IDs — pin to specific nodes (optional)

By default, the listen proxies to every node in the cluster with the specified group. Set 'Nodes IDs' to restrict it to specific nodes. Those nodes must have the group set in 'Nodes Group'.

Port or Socket Path

The listen accepts traffic on one of:

  • 'Port' — a TCP port.
  • 'Socket Path' — a Unix socket. Must live under /run/.

Set exactly one. For application traffic, use a port; for processes that always run on the same node as the database and never need to reach it from elsewhere, use a socket.

Load Balancing Method

'Load Balancing Method' controls how connections are distributed. The default is 'Source IP Address' — a given client IP is routed to the same backend each time (sticky by IP).

Destination Cluster

'Destination Cluster' is the cluster whose nodes are the proxy backends. Usually this is the cluster the listen lives on — but it doesn't have to be.

Cross-cluster proxying

The 'Destination Cluster' doesn't need to match the cluster the listen is hosted on. This lets a node on cluster A expose, via HAProxy, a service running on cluster B.

Typical use case: a dedicated application cluster talking to a dedicated database cluster, without exposing the database nodes directly to the application network. The application cluster has the HAProxy listen; the database cluster runs the actual MariaDB/PostgreSQL/etc. nodes.