HAProxy Enterprise Documentation 1.8r2

HAProxy Community

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.2.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. 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 configuration file inside a userlist section.

    • Add a userlist section with a username and password to the configuration file /etc/haproxy/haproxy.cfg. In the example below, we add a user named dataplaneapi with the password mypassword:

      userlist haproxy-dataplaneapi
         user dataplaneapi insecure-password mypassword
    • 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 haproxy-dataplaneapi
         user dataplaneapi password $5$aVnIFECJ$2QYP64eTTXZ1grSjwwdoQxK/AP8kcOflEO1Q5fc.5aA
    • Reload HAProxy.

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

    • Add the stats socket directive if not already present:

      global
         stats socket /var/run/haproxy.sock user haproxy group haproxy mode 660 level admin expose-fd listeners
    • 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 haproxy $USER

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

  6. Start the Data Plane API:

    $ sudo dataplaneapi \
       --host 127.0.0.1 \
       --port 5555 \
       --haproxy-bin /usr/sbin/haproxy \
       --config-file /etc/haproxy/haproxy.cfg  \
       --reload-delay 5 \
       --reload-cmd "service haproxy reload" \
       --restart-cmd "service haproxy restart" \
       --userlist haproxy-dataplaneapi \
       --transaction-dir /tmp/haproxy
  7. 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":"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.

The following configuration starts the Data Plane API when the HAProxy process is started. The no option start-on-reload line avoids restarting the Data Plane API each time that HAProxy reloads.

  1. Add a program section to your HAProxy configuration:

    program api
        command dataplaneapi --host 0.0.0.0 --port 5555 --haproxy-bin /usr/sbin/haproxy --config-file /etc/haproxy/haproxy.cfg --reload-cmd "systemctl reload haproxy" --reload-delay 5 --userlist haproxy-dataplaneapi
        no option start-on-reload
  2. 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). Then when you view the status of HAProxy, 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 --host 0.0.0.0 --port 5555 --haproxy-bin /usr/sbin/haproxy --config-file /etc/haproxy/haproxy.cfg --reload-cmd "kill -SIGUSR2 1" --reload-delay 5 --userlist haproxy-dataplaneapi
        no option start-on-reload

Next up

CLI