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:

  1. Download the latest archive from the HAProxy Data Plane API GitHub repository.

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

    bash
    tar -zxvf dataplaneapi_2.8.0_Linux_x86_64.tar.gz
    chmod +x build/dataplaneapi
    bash
    tar -zxvf dataplaneapi_2.8.0_Linux_x86_64.tar.gz
    chmod +x build/dataplaneapi
  3. Copy the file to /usr/local/bin/:

    bash
    sudo cp build/dataplaneapi /usr/local/bin/
    bash
    sudo cp build/dataplaneapi /usr/local/bin/
  4. Ensure that your HAProxy 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.

    haproxy.cfg
    haproxy
    global
    stats socket /run/haproxy/admin.sock mode 660 level admin
    haproxy.cfg
    haproxy
    global
    stats socket /run/haproxy/admin.sock mode 660 level admin
  5. Create the Data Plane API configuration file, /etc/haproxy/dataplaneapi.yml, and add the following:

    dataplaneapi.yml
    yaml
    dataplaneapi:
    host: 0.0.0.0
    port: 5555
    transaction:
    transaction_dir: /tmp/haproxy
    user:
    - insecure: true
    password: adminpwd
    name: admin
    haproxy:
    config_file: /etc/haproxy/haproxy.cfg
    haproxy_bin: /usr/sbin/haproxy
    reload:
    reload_delay: 5
    reload_cmd: service haproxy reload
    restart_cmd: service haproxy restart
    dataplaneapi.yml
    yaml
    dataplaneapi:
    host: 0.0.0.0
    port: 5555
    transaction:
    transaction_dir: /tmp/haproxy
    user:
    - insecure: true
    password: adminpwd
    name: admin
    haproxy:
    config_file: /etc/haproxy/haproxy.cfg
    haproxy_bin: /usr/sbin/haproxy
    reload:
    reload_delay: 5
    reload_cmd: service haproxy reload
    restart_cmd: service haproxy restart
  6. Start the Data Plane API:

    bash
    sudo dataplaneapi -f /etc/haproxy/dataplaneapi.yml
    bash
    sudo dataplaneapi -f /etc/haproxy/dataplaneapi.yml
  7. Verify that the API is running properly by calling the info function:

    bash
    curl -X GET --user admin:adminpwd http://localhost:5555/v2/info
    bash
    curl -X GET --user admin:adminpwd http://localhost:5555/v2/info
    output
    json
    {"api":{"build_date":"2023-06-15T09:07:18.000Z","version":"v2.8.0 b77adc7"},"system":{}}
    output
    json
    {"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:

    bash
    curl -k -X GET --user admin:adminpwd https://localhost:5555/v2/info
    bash
    curl -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:

  1. Add a program section to your HAProxy configuration:

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

    The 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 your global section or by adding the -W command-line argument when starting HAProxy.

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

    bash
    sudo systemctl restart haproxy
    sudo systemctl status haproxy
    bash
    sudo systemctl restart haproxy
    sudo systemctl status haproxy
    output
    bash
    haproxy.service - HAProxy Load Balancer
    Loaded: loaded (/lib/systemd/system/haproxy.service; enabled; vendor preset: enabled)
    Active: active (running) since Tue 2023-07-11 21:54:12 UTC; 7s ago
    Docs: man:haproxy(1)
    file:/usr/share/doc/haproxy/configuration.txt.gz
    Main PID: 12044 (haproxy)
    Status: "Ready."
    Tasks: 11 (limit: 1129)
    Memory: 97.1M
    CPU: 2.209s
    CGroup: /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
    output
    bash
    haproxy.service - HAProxy Load Balancer
    Loaded: loaded (/lib/systemd/system/haproxy.service; enabled; vendor preset: enabled)
    Active: active (running) since Tue 2023-07-11 21:54:12 UTC; 7s ago
    Docs: man:haproxy(1)
    file:/usr/share/doc/haproxy/configuration.txt.gz
    Main PID: 12044 (haproxy)
    Status: "Ready."
    Tasks: 11 (limit: 1129)
    Memory: 97.1M
    CPU: 2.209s
    CGroup: /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 the userlist and program section for running the API:

    haproxy.cfg
    haproxy
    userlist haproxy-dataplaneapi
    user admin insecure-password adminpwd
    program api
    command /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-dataplaneapi
    no option start-on-reload
    haproxy.cfg
    haproxy
    userlist haproxy-dataplaneapi
    user admin insecure-password adminpwd
    program api
    command /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-dataplaneapi
    no option start-on-reload

    Then publish port 5555 on the container.

If this page was useful, please, Leave the feedback.