Upgrade HAProxy Enterprise on Docker

You can upgrade HAProxy Enterprise as a Docker container.

Prepare for the upgrade Jump to heading

Issues with the HAProxy Enterprise configuration can cause the load balancer to fail after an upgrade. Even if the service is performing as desired before the upgrade, the upgrade could introduce changes that cause a failure afterward.

Validate the HAProxy Enterprise configuration file before proceeding with the upgrade.

Use the hapee-lb command with the -c option to validate configuration files.

Depending on your version, the command’s output indicates that the file is valid in these ways:
- In version 2.8 and earlier, the command indicates a valid configuration by printing Configuration file is valid in addition to setting the zero return status.
- In version 2.9 and later, the command sets the zero return status for a valid configuration but doesn’t display a message. To display the message, include the -V option on the command line.
Multiple configuration files

If you have multiple configuration files in your application, be sure to check them all in the correct order.

Validate the configuration file as follows:
Validate the configuration file
nix
sudo docker exec hapee /opt/hapee-3.3/sbin/hapee-lb -c -f /etc/hapee-3.3/hapee-lb.cfg -V

nix
sudo docker exec hapee /opt/hapee-3.3/sbin/hapee-lb -c -f /etc/hapee-3.3/hapee-lb.cfg -V
nix
sudo docker exec hapee /opt/hapee-3.2/sbin/hapee-lb -c -f /etc/hapee-3.2/hapee-lb.cfg -V

nix
sudo docker exec hapee /opt/hapee-3.2/sbin/hapee-lb -c -f /etc/hapee-3.2/hapee-lb.cfg -V
nix
sudo docker exec hapee /opt/hapee-3.0/sbin/hapee-lb -c -f /etc/hapee-3.0/hapee-lb.cfg -V

nix
sudo docker exec hapee /opt/hapee-3.0/sbin/hapee-lb -c -f /etc/hapee-3.0/hapee-lb.cfg -V
nix
sudo docker exec hapee /opt/hapee-2.8/sbin/hapee-lb -c -f /etc/hapee-2.8/hapee-lb.cfg -V

nix
sudo docker exec hapee /opt/hapee-2.8/sbin/hapee-lb -c -f /etc/hapee-2.8/hapee-lb.cfg -V
nix
sudo docker exec hapee /opt/hapee-2.6/sbin/hapee-lb -c -f /etc/hapee-2.6/hapee-lb.cfg -V

nix
sudo docker exec hapee /opt/hapee-2.6/sbin/hapee-lb -c -f /etc/hapee-2.6/hapee-lb.cfg -V
Alerts and warnings that appear in the console output explain the errors encountered. An alert is a fatal condition and prohibits the service from starting. A warning indicates a condition that isn’t fatal now but may become fatal in the target release. Address all the errors until you receive the successful output: Configuration file is valid.
Preserve application files in the old container by copying them to the host computer. For example, copy the configuration directory for version 2.9:
```
nix
sudo docker cp hapee:/etc/hapee-2.9 ./
```
```
nix
sudo docker cp hapee:/etc/hapee-2.9 ./
```
Copy map files, ACL files, certificates, and so on.

Upgrade HAProxy Enterprise Jump to heading

The following procedure installs a new major version of HAProxy Enterprise.

Log into the HAProxy Docker registry using your HAProxy Enterprise license key as the username and password.
```
nix
sudo docker login https://registry.haproxy.com
```
```
nix
sudo docker login https://registry.haproxy.com
```
Our registry has moved!

In previous versions of this guide, we used the URL https://hapee-registry.haproxy.com.

Pull the HAProxy Enterprise image.

Pull software image

nix
sudo docker pull registry.haproxy.com/haproxytech/haproxy-enterprise:3.3r1

nix
sudo docker pull registry.haproxy.com/haproxytech/haproxy-enterprise:3.3r1

nix
sudo docker pull registry.haproxy.com/haproxytech/haproxy-enterprise:3.2r1

nix
sudo docker pull registry.haproxy.com/haproxytech/haproxy-enterprise:3.2r1

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

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

nix
sudo docker pull registry.haproxy.com/haproxytech/haproxy-enterprise:2.8r1

nix
sudo docker pull registry.haproxy.com/haproxytech/haproxy-enterprise:2.8r1

nix
sudo docker pull registry.haproxy.com/haproxytech/haproxy-enterprise:2.6r1

nix
sudo docker pull registry.haproxy.com/haproxytech/haproxy-enterprise:2.6r1

Stop and remove any previously running HAProxy Enterprise containers:

nix
sudo docker stop <OLD CONTAINER NAME>
sudo docker rm <OLD CONTAINER NAME>

nix
sudo docker stop <OLD CONTAINER NAME>
sudo docker rm <OLD CONTAINER NAME>

Start the new Docker container, referencing the directory containing your applications files as a volume by using the -v flag.

Start new container

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

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

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

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

nix
sudo docker run \
  --name hapee-3.0 \
  -d \
  -p 80:80 \
  -p 443:443 \
  -p 5555:5555 \
  -v $(pwd):/etc/hapee-3.0r1  \
  --restart=unless-stopped \
  registry.haproxy.com/haproxytech/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.0r1  \
  --restart=unless-stopped \
  registry.haproxy.com/haproxytech/haproxy-enterprise:3.0r1

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

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

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

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

Review the configuration to ensure HAProxy Enterprise successfully locates application files such as the configuration file, map files, ACL files, TLS certificates, and so on.

Validate your HAProxy Enterprise configuration file against the new version of HAProxy Enterprise.

Use the hapee-lb command with the -c option to validate configuration files.

Depending on your version, the command’s output indicates that the file is valid in these ways:
- In version 2.8 and earlier, the command indicates a valid configuration by printing Configuration file is valid in addition to setting the zero return status.
- In version 2.9 and later, the command sets the zero return status for a valid configuration but doesn’t display a message. To display the message, include the -V option on the command line.
Multiple configuration files

If you have multiple configuration files in your application, be sure to check them all in the correct order.

Validate the configuration file as follows:
Validate the configuration file
nix
sudo docker exec hapee /opt/hapee-3.3/sbin/hapee-lb -c -f /etc/hapee-3.3/hapee-lb.cfg -V

nix
sudo docker exec hapee /opt/hapee-3.3/sbin/hapee-lb -c -f /etc/hapee-3.3/hapee-lb.cfg -V
nix
sudo docker exec hapee /opt/hapee-3.2/sbin/hapee-lb -c -f /etc/hapee-3.2/hapee-lb.cfg -V

nix
sudo docker exec hapee /opt/hapee-3.2/sbin/hapee-lb -c -f /etc/hapee-3.2/hapee-lb.cfg -V
nix
sudo docker exec hapee /opt/hapee-3.0/sbin/hapee-lb -c -f /etc/hapee-3.0/hapee-lb.cfg -V

nix
sudo docker exec hapee /opt/hapee-3.0/sbin/hapee-lb -c -f /etc/hapee-3.0/hapee-lb.cfg -V
nix
sudo docker exec hapee /opt/hapee-2.8/sbin/hapee-lb -c -f /etc/hapee-2.8/hapee-lb.cfg -V

nix
sudo docker exec hapee /opt/hapee-2.8/sbin/hapee-lb -c -f /etc/hapee-2.8/hapee-lb.cfg -V
nix
sudo docker exec hapee /opt/hapee-2.6/sbin/hapee-lb -c -f /etc/hapee-2.6/hapee-lb.cfg -V

nix
sudo docker exec hapee /opt/hapee-2.6/sbin/hapee-lb -c -f /etc/hapee-2.6/hapee-lb.cfg -V
Alerts and warnings that appear in the console output explain the errors encountered. An alert is a fatal condition and prohibits the service from starting. A warning indicates a condition that isn’t fatal now but may become fatal in the target release. Address all the errors until you receive the successful output: Configuration file is valid.
In addition to upgrading the HAProxy Enterprise package, the upgrade process upgrades many of the modules available with HAProxy Enterprise. Verify that the modules you use have been upgraded.

To see which modules you use, review your HAProxy Enterprise configuration file and look for modules named in the module-load directive, for example:
```
hapee-lb.cfg
haproxy
global
  module-load hapee-lb-waf.so
```
```
hapee-lb.cfg
haproxy
global
  module-load hapee-lb-waf.so
```

List modules installed on your node by running the following command:

List modules

nix
sudo docker exec $(sudo docker ps -qf "name=hapee-3.3r1") apt list --installed | grep hapee

nix
sudo docker exec $(sudo docker ps -qf "name=hapee-3.3r1") apt list --installed | grep hapee

nix
sudo docker exec $(sudo docker ps -qf "name=hapee-3.2r1") apt list --installed | grep hapee

nix
sudo docker exec $(sudo docker ps -qf "name=hapee-3.2r1") apt list --installed | grep hapee

nix
sudo docker exec $(sudo docker ps -qf "name=hapee-3.0r1") apt list --installed | grep hapee

nix
sudo docker exec $(sudo docker ps -qf "name=hapee-3.0r1") apt list --installed | grep hapee

nix
sudo docker exec $(sudo docker ps -qf "name=hapee-2.8r1") apt list --installed | grep hapee

nix
sudo docker exec $(sudo docker ps -qf "name=hapee-2.8r1") apt list --installed | grep hapee

nix
sudo docker exec $(sudo docker ps -qf "name=hapee-2.6r1") apt list --installed | grep hapee

nix
sudo docker exec $(sudo docker ps -qf "name=hapee-2.6r1") apt list --installed | grep hapee

Verify that the installed modules are up to date with the new version of HAProxy Enterprise. Upgrade any modules that are out of date. For more information, see Enterprise modules.

Use systemctl reload to reload the load balancer configuration with the copied configuration file:

Reload service

haproxy
sudo systemctl reload hapee-3.3-lb

haproxy
sudo systemctl reload hapee-3.3-lb

haproxy
sudo systemctl reload hapee-3.2-lb

haproxy
sudo systemctl reload hapee-3.2-lb

haproxy
sudo systemctl reload hapee-3.0-lb

haproxy
sudo systemctl reload hapee-3.0-lb

haproxy
sudo systemctl reload hapee-2.8-lb

haproxy
sudo systemctl reload hapee-2.8-lb

haproxy
sudo systemctl reload hapee-2.6-lb

haproxy
sudo systemctl reload hapee-2.6-lb

Product Documentation

API Documentation

Configuration Documentation

Install the VM image

Upgrade HAProxy Enterprise on Docker

Prepare for the upgrade Jump to heading

Upgrade HAProxy Enterprise Jump to heading

Install the VM image

Product Documentation

API Documentation

Configuration Documentation

Prepare for the upgrade Jump to heading #

Upgrade HAProxy Enterprise Jump to heading #

Prepare for the upgrade Jump to heading

Upgrade HAProxy Enterprise Jump to heading