Install the HAProxy Data Plane API on HAProxy

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

Run the API in the current terminal session Jump to heading #

To run the API by invoking the program directly:

1. Download the latest archive from the HAProxy Data Plane API GitHub repository.

2. Extract the archive with tar and set its permissions to executable with chmod:

   x86_64

   nix
   tar -zxvf dataplaneapi_2.8.0_Linux_x86_64.tar.gz
   chmod +x build/dataplaneapi

   nix
   tar -zxvf dataplaneapi_2.8.0_Linux_x86_64.tar.gz
   chmod +x build/dataplaneapi

3. Copy the file to /usr/local/bin/:

   nix
   sudo cp build/dataplaneapi /usr/local/bin/

   nix
   sudo cp build/dataplaneapi /usr/local/bin/

4. 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 /run/haproxy/admin.sock mode 660 level admin

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

5. Create the Data Plane API configuration file, /etc/haproxy/dataplaneapi.yml, and add the following:

   dataplaneapi.yml
   yaml
   dataplaneapi:
      host: 0.0.0.0
      port: 5555
      transaction:
        transaction_dir: /tmp/haproxy
      user:
      - insecure: true
        password: adminpwd
        name: admin
   haproxy:
      config_file: /etc/haproxy/haproxy.cfg
      haproxy_bin: /usr/sbin/haproxy
      reload:
         reload_delay: 5
         reload_cmd: service haproxy reload
         restart_cmd: service haproxy restart

   dataplaneapi.yml
   yaml
   dataplaneapi:
      host: 0.0.0.0
      port: 5555
      transaction:
        transaction_dir: /tmp/haproxy
      user:
      - insecure: true
        password: adminpwd
        name: admin
   haproxy:
      config_file: /etc/haproxy/haproxy.cfg
      haproxy_bin: /usr/sbin/haproxy
      reload:
         reload_delay: 5
         reload_cmd: service haproxy reload
         restart_cmd: service haproxy restart

6. Start the Data Plane API:

   nix
   sudo dataplaneapi -f /etc/haproxy/dataplaneapi.yml

   nix
   sudo dataplaneapi -f /etc/haproxy/dataplaneapi.yml

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

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

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

   output
   json
   {"api":{"build_date":"2023-06-15T09:07:18.000Z","version":"v2.8.0 b77adc7"},"system":{}}

   output
   json
   {"api":{"build_date":"2023-06-15T09:07:18.000Z","version":"v2.8.0 b77adc7"},"system":{}}

   Tip

   If you get a permission denied error:

   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.

   Tip

   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/v2/info

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

Run the API with the HAProxy Process Manager Jump to heading #

You can use the HAProxy Process Manager to run the Data Plane API as a background service. The Process Manager adds a new section called program to the HAProxy configuration, which you can use to start external programs when HAProxy starts.

After following the steps in the previous section to install the Data Plane API binary and create a configuration file:

1. Add a program section to your HAProxy configuration:

   haproxy.cfg
   haproxy
   global
     master-worker
   program api
     command dataplaneapi -f /etc/haproxy/dataplaneapi.yml
     no option start-on-reload

   haproxy.cfg
   haproxy
   global
     master-worker
   program api
     command dataplaneapi -f /etc/haproxy/dataplaneapi.yml
     no option start-on-reload

   The no option start-on-reload line avoids restarting the Data Plane API each time that HAProxy reloads.

   Enabling master-worker mode

   For this to work, you must run HAProxy in master-worker mode by adding the master-worker directive to your global section or by adding the -W command-line argument when starting HAProxy.

2. Then when you restart HAProxy and view its status, you’ll see the new program running alongside the HAProxy worker processes.

   nix
   sudo systemctl restart haproxy
   sudo systemctl status haproxy

   nix
   sudo systemctl restart haproxy
   sudo systemctl status haproxy

   output
   text
   haproxy.service - HAProxy Load Balancer
     Loaded: loaded (/lib/systemd/system/haproxy.service; enabled; vendor preset: enabled)
     Active: active (running) since Tue 2023-07-11 21:54:12 UTC; 7s ago
       Docs: man:haproxy(1)
             file:/usr/share/doc/haproxy/configuration.txt.gz
   Main PID: 12044 (haproxy)
     Status: "Ready."
      Tasks: 11 (limit: 1129)
     Memory: 97.1M
        CPU: 2.209s
     CGroup: /system.slice/haproxy.service
             ├─12044 /usr/sbin/haproxy -Ws -f /etc/haproxy/haproxy.cfg -p /run/haproxy.pid -S /run/haproxy-master.sock
             ├─12047 dataplaneapi -f /etc/haproxy/dataplaneapi.yml
             └─12048 /usr/sbin/haproxy -Ws -f /etc/haproxy/haproxy.cfg -p /run/haproxy.pid -S /run/haproxy-master.sock

   output
   text
   haproxy.service - HAProxy Load Balancer
     Loaded: loaded (/lib/systemd/system/haproxy.service; enabled; vendor preset: enabled)
     Active: active (running) since Tue 2023-07-11 21:54:12 UTC; 7s ago
       Docs: man:haproxy(1)
             file:/usr/share/doc/haproxy/configuration.txt.gz
   Main PID: 12044 (haproxy)
     Status: "Ready."
      Tasks: 11 (limit: 1129)
     Memory: 97.1M
        CPU: 2.209s
     CGroup: /system.slice/haproxy.service
             ├─12044 /usr/sbin/haproxy -Ws -f /etc/haproxy/haproxy.cfg -p /run/haproxy.pid -S /run/haproxy-master.sock
             ├─12047 dataplaneapi -f /etc/haproxy/dataplaneapi.yml
             └─12048 /usr/sbin/haproxy -Ws -f /etc/haproxy/haproxy.cfg -p /run/haproxy.pid -S /run/haproxy-master.sock

Run the API in Docker Jump to heading #

The HAProxy Docker images support running the Data Plane API as a sidecar.

• Update your haproxy.cfg to set the userlist and program section for running the API:

  haproxy.cfg
  haproxy
  userlist haproxy-dataplaneapi
    user admin insecure-password adminpwd
  program api
    command /usr/bin/dataplaneapi --host 0.0.0.0 --port 5555 --haproxy-bin /usr/sbin/haproxy --config-file /usr/local/etc/haproxy/haproxy.cfg --reload-cmd "kill -SIGUSR2 1" --reload-delay 5 --restart-cmd "kill -SIGUSR2 1" --userlist haproxy-dataplaneapi
    no option start-on-reload

  haproxy.cfg
  haproxy
  userlist haproxy-dataplaneapi
    user admin insecure-password adminpwd
  program api
    command /usr/bin/dataplaneapi --host 0.0.0.0 --port 5555 --haproxy-bin /usr/sbin/haproxy --config-file /usr/local/etc/haproxy/haproxy.cfg --reload-cmd "kill -SIGUSR2 1" --reload-delay 5 --restart-cmd "kill -SIGUSR2 1" --userlist haproxy-dataplaneapi
    no option start-on-reload

  Then publish port 5555 on the container.