HAProxy ALOHA Documentation 15.5

Data Plane API

The Data Plane API is a service that runs on HAProxy 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. Mount a partition required for installing additional modules.

  2. Obtain your credentials for accessing HAProxy ALOHA downloads. You can create a new support ticket in the HAProxy Technologies Customer Portal to request your credentials.

  3. Download the management-aloha15.5.x.img disk image from https://www.haproxy.com/download/aloha/15.5/packages/. Enter your credentials to access the folder.

  4. Log in to your HAProxy ALOHA web UI as an administrator.

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

  5. Select the Tools tab, then upload the management-aloha15.5.x.img disk image to the /app/images/ directory through the File Manager.

  6. Select the Setup tab and reboot the virtual appliance by clicking Reboot.

  7. Check in the File Manager that the /app/management directory is populated.

  8. Check that the dataplaneapi service is started in the Services tab.

Update

To update to a newer version of the API, follow these steps:

  1. Obtain your credentials for accessing HAProxy ALOHA downloads. You can create a new support ticket in the HAProxy Technologies Customer Portal to request your credentials.

  2. Download the latest management-aloha15.5.x.img disk image from https://www.haproxy.com/download/aloha/15.5/packages/. Enter your credentials to access the folder.

  3. In the Services tab, stop stop_icon the dataplaneapi service.

  4. Select the Tools tab, then upload the new management-aloha15.5.x.img disk image to the /app/images/ directory through the File Manager.

  5. Reboot the virtual appliance through the Setup tab.

  6. Check that the dataplaneapi service is started in the Services tab.

    You can also verify which version of the API is installed by running the following command from the CLI:

    $ /app/management/usr/sbin/dataplaneapi --version

Reference

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

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

  • OpenAPI specification at https://<HAProxy ALOHA HOSTNAME>:8889/v2/specification (log in with your HAProxy 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 HAProxy 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://<HAProxy 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.

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://<HAProxy 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://<HAProxy 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://<HAProxy 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://<HAProxy 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://<HAProxy 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://<HAProxy 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://<HAProxy 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://<HAProxy 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://<HAProxy 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