Role: haproxy

Deploy HAProxy Load Balancer for Service Exposure

Module	NODE
Docs	https://pigsty.io/docs/node/haproxy
Related Roles	node, pgsql

Overview

The haproxy role deploys HAProxy for load balancing and service exposure:

• Install HAProxy package
• Create configuration directory
• Render default and service configs
• Configure SELinux policies (if applicable)
• Launch HAProxy service
• Support config reload without restart

HAProxy is used by PostgreSQL clusters for connection pooling and load balancing across replicas.

Playbooks

Playbook	Description
node.yml	Node provisioning (includes HAProxy)

File Structure

roles/haproxy/
├── defaults/
│   └── main.yml              # Default variables
├── files/
│   └── haproxy.svc           # Systemd service file
├── meta/
│   └── main.yml              # Role dependencies
├── tasks/
│   └── main.yml              # Main task list
└── templates/
    ├── haproxy.cfg.j2        # Default HAProxy config
    └── service.j2            # Service definition template

Tags

Tag Hierarchy

haproxy (full role)
│
├── haproxy_install            # Install HAProxy
│
├── haproxy_config             # Configure HAProxy
│   └── haproxy_firewall       # SELinux configuration
│
├── haproxy_launch             # Start HAProxy service
│
└── haproxy_reload             # Reload configuration

Key Variables

Basic Configuration

Variable	Default	Description
haproxy_enabled	true	Enable HAProxy on this node
haproxy_clean	false	Wipe existing config on deploy
haproxy_reload	true	Reload after config changes

Admin Interface

Variable	Default	Description
haproxy_auth_enabled	true	Enable admin authentication
haproxy_admin_username	admin	Admin page username
haproxy_admin_password	pigsty	Admin page password
haproxy_exporter_port	9101	Admin/metrics port

⚠️ Security Warning: The default password pigsty is publicly known. Change haproxy_admin_password in production environments!

Timeouts

Variable	Default	Description
haproxy_client_timeout	24h	Client connection timeout
haproxy_server_timeout	24h	Server connection timeout

Services

Variable	Default	Description
haproxy_services	[]	List of services to expose

Configuration Directory

/etc/haproxy/
├── haproxy.cfg           # Global defaults
├── pg-test-primary.cfg   # Service: port 5433
├── pg-test-replica.cfg   # Service: port 5434
├── pg-test-default.cfg   # Service: port 5435
├── pg-test-offline.cfg   # Service: port 5436
└── ...

Service Definition

Define custom HAProxy services:

haproxy_services:
  # PostgreSQL read-only replicas
  - name: pg-test-ro
    port: 5440
    ip: "*"
    protocol: tcp
    balance: leastconn
    maxconn: 20000
    default: 'inter 3s fastinter 1s downinter 5s rise 3 fall 3 on-marked-down shutdown-sessions slowstart 30s maxconn 3000 maxqueue 128 weight 100'
    options:
      - option httpchk
      - option http-keep-alive
      - http-check send meth OPTIONS uri /read-only
      - http-check expect status 200
    servers:
      - { name: pg-test-1, ip: 10.10.10.11, port: 5432, options: 'check port 8008', backup: true }
      - { name: pg-test-2, ip: 10.10.10.12, port: 5432, options: 'check port 8008' }
      - { name: pg-test-3, ip: 10.10.10.13, port: 5432, options: 'check port 8008' }

  # Redis cluster
  - name: redis-test
    port: 5441
    servers:
      - { name: redis-test-1-6379, ip: 10.10.10.11, port: 6379, options: check }
      - { name: redis-test-1-6380, ip: 10.10.10.11, port: 6380, options: check }

Service Parameters

Parameter	Required	Default	Description
name	Yes	-	Unique service name
port	Yes	-	Listen port
ip	No	*	Listen address
protocol	No	tcp	Protocol (tcp/http)
balance	No	roundrobin	Load balance algorithm
maxconn	No	10000	Max frontend connections
options	No	[]	Additional HAProxy options
servers	Yes	-	Backend server list

Load Balancing Algorithms

Algorithm	Description
roundrobin	Round-robin selection (default, good for homogeneous servers)
leastconn	Prefer server with fewest connections (good for OLTP)
source	Hash client IP for session affinity
first	Use first available server (for active-standby)

Health Check

For PostgreSQL clusters, HAProxy uses HTTP health checks against Patroni REST API:

options:
  - option httpchk
  - option http-keep-alive
  - http-check send meth OPTIONS uri /read-only  # or /primary, /replica, /health
  - http-check expect status 200
servers:
  - { name: pg-test-1, ip: 10.10.10.11, port: 5432, options: 'check port 8008' }

Patroni Health Check Endpoints (port 8008):

Endpoint	Returns 200 When	Use Case
/primary	Instance is primary	Read-write service
/replica	Instance is replica	Read-only service
/read-only	Instance accepts read queries (any role)	Read-only + backup
/health	Instance is healthy (any role)	General health

Reload Configuration

Update services without restarting:

./node.yml -t haproxy_config,haproxy_reload
bin/pgsql-svc <cls>

This validates config before reload and only applies changes if valid.

SELinux Handling

On RHEL/Rocky systems with SELinux enabled, the role automatically:

1. Sets haproxy_connect_any boolean to allow HAProxy to connect to any port
2. Installs a custom SELinux policy module (haproxy_proc) to allow HAProxy to read /proc filesystem for health monitoring

This is handled silently - if SELinux tools are not available, these steps are skipped.

Platform Support

This role supports RHEL/Rocky 8-10, Ubuntu 22-24, and Debian 12-13.

The systemd service file is installed to {{ systemd_dir }}/haproxy.service, where systemd_dir is determined by the node_id role based on OS detection.

See Also

• node: Node provisioning
• pgsql: PostgreSQL cluster
• HAProxy Guide: Configuration documentation