HAProxy Enterprise Documentation 2.1r1

HAProxy Enterprise

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

Run the API using the HAProxy Process Manager

You can run the Data Plane API as a child process of HAProxy Enterprise's parent process.

  1. Install the Data Plane API package:

    $ # On Debian/Ubuntu
    $ sudo apt-get install hapee-extras-dataplane-api
    $ # On CentOS/RedHat/Oracle
    $ sudo yum install hapee-extras-dataplane-api
    $ # On SUSE
    $ sudo zypper install hapee-extras-dataplane-api
    $ # On FreeBSD
    $ sudo pkg install hapee-extras-dataplane-api

    This adds the program here: /opt/hapee-extras/sbin/hapee-dataplane-api.

  2. Add a master-worker directive to the global section of your configuration file, , /etc/hapee-2.1/hapee-lb.cfg. This is required to before you can use the program section.

    global
       master-worker
  3. Add a program section to your HAProxy configuration:

    program api
       command /opt/hapee-extras/sbin/hapee-dataplane-api -f /etc/hapee-extras/dataplane-api.hcl
       no option start-on-reload

    A program section starts an external program when HAProxy Enterprise starts. The no option start-on-reload line avoids restarting the Data Plane API each time that the load balancer reloads.

    The Data Plane API's configuration file is at /etc/hapee-extras/dataplane-api.hcl. You can edit the default values found there.

  4. Add a userlist section that sets a username and password to require when calling API functions.

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

    userlist hapee-dataplaneapi
       user admin insecure-password adminpwd

    Optionally, first encrypt the password with the mkpasswd command from the whois package:

    $ sudo apt install -y whois
    $ mkpasswd -m sha-256 mypassword
    
    # encrypted password displayed

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

    userlist hapee-dataplaneapi
       user admin password $5$aVnIFECJ$2QYP64eTTXZ1grSjwwdoQxK/AP8kcOflEO1Q5fc.5aA
  5. 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/hapee-2.1/hapee-lb.sock user hapee-lb group hapee mode 660 level admin expose-fd listeners
  6. Restart HAProxy Enterprise:

    $ sudo systemctl restart hapee-2.1-lb

Run the API as a Systemd service

You can enable the Data Plane API as a Systemd service.

  1. Install the Data Plane API package:

    $ # On Debian/Ubuntu
    $ sudo apt-get install hapee-extras-dataplane-api
    $ # On CentOS/RedHat/Oracle
    $ sudo yum install hapee-extras-dataplane-api
    $ # On SUSE
    $ sudo zypper install hapee-extras-dataplane-api
    $ # On FreeBSD
    $ sudo pkg install hapee-extras-dataplane-api

    This adds the program here: /opt/hapee-extras/sbin/hapee-dataplane-api.

  2. Add a userlist section to your configuration file, /etc/hapee-2.1/hapee-lb.cfg, that sets a username and password to require when calling API functions.

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

    userlist hapee-dataplaneapi
       user admin insecure-password adminpwd

    Optionally, first encrypt the password with the mkpasswd command from the whois package:

    $ sudo apt install -y whois
    $ mkpasswd -m sha-256 mypassword
    
    # encrypted password displayed

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

    userlist hapee-dataplaneapi
       user dataplaneapi password $5$aVnIFECJ$2QYP64eTTXZ1grSjwwdoQxK/AP8kcOflEO1Q5fc.5aA
  3. 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/hapee-2.1/hapee-lb.sock user hapee-lb group hapee mode 660 level admin expose-fd listeners
  4. Enable and start the service:

    $ sudo systemctl enable hapee-extras-dataplane-api
    $ sudo systemctl start hapee-extras-dataplane-api

Choose a different IP address and port

By default, the API listens on all IP addresses at port 5555. You can change this by editing the file /etc/hapee-extras/dataplane-api.hcl.

  1. Change the host and/or port fields in the dataplaneapi block.

    dataplaneapi {
       host = "192.168.50.20"
       port = 5557

    Alternatively, set the $HOST and $PORT environment variables.

  2. Restart the service:

    $ sudo systemctl restart hapee-extras-dataplane-api

Verify that the API works

  1. 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":"2020-11-10T14:37:06.000Z","version":"v2.1.0-ee6 30a03a6.dirty"},"system":{}}

    If you get this error:

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

    This 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.


Next up

CLI