Installation
Install the HAProxy Data Plane API on HAProxy
Version 3.0 contains breaking changes
If you’re installing HAProxy Data Plane API 3.x, know that it changes several conventions that were present in version 2.x, and that upgrading to 3.x will require you to call the API endpoints differently. See the release notes for more details.
This section describes how to install the HAProxy Data Plane API alongside HAProxy.
Run the API in the current terminal session Jump to heading
You can run the API in your current terminal session by following these steps on the HAProxy server. When you are finished with the API, stop it with Ctrl + C
.
-
Download the latest 3.0.x archive from the HAProxy Data Plane API GitHub repository.
nixwget https://github.com/haproxytech/dataplaneapi/releases/download/v3.0.1/dataplaneapi_3.0.1_linux_x86_64.tar.gznixwget https://github.com/haproxytech/dataplaneapi/releases/download/v3.0.1/dataplaneapi_3.0.1_linux_x86_64.tar.gz -
Extract the archive and set the permissions on the
dataplaneapi
program to executable withchmod
:nixtar -zxvf dataplaneapi_3.0.1_linux_x86_64.tar.gzchmod +x dataplaneapinixtar -zxvf dataplaneapi_3.0.1_linux_x86_64.tar.gzchmod +x dataplaneapi -
Copy the
dataplaneapi
program to/usr/local/bin/
:nixsudo cp dataplaneapi /usr/local/bin/nixsudo cp dataplaneapi /usr/local/bin/ -
Copy the Data Plane API configuration file to
/etc/haproxy/dataplaneapi.yml
:nixsudo cp dataplaneapi.yml.dist /etc/haproxy/dataplaneapi.ymlnixsudo cp dataplaneapi.yml.dist /etc/haproxy/dataplaneapi.yml -
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 /var/run/haproxy.sock mode 660 level adminhaproxy.cfghaproxyglobalstats socket /var/run/haproxy.sock mode 660 level admin -
Add a
userlist
section to the HAProxy configuration. This sets the authentication username toadmin
and password toadminpwd
:haproxy.cfghaproxyuserlist dataplaneapiuser admin insecure-password adminpwdhaproxy.cfghaproxyuserlist dataplaneapiuser admin insecure-password adminpwd -
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/v3/infonixcurl -X GET --user admin:adminpwd http://localhost:5555/v3/infooutputjson{"api":{"build_date":"2024-08-23T15:38:09.000Z","version":"v3.0.1 1491b08a"},"system":{}}outputjson{"api":{"build_date":"2024-08-23T15:38:09.000Z","version":"v3.0.1 1491b08a"},"system":{}}
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 requires a section called program
in your HAProxy configuration, which you can use to start the Data Plane API program when HAProxy starts. Follow these steps on the HAProxy server:
-
Download the latest 3.0.x archive from the HAProxy Data Plane API GitHub repository.
nixwget https://github.com/haproxytech/dataplaneapi/releases/download/v3.0.1/dataplaneapi_3.0.1_linux_x86_64.tar.gznixwget https://github.com/haproxytech/dataplaneapi/releases/download/v3.0.1/dataplaneapi_3.0.1_linux_x86_64.tar.gz -
Extract the archive and set the permissions on the
dataplaneapi
program to executable withchmod
:nixtar -zxvf dataplaneapi_3.0.1_linux_x86_64.tar.gzchmod +x dataplaneapinixtar -zxvf dataplaneapi_3.0.1_linux_x86_64.tar.gzchmod +x dataplaneapi -
Copy the
dataplaneapi
program to/usr/local/bin/
:nixsudo cp dataplaneapi /usr/local/bin/nixsudo cp dataplaneapi /usr/local/bin/ -
Copy the Data Plane API configuration file to
/etc/haproxy/dataplaneapi.yml
:nixsudo cp dataplaneapi.yml.dist /etc/haproxy/dataplaneapi.ymlnixsudo cp dataplaneapi.yml.dist /etc/haproxy/dataplaneapi.yml -
Ensure that your HAProxy configuration has:
- a
global
section. Thestats socket
line enables the Runtime API, which the Data Plane API uses to make some changes without requiring a reload. Themaster-worker
andinsecure-fork-wanted
lines are required to use theprogram
section. - a
userlist
section. Theuser
line sets the username and password you’ll use to access the API. In the example below, we set the username toadmin
and password toadminpwd
. - a
program
section. Thecommand
line runs the Data Plane API.
haproxy.cfghaproxyglobalstats socket /var/run/haproxy.sock mode 660 level adminmaster-workerinsecure-fork-wanteduserlist dataplaneapiuser admin insecure-password adminpwdprogram apicommand /usr/local/bin/dataplaneapi -f /etc/haproxy/dataplaneapi.ymlno option start-on-reloadhaproxy.cfghaproxyglobalstats socket /var/run/haproxy.sock mode 660 level adminmaster-workerinsecure-fork-wanteduserlist dataplaneapiuser admin insecure-password adminpwdprogram apicommand /usr/local/bin/dataplaneapi -f /etc/haproxy/dataplaneapi.ymlno option start-on-reload - a
-
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 (/etc/systemd/system/haproxy.service; enabled; vendor preset: enabled)Active: active (running) since Fri 2024-08-30 21:47:18 UTC; 8min agoMain PID: 40359 (haproxy)Status: "Ready."Tasks: 11 (limit: 510)Memory: 99.6MCPU: 2.696sCGroup: /system.slice/haproxy.service├─40359 /usr/local/sbin/haproxy -Ws -f /etc/haproxy/haproxy.cfg -p /run/haproxy.pid -S /run/haproxy-master.sock├─40361 dataplaneapi -f /etc/haproxy/dataplaneapi.yml└─40362 /usr/local/sbin/haproxy -Ws -f /etc/haproxy/haproxy.cfg -p /run/haproxy.pid -S /run/haproxy-master.sockoutputtexthaproxy.service - HAProxy Load BalancerLoaded: loaded (/etc/systemd/system/haproxy.service; enabled; vendor preset: enabled)Active: active (running) since Fri 2024-08-30 21:47:18 UTC; 8min agoMain PID: 40359 (haproxy)Status: "Ready."Tasks: 11 (limit: 510)Memory: 99.6MCPU: 2.696sCGroup: /system.slice/haproxy.service├─40359 /usr/local/sbin/haproxy -Ws -f /etc/haproxy/haproxy.cfg -p /run/haproxy.pid -S /run/haproxy-master.sock├─40361 dataplaneapi -f /etc/haproxy/dataplaneapi.yml└─40362 /usr/local/sbin/haproxy -Ws -f /etc/haproxy/haproxy.cfg -p /run/haproxy.pid -S /run/haproxy-master.sock -
Verify that the API is running properly by calling the
info
function:nixcurl -X GET --user admin:adminpwd http://localhost:5555/v3/infonixcurl -X GET --user admin:adminpwd http://localhost:5555/v3/infooutputjson{"api":{"build_date":"2024-08-23T15:38:09.000Z","version":"v3.0.1 1491b08a"},"system":{}}outputjson{"api":{"build_date":"2024-08-23T15:38:09.000Z","version":"v3.0.1 1491b08a"},"system":{}}
Run the API in Docker Jump to heading
Available since
- HAProxy 2.0
The HAProxy Docker images come with the Data Plane API preinstalled. You can then add a program
section to run it in the background.
-
Create a folder on your workstation named
haproxy
. Here, you will keep your configuration files. -
To get a sample Data Plane API configuration file:
-
Download the latest 3.0.x archive from the HAProxy Data Plane API GitHub repository.
nixwget https://github.com/haproxytech/dataplaneapi/releases/download/v3.0.1/dataplaneapi_3.0.1_linux_x86_64.tar.gznixwget https://github.com/haproxytech/dataplaneapi/releases/download/v3.0.1/dataplaneapi_3.0.1_linux_x86_64.tar.gz -
Extract the archive to get the sample configuration file
dataplaneapi.yml.dist
.nixtar -zxvf dataplaneapi_3.0.1_linux_x86_64.tar.gznixtar -zxvf dataplaneapi_3.0.1_linux_x86_64.tar.gz -
Rename the file
dataplaneapi.yml.dist
todataplaneapi.yml
and move it into yourhaproxy
folder. -
Change the file paths to the HAProxy program and configuration file:
dataplaneapi.ymlyamlhaproxy:config_file: /usr/local/etc/haproxy/haproxy.cfghaproxy_bin: /usr/local/sbin/haproxydataplaneapi.ymlyamlhaproxy:config_file: /usr/local/etc/haproxy/haproxy.cfghaproxy_bin: /usr/local/sbin/haproxy -
To send API logs to standard out, change the
log_to
line tostdout
:dataplaneapi.ymlyamllog_targets:- log_to: stdoutdataplaneapi.ymlyamllog_targets:- log_to: stdout
-
-
Create an HAProxy configuration file that has:
- a
global
section. Thestats socket
line enables the Runtime API, which the Data Plane API uses to make some changes without requiring a reload. Themaster-worker
andinsecure-fork-wanted
lines are required to use theprogram
section. - a
userlist
section that sets the API authentication username and password. In the example below, we set the username toadmin
and password toadminpwd
. - a
program
section to run the Data Plane API. Thecommand
will indicate the path to the Data Plane API program. Use/usr/local/bin/dataplaneapi
for HAProxy Data Plane API version 3.0, or/usr/local/bin/dataplaneapi-v2
for version 2.0.
haproxy.cfghaproxyglobalstats socket /var/run/haproxy.sock mode 660 level adminmaster-workerinsecure-fork-wanteduserlist dataplaneapiuser admin insecure-password adminpwdprogram apicommand /usr/local/bin/dataplaneapi -f /etc/haproxy/dataplaneapi.ymlno option start-on-reloadhaproxy.cfghaproxyglobalstats socket /var/run/haproxy.sock mode 660 level adminmaster-workerinsecure-fork-wanteduserlist dataplaneapiuser admin insecure-password adminpwdprogram apicommand /usr/local/bin/dataplaneapi -f /etc/haproxy/dataplaneapi.ymlno option start-on-reload - a
-
Change directory into the
haproxy
folder. Then run the Docker container, passing the-v
flag to map your localhaproxy
folder to/usr/local/etc/haproxy
inside the container:nixdocker run -d --name my-running-haproxy -p 5555:5555/tcp -v ${PWD}:/usr/local/etc/haproxy:rw haproxytech/haproxy-ubuntunixdocker run -d --name my-running-haproxy -p 5555:5555/tcp -v ${PWD}:/usr/local/etc/haproxy:rw haproxytech/haproxy-ubuntu -
Verify that the API is running properly by calling the
info
function:nixcurl -X GET --user admin:adminpwd http://localhost:5555/v3/infonixcurl -X GET --user admin:adminpwd http://localhost:5555/v3/infooutputjson{"api":{"build_date":"2024-08-23T15:38:09.000Z","version":"v3.0.1 1491b08a"},"system":{}}outputjson{"api":{"build_date":"2024-08-23T15:38:09.000Z","version":"v3.0.1 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 theHAPROXY_CFGFILES
environment variable by including it in your logs. Set yourconfig_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
orClient sent an HTTP request to an HTTPS server
, HTTPS may be enabled. Try thecurl
command again with the-k
option and specifyhttps://
in your URL:nixcurl -k -X GET --user admin:adminpwd https://localhost:5555/v3/infonixcurl -k -X GET --user admin:adminpwd https://localhost:5555/v3/info
Do you have any suggestions on how we can improve the content of this page?