Installation

Install the HAProxy Data Plane API on HAProxy Enterprise

This section describes how to install the HAProxy Data Plane API on HAProxy Enterprise.

Available packages Jump to heading

The following packages are available:

Version Package name
2.8 hapee-extras-dataplaneapi28
2.7 hapee-extras-dataplaneapi27
2.6 hapee-extras-dataplaneapi26
2.5 hapee-extras-dataplaneapi25
2.4 hapee-extras-dataplaneapi24
2.3 hapee-extras-dataplaneapi

Install the API as a service Jump to heading

To enable the Data Plane API as a Systemd service:

  1. Install the Data Plane API x86-64 package.

    bash
    sudo apt-get install hapee-extras-dataplaneapi28
    bash
    sudo apt-get install hapee-extras-dataplaneapi28
    bash
    sudo yum install hapee-extras-dataplaneapi28
    bash
    sudo yum install hapee-extras-dataplaneapi28
    bash
    sudo zypper install hapee-extras-dataplaneapi28
    bash
    sudo zypper install hapee-extras-dataplaneapi28
    bash
    sudo pkg install hapee-extras-dataplaneapi28
    bash
    sudo pkg install hapee-extras-dataplaneapi28
  2. Ensure that your HAProxy Enterprise configuration has a stats socket line in the global section.

    This enables the HAProxy Runtime API. The Data Plane API integrates with the Runtime API to make some configuration changes without needing to reload the load balancer.

    hapee-lb.cfg
    haproxy
    global
    stats socket /var/run/hapee-2.8/hapee-lb.sock user hapee-lb group hapee mode 660 level admin expose-fd listeners
    hapee-lb.cfg
    haproxy
    global
    stats socket /var/run/hapee-2.8/hapee-lb.sock user hapee-lb group hapee mode 660 level admin expose-fd listeners
  3. Configure the Basic authentication credentials you’ll use to access the API. You can either:

    Option 1: Set the username and password in the Data Plane API configuration file

    Add a user block to the Data Plane API configuration file and set the password via its insecure and password fields.

    HAProxy Enterprise version 2.7r1 and earlier use the configuration file /etc/hapee-extras/dataplaneapi.hcl.

    dataplaneapi.hcl
    hcl
    dataplaneapi {
    user "admin" {
    insecure = true
    password = "adminpwd"
    }
    }
    dataplaneapi.hcl
    hcl
    dataplaneapi {
    user "admin" {
    insecure = true
    password = "adminpwd"
    }
    }

    HAProxy Enterprise versions beyond 2.7r1 will use the configuration file /etc/hapee-extras/dataplaneapi.yml.

    dataplaneapi.yml
    yaml
    dataplaneapi:
    user:
    - name: admin
    insecure: true
    password: adminpwd
    dataplaneapi.yml
    yaml
    dataplaneapi:
    user:
    - name: admin
    insecure: true
    password: adminpwd
    Option 2: Set the username and password in the HAProxy Enterprise configuration file

    Add a userlist section named hapee-dataplaneapi to your configuration file, /etc/hapee-<VERSION>/hapee-lb.cfg, and set a username and password via the user directive.

    In the example below, we add a user named admin with the password adminpwd:

    hapee-lb.cfg
    haproxy
    userlist hapee-dataplaneapi
    user admin insecure-password adminpwd
    hapee-lb.cfg
    haproxy
    userlist hapee-dataplaneapi
    user admin insecure-password adminpwd

    Optional: If you prefer to encrypt the password first, use the mkpasswd command to do so. If mkpasswd is not present on your OS, it can be installed by downloading the whois package on most Linux distributions; on RedHat you may have to explicitly install it via sudo yum install mkpasswd.

    bash
    mkpasswd -m sha-256 adminpwd
    bash
    mkpasswd -m sha-256 adminpwd

    Then copy and paste the encrypted password into your configuration file:

    hapee-lb.cfg
    haproxy
    userlist hapee-dataplaneapi
    user admin password $5$aVnIFECJ$2QYP64eTTXZ1grSjwwdoQxK/AP8kcOflEO1Q5fc.5aA
    hapee-lb.cfg
    haproxy
    userlist hapee-dataplaneapi
    user admin password $5$aVnIFECJ$2QYP64eTTXZ1grSjwwdoQxK/AP8kcOflEO1Q5fc.5aA

    If you find that your credentials are not working, check the other configuration file. There may be a competing username and password there!

  4. Enable and restart the service:

    bash
    sudo systemctl enable hapee-extras-dataplaneapi
    sudo systemctl restart hapee-extras-dataplaneapi
    bash
    sudo systemctl enable hapee-extras-dataplaneapi
    sudo systemctl restart hapee-extras-dataplaneapi

Change the listening IP address and port Jump to heading

By default, the Data Plane API listens on all IP addresses at TCP port 5555. You can change the listening IP address and port by editing the Data Plane API configuration file.

  • Data Plane API version 2.7 and earlier use the configuration file /etc/hapee-extras/dataplaneapi.hcl.
  • Data Plane API version 2.8 and beyond will use the configuration file /etc/hapee-extras/dataplaneapi.yml.
  1. Change the host and/or port fields in the dataplaneapi block.

    This example changes the host to 192.168.50.20 and the port from its default of 5555 to 5557.

    dataplaneapi.hcl
    hcl
    dataplaneapi {
    host = "192.168.50.20"
    port = 5557
    dataplaneapi.hcl
    hcl
    dataplaneapi {
    host = "192.168.50.20"
    port = 5557
    dataplaneapi.yml
    yaml
    dataplaneapi:
    host: 192.168.50.20
    port: 5557
    dataplaneapi.yml
    yaml
    dataplaneapi:
    host: 192.168.50.20
    port: 5557

    Alternatively, set the HOST and PORT environment variables. Because the API runs as a Systemd service, you would add those variables to the file /etc/default/hapee-extras-dataplaneapi, which the service reads on startup.

    hapee-extras-dataplaneapi
    ini
    HOST=192.168.50.20
    PORT=5557
    hapee-extras-dataplaneapi
    ini
    HOST=192.168.50.20
    PORT=5557
  2. Restart the service:

    bash
    sudo systemctl restart hapee-extras-dataplaneapi
    bash
    sudo systemctl restart hapee-extras-dataplaneapi

Verify that the API works Jump to heading

To verify that the API is running properly:

  1. Try calling the info API endpoint:

    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-02-17T14:41:27.000Z","version":"v2.7.2-ee1 191e89da"},"system":{}}
    output
    json
    {"api":{"build_date":"2023-02-17T14:41:27.000Z","version":"v2.7.2-ee1 191e89da"},"system":{}}

    Tip

    If you get a permission denied error:

    output
    json
    {"code":500,"message":"dial unix /var/run/hapee-2.8/hapee-lb.sock: connect: permission denied"}
    output
    json
    {"code":500,"message":"dial unix /var/run/hapee-2.8/hapee-lb.sock: connect: permission denied"}

    This often means that the user who runs the API does not have access to the Runtime API socket. Check that you added them to the system group hapee, log out and back in again, then try it 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

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