Skip to content

Commit

Permalink
copy edit
Browse files Browse the repository at this point in the history
  • Loading branch information
@jddocs
jddocs committed Dec 3, 2024
1 parent 450da27 commit 162942a
Showing 1 changed file with 42 additions and 36 deletions.
78 changes: 42 additions & 36 deletions ...cing/getting-started-with-haproxy-tcp-load-balancing-and-health-checks/index.md
View file
Original file line number Diff line number Diff line change
@@ -1,48 +1,53 @@
---
slug: getting-started-with-haproxy-tcp-load-balancing-and-health-checks
title: "Getting Started with HAProxy TCP Load Balancing and Health Checks"
description: "Learn how to install and configure HAProxy for load balancing and health checks on Ubuntu, CentOS Stream, and openSUSE Leap in this guide."
description: "Learn how to install and configure HAProxy for load balancing and health checks on Ubuntu, CentOS Stream, and openSUSE Leap."
authors: ["Tom Henderson"]
contributors: ["Tom Henderson"]
published: 2024-08-21
keywords: ['haproxy','haproxy load balancing','haproxy setup tutorial','haproxy active health checks','haproxy passive health checks','install haproxy on ubuntu','install haproxy on centos','install haproxy on opensuse','haproxy frontend configuration','haproxy backend configuration','haproxy health check configuration']
license: '[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0)'
external_resources:
- '[HAProxy Official Documentation](https://www.haproxy.com/documentation/)'

---

[HAProxy](https://www.haproxy.org/) serves as a reverse proxy between frontend client requests and backend server resources. HAProxy can be configured at Layer 4 (network) or Layer 7 (application). The most common use of HAProxy is as an intelligent network load balancer. In this role, HAProxy routes incoming frontend traffic to designated backend instances. By default, no load balancing is applied. However, you can configure HAProxy to use various load balancing methods, including:
[HAProxy](https://www.haproxy.org/) serves as a reverse proxy between frontend client requests and backend server resources, and can be configured at Layer 4 (network) or Layer 7 (application). A common use of HAProxy is as an intelligent network load balancer. In this role, HAProxy routes incoming frontend traffic to designated backend instances. By default, no load balancing is applied, however, HAProxy can be configured to use various load balancing methods, including:

- **Round Robin**: Distributes incoming connections evenly across all available backend servers by sequentially assigning each new connection to the next server in the pool.
- **Least Conn**: Directs incoming connections to the backend server with the fewest active connections, helping to balance the load more evenly based on current server utilization.
- **Least Connections**: Directs incoming connections to the backend server with the fewest active connections, helping to balance the load more evenly based on current server utilization.
- **Health Checks**: Continuously monitors the health of backend servers. Servers that fail health checks are automatically removed from the pool until they recover, ensuring that only healthy servers receive traffic.

This guide demonstrates how to install HAProxy onto three common Linux distributions: Ubuntu, CentOS Stream, and openSUSE Leap. It also provides instructions for developing a proof-of-concept based on HAProxy TCP load balancing and health check features.
This guide demonstrates how to install HAProxy onto three Linux distributions: Ubuntu, CentOS Stream, and openSUSE Leap. It also uses an example WordPress deployment with sample configurations to implement and test HAProxy's TCP load balancing and health check features.

## Before You Begin

1. If you do not already have a virtual machine to use, create a Compute Instance. HAProxy can be deployed on a simple [Nanode](https://www.linode.com/blog/linode/akamai_cloud_computing_price_update/). Under **Linux Distribution**, choose either `Ubuntu 24.04 LTS`, `CentOS Stream 9`, or `openSUSE Leap 15.6`, and assign the instance to a VLAN. See our [Getting Started with Linode](/docs/products/platform/get-started/) and [Creating a Compute Instance](/docs/products/compute/compute-instances/guides/create/) guides.
1. To be used as your HAProxy instance, deploy a Compute Instance running one of the `Ubuntu 24.04 LTS`, `CentOS Stream 9`, or `openSUSE Leap 15.6` distributions, and assign the instance to a VLAN. See our [Getting Started with Linode](/docs/products/platform/get-started/) and [Creating a Compute Instance](/docs/products/compute/compute-instances/guides/create/) guides.

HAProxy can be deployed using a [Nanode](https://www.linode.com/pricing/) plan for testing purposes. See HAProxy's [hardware recommendations](https://www.haproxy.com/documentation/haproxy-enterprise/getting-started/installation/linux/#hardware-recommendations) for production-level workloads.

1. Follow our [Setting Up and Securing a Compute Instance](/docs/products/compute/compute-instances/guides/set-up-and-secure/) guide to update your system. You may also wish to set the timezone, configure your hostname, create a limited user account, and harden SSH access.

1. This guide uses simple WordPress backend instances to demonstrate how HAProxy controls network traffic flows at both the TCP/Network (Layer 4) and HTTP/Application (Layer 7) levels. Follow the steps in our [Deploy WordPress through the Linode Marketplace](/docs/marketplace-docs/guides/wordpress/) guide to create three backend WordPress test instances. Under **WordPress Setup**, fill out all of the required fields and use the default values, along with the following options:
1. This guide uses WordPress backend instances to demonstrate how HAProxy controls network traffic flows at both the TCP/Network (Layer 4) and HTTP/Application (Layer 7) levels. Follow the steps in our [Deploy WordPress through the Linode Marketplace](/docs/marketplace-docs/guides/wordpress/) guide to create three backend WordPress test instances. Fill out all required fields under **WordPress Setup**, and use default values along with the following options:

- **The stack you are looking to deploy Wordpress on**: Choose either **LAMP** or **LEMP**.
- **Website title**: Enter `backend1`, `backend2`, and `backend3`, respectively.
- **Website title**: For each instance, enter `backend1`, `backend2`, and `backend3`, respectively.
- **Region**: Select the same location the HAProxy instance is in.
- **Linode Plan**: A **Shared CPU**, **Nanode 1 GB** is sufficient to test and demonstrate HAProxy options.
- **Linode Label**: Once again, enter `backend1`, `backend2`, and `backend3`, respectively.
- **Linode Label**: Label each instance to correspond with the website titles `backend1`, `backend2`, and `backend3`, respectively.
- **VLAN**: Attach the instances to the same VLAN as the HAProxy instance.

Each of these servers are generated with an `index.html` home page that indicates the name of the server (`backend1`, `backend2`, `backend3`). Open a web browser and check each server by its IP address to verify that the example test servers are functioning. Take note of the IP addresses of the three instances, as you need them later.
Each server is generated with an `index.html` home page that indicates the given title of the website hosted on the instance (`backend1`, `backend2`, or `backend3`). Open a web browser and navigate to each server's IP address to verify that the example test servers are functioning. Take note of the IP addresses of each backend instance, as they are used later.

{{< note >}}
This guide is written for a non-root user. Commands that require elevated privileges are prefixed with `sudo`. If you’re not familiar with the `sudo` command, see the [Users and Groups](/docs/guides/linux-users-and-groups/) guide.
{{< /note >}}

## Install HAProxy

To install HAProxy, log in to your HAProxy instance as `root`.
To install HAProxy, log into the HAProxy instance as your limited sudo user, and complete the steps below.

1. Follow the instructions below for your distribution:
1. Select your distribution, and use the command to install HAProxy:

{{< tabs >}}
{{< tab "Ubuntu 24.04 LTS" >}}
Expand Down Expand Up @@ -107,13 +112,13 @@ To install HAProxy, log in to your HAProxy instance as `root`.
sudo systemctl start haproxy
```

1. Also use `systemctl` to automatically start HAProxy after a reboot:
1. Use `systemctl` to configure HAProxy to automatically start after a reboot:

```command
sudo systemctl enable haproxy
```

1. Verify that HAProxy is `active (running)`:
1. Verify HAProxy is `active (running)`:

```command
systemctl status haproxy
Expand All @@ -137,21 +142,22 @@ To install HAProxy, log in to your HAProxy instance as `root`.
└─46018 /usr/sbin/haproxy -sf 45988 -x sockpair@5 -Ws -f /etc/haproxy/haproxy.cfg -p /run/haproxy.pid -S /run/haproxy-master.sock
```

### HAProxy Configuration File
## The HAProxy Configuration File

HAProxy is controlled through its configuration file and the CLI. The HAProxy configuration file contains the settings needed to perform network balancing and flow control. A default configuration file is created at `/etc/haproxy/haproxy.cfg` during HAProxy installation. It can be edited with `nano` or any other command line text editor:
HAProxy is controlled through its configuration file and the CLI. The default HAProxy configuration file is created at `/etc/haproxy/haproxy.cfg` during installation, and contains the settings needed to perform network balancing and flow control. It can be edited with any command line-based text editor.

To edit and use the TCP load balancing and health check functions in this guide, open the HAProxy configuration file with the text editor of your choice:

```command
sudo nano /etc/haproxy/haproxy.cfg
```

## TCP Load Balancing

Load balancing is defined in two sections of the HAProxy configuration file: `frontend` and `backend`.
Load balancing is defined in two sections of the HAProxy configuration file: `frontend` and `backend`. Below are example `frontend` and `backend` configurations for TCP load balancing:

### Frontend Configuration

This is an example `frontend` configuration for TCP load balancing:
### Frontend Configuration

```file {title="/etc/haproxy/haproxy.cfg"}
frontend web-test
Expand Down Expand Up @@ -183,33 +189,33 @@ backend web-test
## TCP Health Checks
HAProxy’s load balancing function can also select servers based on their health status. Health checks can be either active or passive. An active health check probes each backend server individually for specific health attributes. In contrast, a passive check relies on basic connection error information by protocol (Layer 4/TCP or Layer7/HTTP).
HAProxy’s load balancing function can also select servers based on their health status. Health checks can be either active or passive. An active health check probes each backend server individually for specific health attributes, whereas a passive check relies on basic connection error information by protocol (Layer 4/TCP or Layer7/HTTP).
To enable a basic server health check, simply include the `check` keyword in the `server` entry of your HAProxy configuration file, like so:
To enable a basic server health check, include the `check` keyword in the `server` entry of your HAProxy configuration file:
```file {title="/etc/haproxy/haproxy.cfg"}
server server1 {{< placeholder "backend1_VLAN_IP_ADDRESS" >}}:80 check
```
When the `check` keyword is included, HAProxy sends a SYN/ACK to determine if the server is active. Even though some servers correctly respond to this type of query, their services might still be down or unavailable.
When the `check` keyword is included, HAProxy sends a SYN/ACK request to determine if a server is active. In some cases, servers may correctly respond to this type of query, while individual services and applications may still be down or unavailable.
### Active TCP Health Checks
Active health checks provide more sophisticated monitoring by sending application-specific queries to the backend servers and expecting a valid response.
Active health checks provide more sophisticated monitoring by sending application-specific queries to backend servers and expecting a valid response in return.
Include the `inter` keyword to have HAProxy check server health at specified intervals, for example:
To have HAProxy check server health at specified intervals, include the `inter` keyword along with an interval value. For example:
```file {title="/etc/haproxy/haproxy.cfg"}
server server1 {{< placeholder "backend1_VLAN_IP_ADDRESS" >}}:80 check inter 4
```
In this example, HAProxy checks the first server in the pool every four seconds. If the server does not respond, it is marked as down. This process is similar to a ping-type health check that verifies server availability.
In this example, HAProxy checks the first server in the pool every four seconds. If the server does not respond as expected, it is marked as down. This process functions like a ping-style health check to verify server availability.
### Passive TCP Health Checks
HAProxy uses the TCP protocol to perform passive health checks on backend servers. With passive health checks, HAProxy monitors Layer 4 (TCP) traffic for errors and marks a server as down when a specified error limit is reached.
Here's an example of the syntax for a passive health check:
Below is an example of the syntax used for a passive health check:
```file {title="/etc/haproxy/haproxy.cfg"}
server backend1 {{< placeholder "backend1_VLAN_IP_ADDRESS" >}}:80 check observe layer4 error-limit 10 on-error mark-down
Expand All @@ -221,13 +227,13 @@ This configuration specifies a passive health check that observes TCP errors (`o
Set the HAProxy configuration file to perform TCP load balancing with basic passive health checks.
1. Open the HAProxy configuration file with `nano` or another command line text editor:
1. Open the HAProxy configuration file with the text editor of your choice:
```command
sudo nano /etc/haproxy/haproxy.cfg
```
1. Append the following code to the end of the file:
1. Append the following code to the end of the file, and save your changes:
```file {title="/etc/haproxy/haproxy.cfg"}
frontend web-test
Expand All @@ -243,29 +249,29 @@ Set the HAProxy configuration file to perform TCP load balancing with basic pass
server server3 {{< placeholder "backend3_VLAN_IP_ADDRESS" >}}:80 check
```
When done, press <kbd>CTRL</kbd>+<kbd>X</kbd>, followed by <kbd>Y</kbd> then <kbd>Enter</kbd> to save the file and exit `nano`.

1. After making any changes to the configuration file, use the following command to restart HAProxy and enable those changes:
1. Restart HAProxy to enable the changes made to the configuration file:
```command
sudo systemctl restart haproxy
```
{{< note >}}
{{< note title="Check for syntax errors" >}}
If you encounter any errors after reloading HAProxy, run the following command to check for syntax errors in your `haproxy.cfg` file:
```command
sudo haproxy -c -f /etc/haproxy/haproxy.cfg
```
An error message is returned if the configuration file has logical or syntax errors. When the check is complete, each error is listed one per line. This command only verifies the syntax and basic logic of the configuration, it does not guarantee that the configuration works as intended when running.
An error message is returned if the configuration file has logical or syntax errors. When the check is complete, each error is listed one per line.
This command only verifies the syntax and basic logic of the configuration, and it does not guarantee that the configuration works as intended when running.
{{< /note >}}
### Test TCP Load Balancing
Load balancing can be verified by visiting the HAProxy instances's public IP address.

{{< note "CentOS Stream 9" >}}
{{< note title="CentOS Stream 9" >}}
The default firewall settings for CentOS Stream 9 must be changed prior to testing. Run the following command to temporarily open port `80` to `tcp` traffic:

```command
Expand All @@ -290,7 +296,7 @@ sudo firewall-cmd --reload
![The 2024 default WordPress homepage served from backend1.](2024-Default-WordPress-Homepage-backend1.png)
{{< note >}}
{{< note title="Certificate warnings" >}}
If your browser warns of no HTTPS/TLS certificate, ignore the warning or use the advanced settings to reach the site.
{{< /note >}}
Expand All @@ -302,15 +308,15 @@ sudo firewall-cmd --reload

![The 2024 default WordPress homepage served from backend3.](2024-Default-WordPress-Homepage-backend3.png)

The HAProxy gateway is now successfully balancing traffic between the three backend instances.
The HAProxy gateway is now successfully balancing traffic between the three backend instances using the Round Robin method.

### Verify TCP Health Checks

Health checks can be verified by removing one of the backend instances from the server pool. This should trigger a health check failure, causing HAProxy to exclude the unresponsive server from the backend pool.

1. Open the Cloud Manager and choose **Linodes**

1. Click on the three dots (**...**) to the right of `backend1`.
1. Click on the ellipsis (**...**) to the right of your first backend instance, `backend1`.

1. Choose **Power Off**, then click **Power Off Linode**.

Expand Down

0 comments on commit 162942a

Please sign in to comment.