Install HAProxy Enterprise on Docker

The HAProxy Enterprise Docker image lets you run the load balancer as a container.

Install the HAProxy Enterprise Docker container Jump to heading #

The haproxy-enterprise Docker image hosts HAProxy Enterprise and the HAProxy Data Plane API. Follow these steps to install it:

1. Log into the hapee-registry.haproxy.com Docker registry using your HAProxy Enterprise license key as both the username and password. If you do not have a key, get one by registering and requesting a free trial of HAProxy Enterprise at https://www.haproxy.com/downloads/hapee-trial/.

   nix
   sudo docker login https://hapee-registry.haproxy.com

   nix
   sudo docker login https://hapee-registry.haproxy.com

2. Pull the HAProxy Enterprise image.

   nix
   sudo docker pull hapee-registry.haproxy.com/haproxy-enterprise:3.0r1

   nix
   sudo docker pull hapee-registry.haproxy.com/haproxy-enterprise:3.0r1

3. Create an HAProxy Enterprise configuration file (i.e. hapee-lb.cfg) that defines your load balancer settings.

   You can run a container temporarily, just to get the HAProxy Enterprise configuration file from it to use as a starting point.

   nix
   sudo docker run --rm -d --name hapee hapee-registry.haproxy.com/haproxy-enterprise:3.0r1
   sudo docker cp hapee:/etc/hapee-3.0 ./
   sudo docker stop hapee
   cd hapee-3.0

   nix
   sudo docker run --rm -d --name hapee hapee-registry.haproxy.com/haproxy-enterprise:3.0r1
   sudo docker cp hapee:/etc/hapee-3.0 ./
   sudo docker stop hapee
   cd hapee-3.0

4. Start the Docker container, referencing the directory containing your configuration file as a volume by using the -v flag.

   nix
   sudo docker run \
     --name hapee-3.0 \
     -d \
     -p 80:80 \
     -p 443:443 \
     -p 5555:5555 \
     -v $(pwd):/etc/hapee-3.0  \
     --restart=unless-stopped \
     hapee-registry.haproxy.com/haproxy-enterprise:3.0r1

   nix
   sudo docker run \
     --name hapee-3.0 \
     -d \
     -p 80:80 \
     -p 443:443 \
     -p 5555:5555 \
     -v $(pwd):/etc/hapee-3.0  \
     --restart=unless-stopped \
     hapee-registry.haproxy.com/haproxy-enterprise:3.0r1

Access the Data Plane API Jump to heading #

The Data Plane API listens at port 5555. However, you must retrieve the Basic authentication credentials to access it.

1. Use the following command to read the username and password from the Data Plane API configuration file:

   nix
   sudo docker exec -it hapee-3.0 grep user: -A3 /etc/hapee-extras/dataplaneapi.yml

   nix
   sudo docker exec -it hapee-3.0 grep user: -A3 /etc/hapee-extras/dataplaneapi.yml

   output
   yaml
   user:
   - insecure: true
     password: v7xkLr4Z4Qlc
     name: admin

   output
   yaml
   user:
   - insecure: true
     password: v7xkLr4Z4Qlc
     name: admin

   Then you can verify that the API is working by calling the info function. In the example below, we use the username and password that we retrieved during the last step:

   nix
   curl -X GET --user admin:v7xkLr4Z4Qlc http://localhost:5555/v2/info

   nix
   curl -X GET --user admin:v7xkLr4Z4Qlc http://localhost:5555/v2/info

   output
   json
   {"api":{"build_date":"2021-06-01T21:18:15.000Z","version":"v2.3.2-ee2 8fdcfba"},"system":{}}

   output
   json
   {"api":{"build_date":"2021-06-01T21:18:15.000Z","version":"v2.3.2-ee2 8fdcfba"},"system":{}}

Reload or stop the services Jump to heading #

When you change your hapee-lb.cfg configuration file, you will need to reload the service for the changes to take effect. We use s6-overlay to run HAProxy Enterprise and the HAProxy Data Plane API as services.

Reload the services Jump to heading #

To reload the services:

1. Make sure that the following line is included in the global section of your HAProxy Enterprise configuration file. It ensures that you can perform a hitless reload, which means no traffic is dropped.

   haproxy
   global
     stats socket /var/run/hapee-3.0/hapee-lb.sock user hapee-lb group hapee mode 660 level admin expose-fd listeners

   haproxy
   global
     stats socket /var/run/hapee-3.0/hapee-lb.sock user hapee-lb group hapee mode 660 level admin expose-fd listeners

2. Reload the HAProxy Enterprise process with this command:

   nix
   sudo docker exec hapee-3.0 s6-svc -2 /var/run/s6/services/haproxy

   nix
   sudo docker exec hapee-3.0 s6-svc -2 /var/run/s6/services/haproxy

   The -2 argument sends a SIGUSR2 signal to the HAProxy Enterprise container, and when the load balancer receives the signal it will reload.

3. (Optional): To restart the Data Plane API, use this command:

   nix
   sudo docker exec hapee-3.0 s6-svc -t /var/run/s6/services/dataplaneapi

   nix
   sudo docker exec hapee-3.0 s6-svc -t /var/run/s6/services/dataplaneapi

Stop the services Jump to heading #

To perform a graceful shutdown of the load balancer you can issue this command:

nix
sudo docker exec hapee-3.0 s6-svc -1 /var/run/s6/services/haproxy

nix
sudo docker exec hapee-3.0 s6-svc -1 /var/run/s6/services/haproxy

The -1 argument sends a SIGUSR1 signal to the HAProxy Enterprise container. Upon receiving the signal, the load balancer unbinds its listening ports so that it will not receive any additional connections, but will continue processing existing connections until all connections close. After all connections have closed, the load balancer process terminates gracefully.

haproxy
global
  hard-stop-after 30s

haproxy
global
  hard-stop-after 30s

If needed, you can perform a hard restart by issuing the following command:

nix
sudo docker exec hapee-3.0 s6-svc -t /var/run/s6/services/haproxy

nix
sudo docker exec hapee-3.0 s6-svc -t /var/run/s6/services/haproxy

The -t argument sends a SIGTERM signal to the HAProxy Enterprise container. When the load balancer receives the SIGTERM signal, it does not shut down gracefully, but rather, it immediately terminates and closes all established connections. Note that performing a hard restart in this way may result in dropped traffic.

Installing with a custom Docker file Jump to heading #

To install a modified HAProxy Enterprise environment, create a custom Docker file. Specify the desired HAProxy Enterprise base image as in the following example, which specifies version 3.0r1:

docker
FROM hapee-registry.haproxy.com/haproxy-enterprise:3.0r1

docker
FROM hapee-registry.haproxy.com/haproxy-enterprise:3.0r1

Then add any further Dockerfile commands as needed.

The following example Dockerfile builds a HAProxy Enterprise version 3.0r1 image that includes a custom set of tools. The custom tool installation script, install_mytools-4.3.sh, must reside in the current directory.

docker
FROM hapee-registry.haproxy.com/haproxy-enterprise:3.0r1
# install internal tools
WORKDIR /tmp
ARG mytools_version="4.3"
COPY install_mytools-"$mytools_version".sh .
RUN  /tmp/install_mytools-"$mytools_version".sh

docker
FROM hapee-registry.haproxy.com/haproxy-enterprise:3.0r1
# install internal tools
WORKDIR /tmp
ARG mytools_version="4.3"
COPY install_mytools-"$mytools_version".sh .
RUN  /tmp/install_mytools-"$mytools_version".sh

See also Jump to heading #

• hard-stop-after reference
• Stopping and restarting HAProxy - Management Guide