HAProxy Enterprise Documentation 2.1r1

HAProxy Enterprise

The Data Plane API comes as a system package which you can install with apt or yum. The following is an example of an installation on an Ubuntu 18.04 server.

  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. The Data Plane API requires that you enable Basic authentication, which means that any user invoking its methods must provide valid credentials. Usernames and passwords are stored in the HAProxy Enterprise configuration file inside a userlist section.

    1. Add a userlist section with a username and password to the configuration file /etc/hapee-2.1/hapee-lb.cfg. In the example below, we add a user named dataplaneapi with the password mypassword:

      userlist hapee-dataplaneapi
         user dataplaneapi insecure-password mypassword
    2. 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
    3. Then copy and paste the encrypted password into your configuration file:

      userlist hapee-dataplaneapi
         user dataplaneapi password $5$aVnIFECJ$2QYP64eTTXZ1grSjwwdoQxK/AP8kcOflEO1Q5fc.5aA
    4. Reload HAProxy Enterprise.

  3. The Data Plane API needs access to the HAProxy Runtime API. To do this, update your HAProxy Enterprise configuration file so that it has a stats socket line in the global section.

    1. Add the stats socket directive if not already present:

      global
         stats socket /var/run/hapee-2.1/hapee-lb.sock user hapee-lb group hapee mode 660 level admin expose-fd listeners
    2. If you test the API by running it as your non-root user, you can add your own username to the same group:

      $ sudo usermod -a -G hapee $USER

      If you do this, make sure that you log out and back in again for the permissions to take effect.

  4. Start the Data Plane API service:

    1. Run the following command to replace 1.9 in the service's defaults file with the current version of HAProxy Enterprise:

      $ sudo sed -i 's/1.9/2.1/g' /etc/default/hapee-extras-dataplane-api
    2. Enable and start the service:

      $ sudo systemctl enable hapee-extras-dataplane-api
      $ sudo systemctl start hapee-extras-dataplane-api
  5. Verify that the API is running properly by calling the info function:

    $ curl -X GET --user dataplaneapi:mypassword 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 HAProxy Enterprise group and log out and back in again.

Choose a different IP address and port

By default, the service listens at localhost on port 5555. You can change this by setting the HOST and PORT environment variables in /etc/default/hapee-extras-dataplane-api.

  1. Add HOST and PORT variables to the file:

    SYSD_OPTIONS=...
    SYSV_OPTIONS=...
    
    HOST='0.0.0.0'
    PORT='5556'

    To change the port, you will need to delete the --port flag from the SYSD_OPTIONS and SYSV_OPTIONS lines.

  2. Restart the service:

    $ sudo systemctl daemon-reload
    $ sudo systemctl restart hapee-extras-dataplane-api

Next up

CLI