A Basic Configuration Example

global
    log /dev/log local0
    log /dev/log local1 notice
    chroot /var/lib/haproxy
    stats timeout 30s
    # Intermediate configuration from Mozilla generator
    ssl-default-bind-ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384
    ssl-default-bind-ciphersuites TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256
    ssl-default-bind-options prefer-client-ciphers no-sslv3 no-tlsv10 no-tlsv11 no-tls-tickets
    ssl-default-server-ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384
    ssl-default-server-ciphersuites TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256
    ssl-default-server-options no-sslv3 no-tlsv10 no-tlsv11 no-tls-tickets
    # DH Parameter file
    ssl-dh-param-file /etc/haproxy/dhparam
    # User that HAProxy will run as
    user haproxy
    group haproxy
    daemon

defaults
    log global
    mode http
    option httplog
    option dontlognull
    timeout connect 5000
    timeout client 50000
    timeout server 50000

#---------------------------------------------------------------------
# HAProxy Stats Config
# To use TLS on stats page, uncomment the latter 'ssl crt' part of the bind line
# Certificate should be a combined private key and certificate file
# e.g. cat private.key certificate.crt > combined.pem
#---------------------------------------------------------------------
listen stats
    bind *:8443 # ssl crt /etc/haproxy/combined.pem
    mode http
    # Compiled with a Prometheus metrics endpoint. Configure Prometheus to scrape url:8443/metrics
    http-request use-service prometheus-exporter if { path /metrics }
    option forwardfor
    option httpclose
    stats enable
    stats show-legends
    stats refresh 15s
    stats uri /stats
    stats realm Haproxy\ Statistics
    # To add basic simple auth to the stats page, uncomment below
    # stats auth adminuser:adminpass 

#---------------------------------------------------------------------
# K8s API Server (:6443 -> :6443 API server on Control Plane)
#---------------------------------------------------------------------
frontend FE_apiserver
    bind *:6443
    mode tcp
    option tcplog
    default_backend BE_apiserver

backend BE_apiserver
    option httpchk GET /healthz
    http-check expect status 200
    mode tcp
    option ssl-hello-chk
    balance roundrobin
    server k8s-cp-01 192.168.1.151:6443 check
    server k8s-cp-02 192.168.1.152:6443 check
    server k8s-cp-03 192.168.1.153:6443 check

#---------------------------------------------------------------------
# K8s HTTP Requests (:80 -> :30080 Nodeport on Workers)
#---------------------------------------------------------------------
frontend FE_http
    bind *:80
    mode tcp
    option tcplog
    default_backend BE_http

backend BE_http
    balance roundrobin
    mode tcp
    server k8s-wk-01 192.168.1.154:30080 check
    server k8s-wk-02 192.168.1.155:30080 check
    server k8s-wk-03 192.168.1.156:30080 check

#---------------------------------------------------------------------
# K8s HTTP Requests (:443 -> :30443 Nodeport on Workers)
#---------------------------------------------------------------------
frontend FE_https
    bind *:443
    mode tcp
    option tcplog
    default_backend BE_https

backend BE_https
    balance roundrobin
    mode tcp
    server k8s-wk-01 192.168.1.154:30443 check
    server k8s-wk-02 192.168.1.155:30443 check
    server k8s-wk-03 192.168.1.156:30443 check

The global section defines the general settings for HAProxy's runtime environment and system-level configurations.

global
    log /dev/log local0
    log /dev/log local1 notice
    chroot /var/lib/haproxy
    stats timeout 30s
    # Intermediate configuration from Mozilla generator
    ssl-default-bind-ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384
    ssl-default-bind-ciphersuites TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256
    ssl-default-bind-options prefer-client-ciphers no-sslv3 no-tlsv10 no-tlsv11 no-tls-tickets
    ssl-default-server-ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384
    ssl-default-server-ciphersuites TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256
    ssl-default-server-options no-sslv3 no-tlsv10 no-tlsv11 no-tls-tickets
    # DH Parameter file
    ssl-dh-param-file /etc/haproxy/dhparam
    # User that HAProxy will run as
    user haproxy
    group haproxy
    daemon

Explanations (global)

• log /dev/log local0:
  • Specifies where HAProxy should log its activity. /dev/log is the Unix socket used for logging, and local0 is the facility level for logging (used to differentiate between types of log messages).
• log /dev/log local1 notice:
  • Similar to the previous line but for local1 facility. The notice priority level specifies that HAProxy will log messages at this level or higher (e.g., alerts, errors).
• chroot /var/lib/haproxy:
  • Changes the root directory of HAProxy to /var/lib/haproxy for security purposes, isolating it from the rest of the file system. This minimizes the impact of any potential security breaches.
• stats timeout 30s:
  • Specifies the timeout for the statistics page or other management functions. In this case, the timeout is set to 30 seconds.
• ssl-default-bind-ciphers <ciphers>:
  • Lists the allowed ciphers for SSL/TLS binding (client-side connections). This ensures that only secure ciphers are used for encrypting traffic. The ciphers listed are based on Mozilla's intermediate security configuration.
• ssl-default-bind-ciphersuites <ciphersuites>:
  • Specifies the ciphersuites used for binding when operating with TLS 1.3. This line ensures that the most secure algorithms are prioritized in newer TLS versions.
• ssl-default-bind-options prefer-client-ciphers no-sslv3 no-tlsv10 no-tlsv11 no-tls-tickets:
  • Configures additional SSL options:
    • prefer-client-ciphers: Favors the client's ciphers over the server's, which can be useful for compatibility.
    • no-sslv3, no-tlsv10, no-tlsv11: Disables the insecure SSLv3, TLS 1.0, and TLS 1.1 protocols.
    • no-tls-tickets: Disables TLS session tickets, enhancing forward secrecy.
• ssl-default-server-ciphers <ciphers>:
  • Specifies the ciphers used for SSL/TLS server-side connections (outbound connections). Similar to ssl-default-bind-ciphers, but this applies to the server's side of connections.
• ssl-default-server-ciphersuites <ciphersuites>:
  • Specifies the ciphersuites for TLS 1.3 connections on the server side, ensuring the use of modern, secure algorithms.
• ssl-default-server-options no-sslv3 no-tlsv10 no-tlsv11 no-tls-tickets:
  • Disables outdated SSL/TLS protocols and session tickets for server-side connections, enhancing security.
• ssl-dh-param-file /etc/haproxy/dhparam:
  • Specifies the file path for the Diffie-Hellman (DH) parameters, used for generating keys in perfect forward secrecy (PFS). This file contains DH parameters to establish secure SSL/TLS connections. See additional note on DH parameter file.
    
• user haproxy:
  • Defines the user under which the HAProxy process runs. Running as a non-root user (like haproxy) enhances security.
• group haproxy:
  • Specifies the group under which the HAProxy process runs. Group-based permission control further enhances security.
• daemon:
  • Runs HAProxy as a background process (daemon), meaning it detaches from the terminal after starting.

The defaults section defines default settings that apply to all subsequent frontend, backend, or listen sections unless overridden.

defaults
    log global
    mode http
    option httplog
    option dontlognull
    timeout connect 5000
    timeout client 50000
    timeout server 50000

Explanations (defaults)

• log global:
  • Instructs HAProxy to inherit the logging options defined in the global section. This ensures consistent logging behavior.
• mode http:
  • Sets the default mode to HTTP. HAProxy can operate in various modes (e.g., tcp, http), and this configures it to handle HTTP traffic by default.
• option httplog:
  • Enables HTTP-specific logging. This logs additional HTTP-related information, such as the HTTP method, status code, and URL.
• option dontlognull:
  • Prevents logging of connections that result in no data exchange (e.g., if the client connects and immediately disconnects without sending any request).
• timeout connect 5000:
  • Defines the maximum time (5 seconds) to wait for a connection attempt to a backend server before timing out.
• timeout client 50000:
  • Sets the maximum time (50 seconds) to wait for data from a client before timing out. This includes request headers and body data.
• timeout server 50000:
  • Sets the maximum time (50 seconds) to wait for a response from a backend server before timing out. This includes response headers and body data.

This section defines a listen block, which combines the functionalities of a frontend (handling incoming requests) and a backend (handling outgoing requests) for monitoring HAProxy statistics and exposing metrics.

listen stats
    bind *:8443 # ssl crt /etc/haproxy/combined.pem
    mode http
    # HAProxy is usually compiled with a Prometheus metrics endpoint. Configure Prometheus to scrape url:8443/metrics
    http-request use-service prometheus-exporter if { path /metrics }
    option forwardfor
    option httpclose
    stats enable
    stats show-legends
    stats refresh 15s
    stats uri /stats
    stats realm Haproxy\ Statistics

Explanations (listen)

• listen stats:
  • Defines a new listen section named stats. This section handles incoming requests on a specific port and provides a monitoring interface, including Prometheus metrics and HAProxy's built-in statistics.
• bind *:8443 # ssl crt /etc/haproxy/combined.pem:
  • Binds this listener to all available IP addresses (*) on port 8443. This means HAProxy will listen for HTTP or HTTPS traffic on that port.
    
    The commented-out part # ssl crt /etc/haproxy/combined.pem indicates that SSL could be enabled with a certificate, (it's commented out so is not enabled in this example).
    
    HAProxy requires that both certificate and private key be combined into a single file. The certificate in this example would be located at /etc/haproxy/combined.pem.
• mode http:
  • Sets the mode to HTTP for this listener. This means it will handle HTTP requests, as opposed to TCP or other modes.
• http-request use-service prometheus-exporter if { path /metrics }:
  • Directs HAProxy to use the Prometheus exporter service when the incoming request's path is /metrics. This enables HAProxy to expose Prometheus-compatible metrics at the specified URL (e.g., https://example.com:8443/metrics). The Prometheus Exporter service is a built-in feature that allows HAProxy to export its performance metrics in a format compatible with the Prometheus monitoring system. (A Prometheus deployment would need to have this endpoint added to it's configuration).
    
• option forwardfor:
  • Adds the X-Forwarded-For header to incoming HTTP requests, passing the original client's IP address to the backend server. This is useful for logging or analytics when the HAProxy instance is sitting between clients and servers.
• option httpclose:
  • Forces HAProxy to close the connection with the client after each request is completed. This disables HTTP keep-alive, meaning each request requires a new connection, which may be useful in certain scenarios, like optimizing resource use or managing legacy backend servers.
• stats enable:
  • Enables HAProxy's statistics feature for this listener. It allows access to the HAProxy statistics page (a built-in web page showing traffic, server health, and performance metrics).
• stats show-legends:
  • Enables additional descriptions or legends on the HAProxy statistics page to explain various metrics and data fields. This can be helpful when viewing the stats page for a clearer understanding of the displayed data.
• stats refresh 15s:
  • Configures the statistics page to automatically refresh every 15 seconds. This ensures real-time monitoring of HAProxy performance metrics.
• stats uri /stats:
  • Specifies the URL path (/stats) for accessing the HAProxy statistics page. e.g. https://example.com:8443/stats
• stats realm Haproxy\ Statistics:
  • Defines a custom realm (or authentication prompt) for accessing the stats page. The realm name, "Haproxy Statistics" will appear in the browser's authentication dialog box when access control is enabled, prompting users for credentials. The backslash \ escapes the space, so it is correctly interpreted as a single string.