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.
-
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" } ]
-
For each command that you want to include in the transaction, add the transaction's
id
value as thetransaction_id
URL parameter. You do not need to include aversion
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" }
-
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 }
-
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" }
-
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 }
-
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