HAProxy Enterprise Documentation 13.0

Data Plane API

The Data Plane API is a service that runs on the ALOHA and lets you configure the load balancer using HTTP RESTful commands. This feature benefits a number of use cases that are suited for a dynamically-generated configuration.

Enable the Data Plane API

By default, the Data Plane API is deactivated.

  1. Download the management-aloha13.0.x.img disk image from https://www.haproxy.com/download/aloha/13.0/packages/.

  2. Log in to your ALOHA WUI as an administrator.

    For example: http://<ALOHA HOSTNAME>:4444/.

    https://cdn.haproxy.com/documentation/aloha/latest/assets/aloha-wui-c7da4f5b31a2c882b364b57515e932bb7ab0825be1492468083e9c259821b221.png
  3. Select the Tools tab, then copy the management-aloha13.0.x.img disk image to the /app/images/ directory through the File Manager.

    https://cdn.haproxy.com/documentation/aloha/latest/assets/aloha-file-manager-data-plane-api-adc847ad3e6e079478094fa29d40dbad398e39ed631beb8efdba3cb8fa9d2d67.png
  4. Reboot the virtual appliance through the Setup tab.

    https://cdn.haproxy.com/documentation/aloha/latest/assets/aloha-wui-config-reboot-b13f0534f5f16b5b5dde012c4e98be72668d4ff757fde6bad01e573cb8a1a5ca.png
  5. Check in the File Manager that the /app/management directory is populated.

Reference

With the API running, open a browser to access documentation resources:

  • Reference documentation at https://<ALOHA HOSTNAME>:8889/v2/docs

  • OpenAPI specification at https://<ALOHA HOSTNAME>:8889/v2/specification (log in with your ALOHA credentials)

Usage

Use the curl command to test calling various methods from your workstation. If you're using the untrusted TLS certificate that ships with ALOHA, add the -k flag to the curl command to ignore untrusted certificate errors.

GET requests

Use a GET request to fetch information about the current configuration. For example, to list the servers defined in the backend named webfarm, call the /services/haproxy/configuration/servers endpoint like this:

$ curl -k -X GET --user admin:admin "https://<ALOHA HOSTNAME>:8889/v2/services/haproxy/configuration/servers?backend=webfarm"

{
   "_version":2,
   "data":[
      {
         "address":"192.168.1.21",
         "check":"enabled",
         "cookie":"websrv1",
         "maxconn":1000,
         "name":"websrv1",
         "port":80,
         "proxy-v2-options":null,
         "weight":10
      },
      {
         "address":"192.168.1.22",
         "check":"enabled",
         "cookie":"websrv2",
         "maxconn":1000,
         "name":"websrv2",
         "port":80,
         "proxy-v2-options":null,
         "weight":10
      }
   ]
}

This returns a JSON document with two top-level keys:

  • _version keeps track of the current state of the configuration. It increments whenever you write data via a POST, PUT or DELETE request. It ensures that changes to the file don't conflict when multiple people are using the API simultaneously.

  • data contains the result of the command, which in this case is an array of objects describing each server.

Tip

It's a good idea to enclose the URL within quotes so that the shell does not interpret any URL parameter prefixed with an ampersand as a request to run the command in the background.

POST requests

Use a POST request to add new directives to the configuration. Below, we call the /services/haproxy/configuration/servers endpoint to add a new server to an existing backend. We set the backend URL parameter to the name of the backend we want to update and the version URL parameter to the current version number.

$ curl -k -X POST \
   --user admin:admin \
   -H "Content-Type: application/json" \
   -d '{"name": "websrv3", "address": "192.168.1.23", "port": 80, "check": "enabled", "maxconn": 30, "weight": 10}' \
   "https://<ALOHA HOSTNAME>:8889/v2/services/haproxy/configuration/servers?backend=webfarm&version=2"

{
   "address":"192.168.1.23",
   "check":"enabled",
   "maxconn":30,
   "name":"websrv3",
   "port":80,
   "proxy-v2-options":null,
   "weight":10
}

When you write data with a POST request, you must include the version URL parameter. If it does not match the current version tracked by the API, you get a version mismatch error.

In the next section, you will learn how to execute several commands as at once by using a transaction.

Transactions

In the example below, we invoke the /services/haproxy/configuration/frontends endpoint to add a new frontend. For demonstration purposes, this request results in an error because we are trying to create a frontend that references a backend section that doesn't exist yet:

$ curl -k -X POST --user admin:admin \
   -H "Content-Type: application/json" \
   -d '{"name": "test_frontend", "default_backend": "be_web", "mode": "http", "maxconn": 2000}' \
   "https://<ALOHA HOSTNAME>:8889/v2/services/haproxy/configuration/frontends?version=1"

{
   "code":400,
   "message":"14: err transactionId=abe2691f-59bd-40a7-80ce-5b2e214431ca
      msg=Proxy 'test_frontend': unable to find required default_backend: 'be_web'.
      msg=Fatal errors found in configuration."
}

The solution is to create the backend first. Although you could run each command separately, doing so means your configuration is incomplete after each step until you reach the end.

Create a transaction that stores the commands and then apply them all at once.

Batch commands inside a transaction

In the following example, we batch several commands using a transaction.

  1. Initialize a transaction by making a POST request to the /services/haproxy/transactions endpoint:

    $ curl -X POST --user admin:admin \
       -H "Content-Type: application/json" \
       https://<ALOHA HOSTNAME>:8889/v2/services/haproxy/transactions?version=1
    
    {
       "_version":1,
       "id":"b9a0ecd7-b8ae-4ef8-8865-0cd5e38396cd",
       "status":"in_progress"
    }

    To view all active transactions, make a GET request to the /services/haproxy/transactions endpoint:

    $ curl -X GET --user admin:admin \
       -H "Content-Type: application/json" \
       "https://<ALOHA HOSTNAME>:8889/v2/services/haproxy/transactions"
    
    [
       {
          "_version":1,
          "id":"b9a0ecd7-b8ae-4ef8-8865-0cd5e38396cd",
          "status":"in_progress"
       }
    ]
  2. For each command that you want to include in the transaction, add the transaction's id value as the transaction_id URL parameter.

    You do not need to include a version URL parameter. Below, we create a new backend by making a POST request to the /services/haproxy/configuration/backends endpoint:

    $ curl -X POST --user admin:admin \
       -H "Content-Type: application/json" \
       -d '{"name": "test_backend", "mode":"http", "balance": {"algorithm":"roundrobin"}, "httpchk": {"method": "HEAD", "uri": "/check", "version": "HTTP/1.1"}}' \
       "https://<ALOHA HOSTNAME>:8889/v2/services/haproxy/configuration/backends?transaction_id=b9a0ecd7-b8ae-4ef8-8865-0cd5e38396cd"
    
    {
       "balance":
          { "algorithm":"roundrobin" },
          "mode":"http",
          "name":"test_backend"
    }
  3. Add a server to the backend by making a POST request to the /services/haproxy/configuration/servers endpoint.

    Set the backend URL parameter to the name of the backend you just created:

    $ curl -X POST --user admin:admin \
       -H "Content-Type: application/json" \
       -d '{"name": "server1", "address": "127.0.0.1", "port": 8080, "check": "enabled", "maxconn": 30, "weight": 100}' \
       "https://<ALOHA HOSTNAME>:8889/v2/services/haproxy/configuration/servers?backend=test_backend&transaction_id=b9a0ecd7-b8ae-4ef8-8865-0cd5e38396cd"
    
    {
       "address":"127.0.0.1",
       "check":"enabled",
       "maxconn":30,
       "name":"server1",
       "port":8080,
       "proxy-v2-options":null,
       "weight":100
    }
  4. Add a frontend by making a POST request to the /services/haproxy/configuration/frontends endpoint:

    $ curl -X POST --user admin:admin \
       -H "Content-Type: application/json" \
       -d '{"name": "test_frontend", "mode": "http", "default_backend": "test_backend", "maxconn": 2000}' \
       "https://<ALOHA HOSTNAME>:8889/v2/services/haproxy/configuration/frontends?transaction_id=b9a0ecd7-b8ae-4ef8-8865-0cd5e38396cd"
    
    {
       "default_backend":"test_backend",
       "maxconn":2000,
       "mode":"http",
       "name":"test_frontend"
    }
  5. Add a bind line to the frontend by making a POST request to the /services/haproxy/configuration/binds endpoint:

      $ curl -X POST --user admin:admin \
        -H "Content-Type: application/json" \
        -d '{"name": "http", "address": "*", "port": 80}' \
        "https://<ALOHA HOSTNAME>:8889/v2/services/haproxy/configuration/binds?frontend=test_frontend&transaction_id=b9a0ecd7-b8ae-4ef8-8865-0cd5e38396cd"
    
    {
       "address":"*",
       "name":"http",
       "port":80
    }
  6. Now that all desired commands have been called, complete the transaction by making a PUT request to the /services/haproxy/transactions endpoint:

    $ curl -X PUT --user admin:admin \
       -H "Content-Type: application/json" \
       "https://<ALOHA HOSTNAME>:8889/v2/services/haproxy/transactions/b9a0ecd7-b8ae-4ef8-8865-0cd5e38396cd"
    
    {
       "_version":1,
       "id":"b9a0ecd7-b8ae-4ef8-8865-0cd5e38396cd",
       "status":"success"
    }

Configure the service

You can change the default settings of the Data Plane API by editing the file /app/management/var/lib/dataplaneapi/dataplaneapi.yaml and then restarting the dataplaneapi service on the Services tab.


Next up

Troubleshooting