Configuring the HAProxy load balancer

Installing Bamboo Data Center

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

The purpose of a load balancer is to efficiently distribute incoming network traffic between Bamboo nodes in a warm standby cluster configuration. If you don't have a particular preference or policy for load balancers, you can use HAProxy, which is a popular open-source load balancer. Learn how to get up and running with HAProxy and see sample configurations that you can use as reference points for creating your own setup.

Before you begin

Download and install HAProxy from http://www.haproxy.org/.

Make sure that you're using HAProxy 1.5.0 or newer. Earlier versions of HAProxy don't support HTTPS. To check which version of HAProxy you use, run the following command:

haproxy --version

To configure HAProxy:

  1. Review the contents of the haproxy.cfg file and customize it for your environment.

    The haproxy.cfg file is typically located at /etc/haproxy/haproxy.cfg. See https://docs.haproxy.org/ for more information about configuring HAProxy. Refer to the examples of how to configure HAProxy in different scenarios:

    Example 1: Simple configuration

    The following is an example of a minimal configuration that sets up a frontend on port 80/TCP (HTTP) in front of two Bamboo servers running on the default HTTP service port 8085/TCP, and the JMS service frontend and backend on port 54663/TCP.

    tip/resting Created with Sketch.

    In this configuration example, the HAProxy statistics page is disabled by default. To do enable it, change the stats disabled line to stats enabled. Then, once the haproxy service is running, navigate to http://<bamboo-url>/stats.

    However, by default, the HAProxy statistics page doesn't require authentication. In case of any security concerns, you can enforce basic authentication by adding a stats auth <username:password> line to the configuration. Alternatively, disable access to the page by changing the stats enabled line to stats disabled

    For more information, see Exploring the HAProxy Stats Page (What You Should Know).

    # GENERAL CONFIG
    global
        log stdout format raw daemon
        daemon
    defaults
        mode tcp
        log global
        option tcplog
        option dontlognull
        retries 5
        timeout connect 10s
        timeout client 1m
        timeout server 2m
        timeout check 15s
    
    # HTTP FRONTEND
    frontend bamboo_http_frontend
        mode http
        option httpslog
        option log-separate-errors
        bind *:80
        use_backend bamboo_http_backend
    
    # HTTP BACKEND
    backend bamboo_http_backend
        mode http
        option httpchk GET /rest/api/latest/status
        option forwardfor
        option log-health-checks
        http-request set-header X-Forwarded-Port %[dst_port]
        
        # Stats page (disabled)
        stats disable
        stats hide-version
        stats realm Haproxy\ Statistics
        stats uri /stats
    
        # Check status every 10s, UP after two successfull checks, DOWN after one failed check
        default-server check inter 10s downinter 10s rise 2 fall 1
    
        # Two nodes. If a switchover occours, HAProxy will follow the node responding to positive health checks
        server bamboo_node1 bamboo1.mydomain.net:8085 check
        server bamboo_node2 bamboo2.mydomain.net:8085 check
    
    # TCP FRONTEND
    frontend bamboo_tcp_frontend
        option logasap
        bind *:54663
        use_backend bamboo_jms_backend if { dst_port 54663 }
    
    # TCP BACKEND 
    backend bamboo_jms_backend
        # HAProxy will trust the HTTP checks and will not probe the JMS ports directly
        server bamboo_node1 bamboo1.mydomain.net:54663 track bamboo_https_backend/bamboo_node1
        server bamboo_node2 bamboo2.mydomain.net:54663 track bamboo_https_backend/bamboo_node2
    Example 2: Advanced configuration

    The following is an example of a more complex HAProxy configuration, which assumes that:

    • This is a 3-node Bamboo warm standby cluster.

    • HAProxy will listen on ports:
      • 80/TCP for HTTP-to-HTTPS redirection only
      • 443/TCP for HTTPS connections
      • 54663/TCP for JMS connections
    • HAProxy handles SSL offloading.

    • HAProxy expects that Bamboo’s Tomcat backend servers have SSL configured on port 8443.

    • Both SSL certificate and key files used by HAProxy are installed in /usr/local/etc/haproxy/ssl as bamboo.mydomain.net_ssl_bundle.pem and bamboo.mydomain.net_ssl_bundle.pem.key.

    • A redirect from HTTP on port 80/TCP to HTTPS 443/TCP is implicit.
    • There is a tarpit configuration to prevent Bamboo Agents from spamming the active server with sign-in requests during a service switchover.

    • HAProxy enforces SSL-Passthrough on the JMS port, meaning that Bamboo must be configured to use SSL on the JMS service to authenticate the agents.

    tip/resting Created with Sketch.

    In this configuration example, the HAProxy statistics page is enabled by default. This allows you to monitor the health of your cluster by navigating to the HAProxy statistics page at https://<bamboo-url>/stats.

    However, by default, the HAProxy statistics page doesn't require authentication. In case of any security concerns, you can enforce basic authentication by adding a stats auth <username:password> line to the configuration. Alternatively, disable access to the page by changing the stats enabled line to stats disabled

    For more information, see Exploring the HAProxy Stats Page (What You Should Know).

    # GENERAL CONFIG
    global
        log stdout format raw daemon debug 
        ssl-server-verify none
        maxconn 4000 
        daemon
    
    defaults
        mode tcp
        log global
        option tcplog
        option dontlognull
        option log-health-checks
        retries 5
        timeout connect 10s
        timeout client 1m
        timeout server 2m
        timeout check 15s
    
    # HTTPS FRONTEND
    frontend bamboo_https_frontend
        mode http
        option httpslog
        option log-separate-errors
        bind *:80
        bind *:443 ssl crt /usr/local/etc/haproxy/ssl/bamboo.mydomain.net_ssl_bundle.pem
        
        # Redirect http to https
        http-request redirect scheme https code 301 if !{ ssl_fc }
    
        # Prevents Agents from spamming the Bamboo server when a switchover occurs
        # This will allow 400 HTTP connections to /agentServer/bootstrap every 10s
        # It uses X-Forwarded-For IP first and falls back to the real IP address if not found
        acl url_agent path_beg /agentServer/bootstrap
        stick-table type ip size 1m expire 10s store conn_rate(10s)
        http-request track-sc0 req.hdr_ip(X-Forwarded-For,-1) if url_agent
        acl conn_rate_abuse sc0_conn_rate gt 400
        http-request tarpit deny_status 429 if conn_rate_abuse
    
        use_backend bamboo_https_backend if { hdr(host) -m reg -i ^bamboo\.mydomain\.net(:[0-9]{1,5})?$ }
    
    # HTTP BACKEND
    backend bamboo_https_backend
        mode http
        option httpchk GET /rest/api/latest/status
        option forwardfor
        option log-health-checks
        http-request set-header X-Forwarded-Port %[dst_port]
        http-request add-header X-Forwarded-Proto https if { ssl_fc }
        
        # Check status every 10s, UP after two successfull checks, DOWN after one failed check
        default-server ssl verify none check inter 10s downinter 10s rise 2 fall 1
    
        # Stats page
        stats enable
        stats hide-version
        stats realm Haproxy\ Statistics
        stats uri /stats
    
        # Three nodes - If a switchover occours, HAProxy will follow the node responding to positive health checks
        server bamboo_node1 bamboo1.mydomain.net:8443 check
        server bamboo_node2 bamboo2.mydomain.net:8443 check
        server bamboo_node3 bamboo3.mydomain.net:8443 check
    
    # TCP FRONTEND
    frontend bamboo_tcp_frontend
        option logasap
        bind *:54663
    
        # Filter only SSL traffic to the JMS port
        tcp-request inspect-delay 5s
        tcp-request content accept if { req_ssl_hello_type 1 }
    
        use_backend bamboo_jms_backend if { dst_port 54663 }
    
    # TCP BACKEND
    backend bamboo_jms_backend
        # HAProxy will trust the HTTP checks and will not probe the JMS ports directly
        server bamboo_node1 bamboo1.mydomain.net:54663 track bamboo_https_backend/bamboo_node1
        server bamboo_node2 bamboo2.mydomain.net:54663 track bamboo_https_backend/bamboo_node2
        server bamboo_node3 bamboo3.mydomain.net:54663 track bamboo_https_backend/bamboo_node3
  2. Once you have configured haproxy.cfg correctly for your environment, start the haproxy service according to the instructions appropriate for your operating system.

Last modified on Feb 9, 2024

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.