Installation
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:
-
Download the latest archive from the HAProxy Data Plane API GitHub repository.
-
Extract the archive with
tar
and set its permissions to executable withchmod
:nixtar -zxvf dataplaneapi_2.8.0_Linux_x86_64.tar.gzchmod +x build/dataplaneapinixtar -zxvf dataplaneapi_2.8.0_Linux_x86_64.tar.gzchmod +x build/dataplaneapi -
Copy the file to
/usr/local/bin/
:nixsudo cp build/dataplaneapi /usr/local/bin/nixsudo cp build/dataplaneapi /usr/local/bin/ -
Ensure that your HAProxy configuration has a
stats socket
line in theglobal
section.This enables the Runtime API, which the Data Plane API uses to make some changes without requiring a reload.
haproxy.cfghaproxyglobalstats socket /run/haproxy/admin.sock mode 660 level adminhaproxy.cfghaproxyglobalstats socket /run/haproxy/admin.sock mode 660 level admin -
Create the Data Plane API configuration file,
/etc/haproxy/dataplaneapi.yml
, and add the following:dataplaneapi.ymlyamldataplaneapi:host: 0.0.0.0port: 5555transaction:transaction_dir: /tmp/haproxyuser:- insecure: truepassword: adminpwdname: adminhaproxy:config_file: /etc/haproxy/haproxy.cfghaproxy_bin: /usr/sbin/haproxyreload:reload_delay: 5reload_cmd: service haproxy reloadrestart_cmd: service haproxy restartdataplaneapi.ymlyamldataplaneapi:host: 0.0.0.0port: 5555transaction:transaction_dir: /tmp/haproxyuser:- insecure: truepassword: adminpwdname: adminhaproxy:config_file: /etc/haproxy/haproxy.cfghaproxy_bin: /usr/sbin/haproxyreload:reload_delay: 5reload_cmd: service haproxy reloadrestart_cmd: service haproxy restart -
Start the Data Plane API:
nixsudo dataplaneapi -f /etc/haproxy/dataplaneapi.ymlnixsudo dataplaneapi -f /etc/haproxy/dataplaneapi.yml -
Verify that the API is running properly by calling the
info
function:nixcurl -X GET --user admin:adminpwd http://localhost:5555/v2/infonixcurl -X GET --user admin:adminpwd http://localhost:5555/v2/infooutputjson{"api":{"build_date":"2023-06-15T09:07:18.000Z","version":"v2.8.0 b77adc7"},"system":{}}outputjson{"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:nixcurl -k -X GET --user admin:adminpwd https://localhost:5555/v2/infonixcurl -k -X GET --user admin:adminpwd https://localhost:5555/v2/info
Run the API with the HAProxy Process Manager Jump to heading
Available since
- HAProxy 2.0
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:
-
Add a
program
section to your HAProxy configuration:haproxy.cfghaproxyglobalmaster-workerprogram apicommand dataplaneapi -f /etc/haproxy/dataplaneapi.ymlno option start-on-reloadhaproxy.cfghaproxyglobalmaster-workerprogram apicommand dataplaneapi -f /etc/haproxy/dataplaneapi.ymlno option start-on-reloadThe
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 yourglobal
section or by adding the-W
command-line argument when starting HAProxy. -
Then when you restart HAProxy and view its status, you’ll see the new program running alongside the HAProxy worker processes.
nixsudo systemctl restart haproxysudo systemctl status haproxynixsudo systemctl restart haproxysudo systemctl status haproxyoutputtexthaproxy.service - HAProxy Load BalancerLoaded: loaded (/lib/systemd/system/haproxy.service; enabled; vendor preset: enabled)Active: active (running) since Tue 2023-07-11 21:54:12 UTC; 7s agoDocs: man:haproxy(1)file:/usr/share/doc/haproxy/configuration.txt.gzMain PID: 12044 (haproxy)Status: "Ready."Tasks: 11 (limit: 1129)Memory: 97.1MCPU: 2.209sCGroup: /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.sockoutputtexthaproxy.service - HAProxy Load BalancerLoaded: loaded (/lib/systemd/system/haproxy.service; enabled; vendor preset: enabled)Active: active (running) since Tue 2023-07-11 21:54:12 UTC; 7s agoDocs: man:haproxy(1)file:/usr/share/doc/haproxy/configuration.txt.gzMain PID: 12044 (haproxy)Status: "Ready."Tasks: 11 (limit: 1129)Memory: 97.1MCPU: 2.209sCGroup: /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
Available since
- HAProxy 2.0
The HAProxy Docker images support running the Data Plane API as a sidecar.
-
Update your
haproxy.cfg
to set theuserlist
andprogram
section for running the API:haproxy.cfghaproxyuserlist haproxy-dataplaneapiuser admin insecure-password adminpwdprogram apicommand /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-dataplaneapino option start-on-reloadhaproxy.cfghaproxyuserlist haproxy-dataplaneapiuser admin insecure-password adminpwdprogram apicommand /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-dataplaneapino option start-on-reloadThen publish port 5555 on the container.
Do you have any suggestions on how we can improve the content of this page?