HAProxy Enterprise Documentation 2.8r1

Usage

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

  • Reference documentation at http://<HAPROXY ENTERPRISE HOST>:5555/v2/docs

  • OpenAPI specification at http://<HAPROXY ENTERPRISE HOST>:5555/v2/specification (log in with your userlist credentials)

Use the curl command to test calling various methods from your workstation.

GET requests

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

$ curl -X GET --user admin:adminpwd "http://<HAPROXY ENTERPRISE HOST>:5555/v2/services/haproxy/configuration/servers?backend=webservers"

{
   "_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 -X POST \
   --user admin:adminpwd \
   -H "Content-Type: application/json" \
   -d '{"name": "websrv3", "address": "192.168.1.23", "port": 80, "check": "enabled", "maxconn": 30, "weight": 10}' \
   "http://<HAPROXY ENTERPRISE HOST>:5555/v2/services/haproxy/configuration/servers?backend=webservers&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 -X POST --user admin:adminpwd \
   -H "Content-Type: application/json" \
   -d '{"name": "test_frontend", "default_backend": "be_web", "mode": "http", "maxconn": 2000}' \
   "http://<HAPROXY ENTERPRISE HOST>:5555/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:adminpwd \
   -H "Content-Type: application/json" \
   http://<HAPROXY ENTERPRISE HOST>:5555/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:adminpwd \
   -H "Content-Type: application/json" \
   "http://<HAPROXY ENTERPRISE HOST>:5555/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:adminpwd \
   -H "Content-Type: application/json" \
   -d '{"name": "test_backend", "mode":"http", "balance": {"algorithm":"roundrobin"}, "httpchk": {"method": "HEAD", "uri": "/check", "version": "HTTP/1.1"}}' \
   "http://<HAPROXY ENTERPRISE HOST>:5555/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:adminpwd \
   -H "Content-Type: application/json" \
   -d '{"name": "server1", "address": "127.0.0.1", "port": 8080, "check": "enabled", "maxconn": 30, "weight": 100}' \
   "http://<HAPROXY ENTERPRISE HOST>:5555/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:adminpwd \
   -H "Content-Type: application/json" \
   -d '{"name": "test_frontend", "mode": "http", "default_backend": "test_backend", "maxconn": 2000}' \
   "http://<HAPROXY ENTERPRISE HOST>:5555/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:adminpwd \
    -H "Content-Type: application/json" \
    -d '{"name": "http", "address": "*", "port": 80}' \
    "http://<HAPROXY ENTERPRISE HOST>:5555/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:adminpwd \
   -H "Content-Type: application/json" \
   "http://<HAPROXY ENTERPRISE HOST>:5555/v2/services/haproxy/transactions/b9a0ecd7-b8ae-4ef8-8865-0cd5e38396cd"

{
   "_version":1,
   "id":"b9a0ecd7-b8ae-4ef8-8865-0cd5e38396cd",
   "status":"success"
}

Monitor Configuration Reloads

The Data Plane API is started with the --reload-delay or -d flag to set the time interval between reloads. For example, if you set the delay to be five seconds, then every five seconds the program checks whether there have been any changes that require a reload of HAProxy. If none are found, the API waits another five seconds and checks again. All changes that happen during the interval between checks wait for the next check before they are applied. In other words, a command does not trigger a reload. Reloads happen automatically at regular intervals as needed.

Use the /services/haproxy/reloads endpoint to get a list of in-progress and failed reloads. You can use this to verify that the configuration updated successfully.

It is possible to reload the load balancer configuration immediately by passing the force_reload=true URL parameter when invoking a command.

Next up

Data Plane API Reference