Skip to content

How to setup HAProxy for Rancher v2.x

Article Number: 000020175

Environment

  • Rancher v2.x
  • HAProxy
  • Ubuntu / CentOS / RedHat Enterprise Linux

Situation

Install HAProxy
Update your system package index and install HAProxy using the appropriate commands for your OS:

  • Ubuntu:sudo apt update sudo apt install -y haproxy sudo systemctl enable haproxy sudo systemctl start haproxy
  • CentOS / RedHatsudo yum update sudo yum install -y haproxy sudo systemctl enable haproxy sudo systemctl start haproxy

Select and Configure a TLS Routing Strategy
Choose one of the following deployment options based on your security and SSL termination requirements.

Option A: Full SSL Termination and Re-encryption
Use this option when HAProxy handles SSL termination and re-encrypts traffic to the upstream Rancher nodes.

  1. Install Rancher by following the instructions in the documentation - https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/#_install_the_rancher_helm_chart
  2. Verify Rancher URL works when connecting directly to a Rancher node. For example:curl -k --header "Host: <RANCHER_DOMAIN>" https://<RANCHER_NODE_IP>/ping
  3. Combine your SSL certificate and private key into a single file at /etc/haproxy/cert.pem:

cat example.crt example.key > /etc/haproxy/cert.pem
4. Update the /etc/haproxy/haproxy.cfg file with the folllowing backend configurations:
frontend www-https     bind *:443 ssl crt /etc/haproxy/cert.pem     reqadd X-Forwarded-Proto:\ https     default_backend rancher-https
frontend www-http     bind *:80     reqadd X-Forwarded-Proto:\ http     default_backend rancher-http 5. Update the /etc/haproxy/haproxy.cfg file with the folllowing backend configurations:backend rancher-http     mode http     option httpchk HEAD /healthz HTTP/1.0     server rancher01 <RANCHER_NODE_1_IP>:80 check weight 1 maxconn 1024     server rancher02 <RANCHER_NODE_2_IP>:80 check weight 1 maxconn 1024     server rancher03 <RANCHER_NODE_3_IP>:80 check weight 1 maxconn 1024 backend rancher-https     mode http     option httpchk HEAD /healthz HTTP/1.0     server rancher01 <RANCHER_NODE_1_IP>:443 check weight 1 maxconn 1024 ssl verify none     server rancher02 <RANCHER_NODE_2_IP>:443 check weight 1 maxconn 1024 ssl verify none     server rancher03 <RANCHER_NODE_3_IP>:443 check weight 1 maxconn 1024 ssl verify none 6. Test the configuration:haproxy -f /etc/haproxy/haproxy.cfg -c 7. Reload HAProxy:systemctl reload haproxy

Option B: External TLS Termination
Use this option when HAProxy terminates SSL and forwards plain HTTP traffic to the Rancher backend nodes.

  1. Configure Rancher according to the https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/installation-references/helm-chart-options#_external_tls_termination.
  2. Verify HTTP connectivity directly to a Rancher node:curl --header "Host: <RANCHER_DOMAIN>" http://<RANCHER_NODE_IP>/ping
  3. Combine your SSL certificate and private key into a single file at /etc/haproxy/cert.pem:

cat example.crt example.key > /etc/haproxy/cert.pem
4. Update /etc/haproxy/haproxy.cfg with the following frontend configurations:frontend www-http     bind *:80     reqadd X-Forwarded-Proto:\ http     default_backend rancher-http frontend www-https     bind *:443 ssl crt /etc/haproxy/cert.pem     reqadd X-Forwarded-Proto:\ https     default_backend rancher-https 5. Update /etc/haproxy/haproxy.cfg with the following backend configurations:backend rancher-http     mode http     option httpchk HEAD /healthz HTTP/1.0     server rancher01 <RANCHER_NODE_1_IP>:80 check weight 1 maxconn 1024     server rancher02 <RANCHER_NODE_2_IP>:80 check weight 1 maxconn 1024     server rancher03 <RANCHER_NODE_3_IP>:80 check weight 1 maxconn 1024 6. Test the configuration:haproxy -f /etc/haproxy/haproxy.cfg -c 7. Reload HAProxy:

systemctl reload haproxy

Option C - TCP pass-through

  1. Install Rancher by following the instructions in the documentation - https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/#_install_the_rancher_helm_chart
  2. Verify Rancher URL works when connecting directly to a Rancher node. For example:
curl -k --header "Host: <RANCHER_DOMAIN>" https://<RANCHER_NODE_IP>/ping

NOTE: The default gateway for all 3 Rancher nodes must be the load balancer. Doc: https://www.haproxy.com/blog/howto-transparent-proxying-and-binding-with-haproxy-and-aloha-load-balancer/ 3. Update /etc/haproxy/haproxy.cfg with the following frontend configurations::

frontend www-http     bind *:80     mode tcp     option tcplog     tcp-request inspect-delay 5s     default_backend rancher-http

frontend www-https
    bind *:443
    mode tcp
    option tcplog
    tcp-request inspect-delay 5s
    default_backend rancher-https
4. Update /etc/haproxy/haproxy.cfg with the following backend configurations::

backend rancher-http     mode tcp     balance roundrobin     source 0.0.0.0 usesrc client     server rancher01 <RANCHER_NODE_1_IP>:80     server rancher02 <RANCHER_NODE_2_IP>:80     server rancher03 <RANCHER_NODE_3_IP>:80

backend rancher-https     mode tcp     balance roundrobin     source 0.0.0.0 usesrc client     server rancher01 <RANCHER_NODE_1_IP>:443     server rancher02 <RANCHER_NODE_2_IP>:443     server rancher03 <RANCHER_NODE_3_IP>:443 5. Validate HAProxy Configuration
Test the syntax of /etc/haproxy/haproxy.cfg before applying changes:haproxy -f /etc/haproxy/haproxy.cfg -c 6. Reload HAProxy
Apply the new configuration by reloading the systemd service:systemctl reload haproxy

(Optional) Enable HAProxy Statistics for Troubleshooting

To monitor load balancer health, add a stats listener block above the frontend configurations in /etc/haproxy/haproxy.cfg:

  1. Add the following to /etc/haproxy/haproxy.cfg before the frontend section.

listen stats     bind :9000     mode http     stats enable     stats hide-version     stats realm Haproxy\ Statistics     stats uri /     stats auth <ADMIN_USERNAME>:<ADMIN_PASSWORD> 2. Direct Access: Navigate tohttp://<LOAD_BALANCER_DOMAIN>:9000/ and log in with your configured credentials. 3. Firewalled Environment (SSH Tunnel): If port 9000 is blocked by a firewall, open an SSH tunnel from your local machine:

ssh -f -N -L 9000:127.0.0.1:9000 <USER>@<LOAD_BALANCER_IP>
4. Then, access the dashboard at http://<LOAD_BALANCER_DOMAIN>:9000/