Quickstart HAProxy Community Edition dataplaneAPI

This guide was written after starting up a brand new Ubuntu Server on 22.04 and details the steps taken to quickly get the dataplaneapi up and running.

sudo apt-get update
sudo apt-get install haproxy

Run this to see what version is installed

haproxy -v 

For the sake of this discussion I have HAProxy 2.4.22

Running uname -a or uname -m told me I have x86_64 - That is amd64 architecture

Pick the package that you need from this page:

Note: API just needs to be a newer version than your haproxy version long as you are on HAProxy 1.9 and above.

I’m using this one: dataplaneapi_2.8.3_linux_amd64.deb

Right click on the name and click copy link
https://github.com/haproxytech/dataplaneapi/releases/download/v2.8.3/dataplaneapi_2.8.3_linux_amd64.deb

Curl and download the file into your home directory:

cd ~
curl -JLO https://github.com/haproxytech/dataplaneapi/releases/download/v2.8.3/dataplaneapi_2.8.3_linux_amd64.deb

Install it:

sudo dpkg -i dataplaneapi_2.8.3_linux_amd64.deb

I can see that the dataplane api is now installed:

which dataplaneapi

Returns:

/usr/sbin/dataplaneapi

Make sure that the global configuration has the socket configured:

grep "global\|defaults\|stats socket" /etc/haproxy/haproxy.cfg

It should return this or something similar. If “defaults” shows before the stats line then you need to
make sure you move the stats line under the global section

grep "global\|defaults\|stats socket" /etc/haproxy/haproxy.cfg

Returns:

global
        stats socket /run/haproxy/admin.sock mode 660 level admin expose-fd listeners
defaults
        log     global

Create the /etc/haproxy/dataplaneapi.yml file

sudo vi /etc/haproxy/dataplaneapi.yml

Paste the configuration from this page on step 5 - change the password as desired:

If you run this command to start it up it merely runs the API and starts the socket.
It will appear to hang but that’s just because it’s listening. You can open another ssh session to test it.

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

Testing the api:
With the above command running run this:

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

Result should be similar to this:

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

If it’s not then see the green “Tip” sections for help on this page:

Let’s make it load on startup

sudo vi /etc/haproxy/haproxy.cfg

Add these items in (note: the word ‘global’ should already be present, don’t duplicate it):

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

Restart haproxy:

sudo systemctl restart haproxy

This is my current frontend and backend configuration:

frontend frontend1
        bind *:80
        mode http
        option httplog
        log global

        default_backend    be_app

backend be_app
        mode http
        option httpchk HEAD /
        log global
        server app1        172.16.1.32:80 cookie a1 check

If I query for the frontend this way:

curl -X GET   --user admin:adminpwd   "http://127.0.0.1:5555/v2/services/haproxy/configuration/frontends"

The response looks like this:

{"_version":2,"data":[{"default_backend":"be_app","from":"unnamed_defaults_1","httplog":true,"mode":"http","name":"frontend1"}]}

Personally that’s hard to read so I want to install jq and pipe the command to that so it reads like this:

sudo apt-get install jq

Now send it:

curl -X GET   --user admin:adminpwd http://127.0.0.1:5555/v2/services/haproxy/configuration/frontends" | jq

Response is this:

  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   129  100   129    0     0   262k      0 --:--:-- --:--:-- --:--:--  125k
{
  "_version": 2,
  "data": [
    {
      "default_backend": "be_app",
      "from": "unnamed_defaults_1",
      "httplog": true,
      "mode": "http",
      "name": "frontend1"
    }
  ]
}	
1 Like

Amazing guide @randomguy
No wonder I was previously unable to make it work on my own, it’s quite involved!

{
   "_version": 4,
   "data": [
      {
         "default_backend": "be_app",
         "from": "RandomGuyRocks",
         "httplog": true,
         "mode": "http",
         "name": "Glorious"
      }
   ]
}

For any future readers there’s some good examples on using it here:

Something to watch for is notice that a frontend configuration and a bind configuration are two different things so make sure you create both as needed.