Install the HAProxy Data Plane API on HAProxy

This section describes how to install the HAProxy Data Plane API alongside HAProxy.

Run the API using systemd Jump to heading #

Running the API as a systemd service enables you to issue CLI commands to a running haproxy process.

1. Download the latest 3.0.x package from the HAProxy Data Plane API GitHub repository. For Debian/Ubuntu, packages have the suffix .deb. For RHEL, packages have the suffix .rpm.

2. Install the package:

   Debian/Ubuntu RHEL

   nix
   sudo dpkg -i --force-depends dataplaneapi_3.0.3_linux_amd64.deb

   nix
   sudo dpkg -i --force-depends dataplaneapi_3.0.3_linux_amd64.deb

   nix
   sudo rpm -Uvh --nodeps dataplaneapi_3.0.3_linux_amd64.rpm

   nix
   sudo rpm -Uvh --nodeps dataplaneapi_3.0.3_linux_amd64.rpm

3. Ensure that your HAProxy configuration has a stats socket line in the global section.

   This enables the Runtime API, which the Data Plane API uses to make some changes without requiring a reload.

   haproxy.cfg
   haproxy
   global
     stats socket /var/run/haproxy.sock mode 660 level admin

   haproxy.cfg
   haproxy
   global
     stats socket /var/run/haproxy.sock mode 660 level admin

4. Add a userlist section to the HAProxy configuration. This sets the authentication username to admin and password to adminpwd:

   haproxy.cfg
   haproxy
   userlist dataplaneapi
     user admin insecure-password adminpwd

   haproxy.cfg
   haproxy
   userlist dataplaneapi
     user admin insecure-password adminpwd

5. Start the Data Plane API:

   nix
   sudo systemctl start dataplaneapi

   nix
   sudo systemctl start dataplaneapi

6. Verify that the API is running properly by calling the info function:

   nix
   curl -X GET --user admin:adminpwd http://localhost:5555/v3/info

   nix
   curl -X GET --user admin:adminpwd http://localhost:5555/v3/info

   output
   json
   {"api":{"build_date":"2024-08-23T15:38:09.000Z","version":"v3.0.3 1491b08a"},"system":{}}

   output
   json
   {"api":{"build_date":"2024-08-23T15:38:09.000Z","version":"v3.0.3 1491b08a"},"system":{}}

Run the API in Docker Jump to heading #

The HAProxy Docker images come with the Data Plane API preinstalled.

1. Create a folder on your workstation named haproxy. Here, you will keep your configuration files.

2. To get a sample Data Plane API configuration file:

   • Download the latest 3.0.x archive from the HAProxy Data Plane API GitHub repository.

     nix
     wget https://github.com/haproxytech/dataplaneapi/releases/download/v3.0.3/dataplaneapi_3.0.3_linux_x86_64.tar.gz

     nix
     wget https://github.com/haproxytech/dataplaneapi/releases/download/v3.0.3/dataplaneapi_3.0.3_linux_x86_64.tar.gz

   • Extract the archive to get the sample configuration file dataplaneapi.yml.dist.

     nix
     tar -zxvf dataplaneapi_3.0.3_linux_x86_64.tar.gz

     nix
     tar -zxvf dataplaneapi_3.0.3_linux_x86_64.tar.gz

   • Rename the file dataplaneapi.yml.dist to dataplaneapi.yml and move it into your haproxy folder.

   • Change the file paths to the HAProxy program and configuration file:

     dataplaneapi.yml
     yaml
     haproxy:
       config_file: /usr/local/etc/haproxy/haproxy.cfg
       haproxy_bin: /usr/local/sbin/haproxy

     dataplaneapi.yml
     yaml
     haproxy:
       config_file: /usr/local/etc/haproxy/haproxy.cfg
       haproxy_bin: /usr/local/sbin/haproxy

   • To send API logs to standard out, change the log_to line to stdout:

     dataplaneapi.yml
     yaml
     log_targets:
     - log_to: stdout

     dataplaneapi.yml
     yaml
     log_targets:
     - log_to: stdout

3. Create an HAProxy configuration file that has:

   • a global section. The stats socket line enables the Runtime API, which the Data Plane API uses to make some changes without requiring a reload.
   • a userlist section that sets the API authentication username and password. In the example below, we set the username to admin and password to adminpwd.

   haproxy.cfg
   haproxy
   global
     stats socket /var/run/haproxy.sock mode 660 level admin
   userlist dataplaneapi
     user admin insecure-password adminpwd

   haproxy.cfg
   haproxy
   global
     stats socket /var/run/haproxy.sock mode 660 level admin
   userlist dataplaneapi
     user admin insecure-password adminpwd

4. Change directory into the haproxy folder. Then run the Docker container, passing the -v flag to map your local haproxy folder to /usr/local/etc/haproxy inside the container:

   nix
   docker run -d --name my-running-haproxy -p 5555:5555/tcp -v  ${PWD}:/usr/local/etc/haproxy:rw haproxytech/haproxy-ubuntu

   nix
   docker run -d --name my-running-haproxy -p 5555:5555/tcp -v  ${PWD}:/usr/local/etc/haproxy:rw haproxytech/haproxy-ubuntu

5. Verify that the API is running properly by calling the info function:

   nix
   curl -X GET --user admin:adminpwd http://localhost:5555/v3/info

   nix
   curl -X GET --user admin:adminpwd http://localhost:5555/v3/info

   output
   json
   {"api":{"build_date":"2024-08-23T15:38:09.000Z","version":"v3.0.3 1491b08a"},"system":{}}

   output
   json
   {"api":{"build_date":"2024-08-23T15:38:09.000Z","version":"v3.0.3 1491b08a"},"system":{}}

Troubleshooting Jump to heading #

• You get the error The configuration file is not declared in the HAPROXY_CFGFILES environment variable, cannot start.

  The value of config_file in your Data Plane API configuration must match the configuration file that HAProxy actually loaded. Try checking the value of the HAPROXY_CFGFILES environment variable by including it in your logs. Set your config_file field to match. For example, /usr/local/etc/haproxy/haproxy.cfg.

• You get a permission denied error.

  If you get an error like this:

  json
  {"code":500,"message":"dial unix /var/run/haproxy.sock: connect: permission denied"}

  json
  {"code":500,"message":"dial unix /var/run/haproxy.sock: connect: permission denied"}

  This means that the user who runs the API does not have access to the HAProxy socket. Check that you added them to the HAProxy group and log out and back in again.

• You receive 400 Bad Request.

  If you receive an error such as 400 Bad Request or Client sent an HTTP request to an HTTPS server, HTTPS may be enabled. Try the curl command again with the -k option and specify https:// in your URL:

  nix
  curl -k -X GET --user admin:adminpwd https://localhost:5555/v3/info

  nix
  curl -k -X GET --user admin:adminpwd https://localhost:5555/v3/info