HAProxy Enterprise Documentation 2.7r1

Install the HAProxy Data Plane API

If you are using the community version of HAProxy, follow these steps to install the Data Plane API.

  1. Download the Data Plane API binary from the GitHub repository.

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

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

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

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

  4. Be sure that your 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.

    global
   stats socket /var/run/haproxy.sock user haproxy group haproxy mode 660 level admin expose-fd listeners

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

    dataplaneapi {
  host = "0.0.0.0"
  port = 5555

  user "admin" {
    insecure = true
    password = "adminpwd"
  }

  transaction {
    transaction_dir = "/tmp/haproxy"
  }
}

haproxy {
  config_file = "/etc/haproxy/haproxy.cfg"
  haproxy_bin = "/usr/sbin/haproxy"

  reload {
    reload_cmd  = "service haproxy reload"
    restart_cmd = "service haproxy restart"
    reload_delay = "5"
  }
}

  6. Start the Data Plane API:

    $ sudo dataplaneapi -f /etc/haproxy/dataplaneapi.hcl

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

    $ curl -X GET --user admin:adminpwd http://localhost:5555/v2/info
    {"api":{"build_date":"0001-01-01T00:00:00.000Z","version":"v2.2.0 68bd22b"},"system":{}}

    If you get this error:

    {"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.

Run the API with the HAProxy Process Manager

When using HAProxy 2.0 or later, you can use the HAProxy Process Manager to start the Data Plane API. The Process Manager adds a new section called program to the HAProxy configuration, which you can use to start external programs when HAProxy starts.

  1. Add a program section to your HAProxy configuration:

    global
    master-worker

program api
    command dataplaneapi -f /etc/haproxy/dataplaneapi.hcl
    no option start-on-reload

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

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

    $ sudo systemctl restart haproxy
$ sudo systemctl status haproxy

Main PID: 1274 (haproxy)
    Tasks: 6
Memory: 5.5M
    CPU: 2.838s
CGroup: /system.slice/haproxy.service
    1274 /usr/sbin/haproxy -Ws -f /etc/haproxy/haproxy.cfg -p /run/haproxy.pid -sf 2768 -x /run/haproxy/admin.sock
    2768 /usr/sbin/haproxy -Ws -f /etc/haproxy/haproxy.cfg -p /run/haproxy.pid -sf 2662 -x /run/haproxy/admin.sock
    2830 /usr/local/bin/dataplane-api --host 0.0.0.0 --port 5555 -b /usr/local/sbin/haproxy -c /etc/haproxy/haproxy.cfg -d 5 -r systemctl reload haproxy -u controller
    2831 /usr/sbin/haproxy -Ws -f /etc/haproxy/haproxy.cfg -p /run/haproxy.pid -sf 2768 -x /run/haproxy/admin.sock

  3. If HAProxy runs inside a Docker container in master-worker mode (which is the default), you can use the kill -SIGUSR2 [PID] command for the --reload-cmd argument, where PID is always 1, to reload only the HAProxy worker processes without terminating the container's main process.

    program api
   command /etc/haproxy/dataplaneapi -f /etc/haproxy/dataplaneapi.hcl --reload-cmd "kill -SIGUSR2 1"
   no option start-on-reload

Next up

Install the HAProxy Enterprise Data Plane API