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 using systemd Jump to heading
Running the API as a systemd
service enables you to issue CLI commands to a running haproxy
process.
-
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
. -
Install the package:
nixsudo dpkg -i --force-depends dataplaneapi_3.0.3_linux_amd64.debnixsudo dpkg -i --force-depends dataplaneapi_3.0.3_linux_amd64.debnixsudo rpm -Uvh --nodeps dataplaneapi_3.0.3_linux_amd64.rpmnixsudo rpm -Uvh --nodeps dataplaneapi_3.0.3_linux_amd64.rpm -
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 systemctl start dataplaneapinixsudo systemctl start dataplaneapi -
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.3 1491b08a"},"system":{}}outputjson{"api":{"build_date":"2024-08-23T15:38:09.000Z","version":"v3.0.3 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.
-
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.3/dataplaneapi_3.0.3_linux_x86_64.tar.gznixwget 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
.nixtar -zxvf dataplaneapi_3.0.3_linux_x86_64.tar.gznixtar -zxvf dataplaneapi_3.0.3_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. - a
userlist
section that sets the API authentication username and password. In the example below, we set the username toadmin
and password toadminpwd
.
haproxy.cfghaproxyglobalstats socket /var/run/haproxy.sock mode 660 level adminuserlist dataplaneapiuser admin insecure-password adminpwdhaproxy.cfghaproxyglobalstats socket /var/run/haproxy.sock mode 660 level adminuserlist dataplaneapiuser admin insecure-password adminpwd - 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.3 1491b08a"},"system":{}}outputjson{"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 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
Enable HTTPS Jump to heading
To enable HTTPS for Data Plane API with HAProxy, you must add a tls
section to your Data Plane API configuration file and set the scheme
to https
:
-
Add the following to your Data Plane API configuration file:
dataplaneapi.hclhcldataplaneapi {host = "0.0.0.0"port = 5555scheme = ["https"]...tls {tls_port = 6443tls_certificate: "/etc/haproxy/ssl/certs/server-cert.pem"tls_key: "/etc/haproxy/ssl/certs/server-key.pem"}...}dataplaneapi.hclhcldataplaneapi {host = "0.0.0.0"port = 5555scheme = ["https"]...tls {tls_port = 6443tls_certificate: "/etc/haproxy/ssl/certs/server-cert.pem"tls_key: "/etc/haproxy/ssl/certs/server-key.pem"}...}dataplaneapi.ymlyamldataplaneapi:host: 0.0.0.0port: 5555scheme:- https...tls:tls_port: 6443tls_certificate: /etc/haproxy/ssl/certs/server-cert.pemtls_key: /etc/haproxy/ssl/certs/server-key.pem...dataplaneapi.ymlyamldataplaneapi:host: 0.0.0.0port: 5555scheme:- https...tls:tls_port: 6443tls_certificate: /etc/haproxy/ssl/certs/server-cert.pemtls_key: /etc/haproxy/ssl/certs/server-key.pem...Set the following:
- The
scheme
tohttps
. Note that you can also have an entry forhttp
, but you must specify different ports forport
andtls_port
to enable both HTTP and HTTPS. - The port for TLS connections as
tls_port
. This must be a different port than you specify forport
if you intend to have both HTTP and HTTPS connections active. - The path to the certificate file to use with TLS connections as
tls_certificate
. - The path to the private key to use with TLS connections as
tls_key
.
- The
-
Restart Data Plane API:
nixsudo systemctl restart dataplaneapinixsudo systemctl restart dataplaneapi
You can test the HTTPS connection to the Data Plane API using curl
, providing your username and password that you defined in the userlist
during installation. The following example is for Data Plane API 3.0 (v3
):
nix
curl -k --user <username>:<password> -X GET https://localhost:6443/v3/info
nix
curl -k --user <username>:<password> -X GET https://localhost:6443/v3/info
outputjson
{"api":{"build_date":"2024-08-23T15:38:09.000Z","version":"v3.0.3 1491b08a"},"system":{}}
outputjson
{"api":{"build_date":"2024-08-23T15:38:09.000Z","version":"v3.0.3 1491b08a"},"system":{}}
You can optionally set the following properties in the tls
section:
Option | Description |
---|---|
tls_host |
The IP to listen on for HTTPS. If you don’t specify a value, it’s the same as host . |
tls_listen_limit |
Limits the number of outstanding requests. |
tls_keep_alive |
Sets the TCP keep-alive timeouts on accepted connections. |
tls_read_timeout |
Maximum duration before timing out read operation of the request. |
tls_write_timeout |
Maximum duration before timing out write operation of the response. |
tls_ca |
The certificate authority file to be used when you enable mTLS authentication. When you provide this option, basic authentication with the Data Plane API is disabled. You will need to authenticate using a client certificate and key. |
Enable mTLS Jump to heading
If you need to perform client certificate authentication, also known as mTLS, for connections to the Data Plane API, you can set an additional parameter in the configuration tls_ca
which sets the certificate authority with which to authenticate client certificates. To enable this behavior:
-
Add this line to your Data Plane API configuration which specifies the path to your CA file:
dataplaneapi.hclhcldataplaneapi {host = "0.0.0.0"port = 5555scheme = ["https"]...tls {tls_port = 6443tls_certificate: "/etc/haproxy/ssl/certs/server-cert.pem"tls_key: "/etc/haproxy/ssl/certs/server-key.pem"tls_ca: "/etc/haproxy/ssl/certs/ca-cert.pem"}...}dataplaneapi.hclhcldataplaneapi {host = "0.0.0.0"port = 5555scheme = ["https"]...tls {tls_port = 6443tls_certificate: "/etc/haproxy/ssl/certs/server-cert.pem"tls_key: "/etc/haproxy/ssl/certs/server-key.pem"tls_ca: "/etc/haproxy/ssl/certs/ca-cert.pem"}...}dataplaneapi.ymlyamldataplaneapi:host: 0.0.0.0port: 5555scheme:- https...tls:tls_port: 6443tls_certificate: /etc/haproxy/ssl/certs/server-cert.pemtls_key: /etc/haproxy/ssl/certs/server-key.pemtls_ca: /etc/haproxy/ssl/certs/ca-cert.pem...dataplaneapi.ymlyamldataplaneapi:host: 0.0.0.0port: 5555scheme:- https...tls:tls_port: 6443tls_certificate: /etc/haproxy/ssl/certs/server-cert.pemtls_key: /etc/haproxy/ssl/certs/server-key.pemtls_ca: /etc/haproxy/ssl/certs/ca-cert.pem... -
Restart Data Plane API:
nixsudo systemctl restart dataplaneapinixsudo systemctl restart dataplaneapi
Note that enabling mTLS in this way means that instead of authenticating with the Data Plane API using a username and password, you will use a client certificate and key.
You can test the HTTPS connection to the Data Plane API using curl
, providing your client certificate and key. The following example is for Data Plane API 3.0 (v3
):
nix
curl -k --cert client-cert.pem --key client-key.pem -X GET https://localhost:6443/v3/info
nix
curl -k --cert client-cert.pem --key client-key.pem -X GET https://localhost:6443/v3/info
outputjson
{"api":{"build_date":"2024-08-23T15:38:09.000Z","version":"v3.0.3 1491b08a"},"system":{}}
outputjson
{"api":{"build_date":"2024-08-23T15:38:09.000Z","version":"v3.0.3 1491b08a"},"system":{}}
Do you have any suggestions on how we can improve the content of this page?