Installing and Configuring HAProxy as a Load Balancer for Magento 2 Nginx Backends on openSUSE Leap 15.5

Prerequisites and System Setup

This guide assumes a functional openSUSE Leap 15.5 installation with root or sudo privileges. We will be setting up HAProxy to distribute traffic across multiple Nginx instances serving Magento 2. Ensure your Nginx servers are already configured and accessible on a specific port (e.g., 8080) for the backend Magento 2 applications. For this setup, we’ll use a single HAProxy instance, but the principles extend to a highly available pair.

First, update your system’s package list and install HAProxy:

sudo zypper refresh
sudo zypper install haproxy

Verify the installation and check the HAProxy version:

haproxy -v

HAProxy Configuration for Magento 2

The primary configuration file for HAProxy is located at /etc/haproxy/haproxy.cfg. We’ll define frontend and backend sections to manage incoming traffic and direct it to our Nginx servers. For Magento 2, it’s crucial to handle sticky sessions (if required for specific functionalities, though often not for stateless Magento) and to ensure proper health checks are in place.

Open the configuration file for editing:

sudo nano /etc/haproxy/haproxy.cfg

Here’s a sample configuration. Replace 192.168.1.101:8080 and 192.168.1.102:8080 with the actual IP addresses and ports of your Nginx backend servers.

global
    log /dev/log    local0
    log /dev/log    local1 notice
    chroot /var/lib/haproxy
    stats socket /run/haproxy/admin.sock mode 660 level admin expose-fd listeners
    stats timeout 30s
    user haproxy
    group haproxy
    daemon

defaults
    log     global
    mode    http
    option  httplog
    option  dontlognull
    timeout connect 5000
    timeout client  50000
    timeout server  50000
    errorfile 400 /etc/haproxy/errors/400.http
    errorfile 403 /etc/haproxy/errors/403.http
    errorfile 408 /etc/haproxy/errors/408.http
    errorfile 500 /etc/haproxy/errors/500.http
    errorfile 502 /etc/haproxy/errors/502.http
    errorfile 503 /etc/haproxy/errors/503.http
    errorfile 504 /etc/haproxy/errors/504.http

frontend http_frontend
    bind *:80
    mode http
    default_backend http_backend

backend http_backend
    mode http
    balance roundrobin
    option httpchk GET /health_check.php HTTP/1.1\r\nHost:\ www.example.com
    server mage1 192.168.1.101:8080 check inter 2000 rise 2 fall 3
    server mage2 192.168.1.102:8080 check inter 2000 rise 2 fall 3

# Optional: Frontend for HTTPS (if Nginx handles SSL termination)
# frontend https_frontend
#    bind *:443 ssl crt /etc/ssl/certs/your_domain.pem
#    mode http
#    default_backend http_backend

# Optional: HAProxy Stats Page
listen stats
    bind *:8404
    mode http
    stats enable
    stats uri /haproxy?stats
    stats realm Haproxy\ Statistics
    stats auth admin:YourSecurePassword
    stats admin if TRUE

Explanation of Key Directives:

• global: Contains global parameters affecting HAProxy’s operation.
• defaults: Sets default parameters for all frontends and backends. mode http is essential for HTTP traffic. timeout client and server are set to 50 seconds to accommodate potentially long-running Magento requests.
• frontend http_frontend: Defines the listener for incoming HTTP traffic on port 80. bind *:80 listens on all interfaces. default_backend http_backend directs all traffic to the specified backend.
• backend http_backend: Defines the pool of servers. balance roundrobin distributes requests evenly. option httpchk configures a health check. It’s vital to have a dedicated health check endpoint on your Magento 2 Nginx servers (e.g., a simple PHP file that returns 200 OK). Ensure the Host header matches your domain.
• server mage1 ...: Defines individual backend servers. check enables health checking. inter 2000 sets the interval between checks to 2 seconds. rise 2 means the server is considered healthy after 2 successful checks. fall 3 means the server is considered down after 3 failed checks.
• listen stats: Configures the HAProxy statistics page, which is invaluable for monitoring. Remember to change YourSecurePassword to a strong, unique password.

Health Check Endpoint for Magento 2

For the option httpchk directive to work effectively, you need a simple PHP file on each of your Nginx backend servers that HAProxy can query. This file should return a 200 OK status code and minimal content.

Create a file named health_check.php in your Magento 2 Nginx webroot (e.g., /var/www/html/magento2/health_check.php) with the following content:

<?php
header('HTTP/1.1 200 OK');
echo 'OK';
exit;
?>

Ensure this file is accessible via HTTP and that your Nginx configuration allows access to it. For example, in your Nginx server block:

location ~ ^/health_check\.php$ {
    try_files $uri =404;
    fastcgi_pass unix:/var/run/php-fpm/www.sock; # Adjust to your PHP-FPM socket
    fastcgi_index health_check.php;
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_param PATH_INFO $fastcgi_path_info;
}

After creating the file, reload your Nginx configuration on each backend server:

sudo systemctl reload nginx

Enabling and Starting HAProxy Service

Once the configuration is saved, enable and start the HAProxy service. It’s also good practice to ensure it starts on boot.

sudo systemctl enable haproxy
sudo systemctl start haproxy

Check the status of the HAProxy service to ensure it’s running without errors:

sudo systemctl status haproxy

If there are any configuration errors, HAProxy will typically log them to /var/log/messages or journalctl. You can also test the configuration syntax before starting/restarting:

sudo haproxy -c -f /etc/haproxy/haproxy.cfg

Firewall Configuration

Ensure your firewall (e.g., firewalld) allows traffic on the ports HAProxy is listening on (port 80 for HTTP, port 443 for HTTPS if configured, and port 8404 for stats).

sudo firewall-cmd --permanent --add-port=80/tcp
sudo firewall-cmd --permanent --add-port=8404/tcp
# If using HTTPS:
# sudo firewall-cmd --permanent --add-port=443/tcp
sudo firewall-cmd --reload

Testing and Monitoring

Access your Magento 2 store through the IP address or domain name configured for HAProxy (e.g., http://your_haproxy_ip). You should see your Magento 2 store. To verify load balancing and health checks, access the HAProxy statistics page at http://your_haproxy_ip:8404/haproxy?stats. Log in with the credentials defined in the configuration.

The statistics page will show the status of your frontend and backend servers. You can observe how traffic is distributed and if any backend servers are marked as down due to failed health checks. If a backend server fails, HAProxy will automatically stop sending traffic to it until it becomes healthy again.

Advanced Considerations

SSL Termination: For production environments, it’s highly recommended to terminate SSL at HAProxy. This simplifies certificate management on your backend Nginx servers. You would configure the bind *:443 ssl crt /path/to/your/certificate.pem directive in the frontend and ensure the backend servers are configured to accept HTTP traffic from HAProxy.

Session Persistence (Sticky Sessions): While Magento 2 is generally stateless, some specific extensions or custom functionalities might require session persistence. HAProxy can achieve this using cookies. For example, to enable cookie-based persistence:

backend http_backend
    mode http
    balance roundrobin
    option httpchk GET /health_check.php HTTP/1.1\r\nHost:\ www.example.com
    cookie SERVERID insert indirect nocache
    server mage1 192.168.1.101:8080 check inter 2000 rise 2 fall 3 cookie mage1
    server mage2 192.168.1.102:8080 check inter 2000 rise 2 fall 3 cookie mage2

High Availability: For a production setup, a single HAProxy instance is a single point of failure. Implement a High Availability (HA) solution using Keepalived or Pacemaker to manage a virtual IP address (VIP) that floats between two HAProxy servers.

Logging and Monitoring: Configure remote logging for HAProxy to a central log server. Integrate HAProxy metrics into your existing monitoring systems (e.g., Prometheus with the HAProxy exporter) for proactive issue detection and performance analysis.