Tutorials

Manage frontends

On this page

In your load balancer configuration, a frontend section defines the client-facing proxy that receives requests.

You can manage frontends programmatically via the API endpoint /services/haproxy/configuration/frontends.

Getting and setting the version parameter Jump to heading

When making a POST, PUT, or DELETE API call, you must add the version URL parameter. For example:

nix
http://localhost:5555/v3/services/haproxy/configuration/backends/myservers?version=1
nix
http://localhost:5555/v3/services/haproxy/configuration/backends/myservers?version=1

The version parameter must match the load balancer’s current configuration version. This is because the Data Plane API uses optimistic concurrency control, or optimistic locking, to manage its transactions. This ensures that if multiple entities modify a resource that the changes are applied correctly. The APIv3 examples in this section make a GET request to /v3/services/haproxy/configuration/version immediately before making a call to update a resource to retrieve the version and populate the CFGVER environment variable for the URL version parameter as is shown in the following command:

nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v3/services/haproxy/configuration/version)
nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v3/services/haproxy/configuration/version)

You will then use the value of the environment variable to populate the version parameter in the endpoint URL. An example URL may look like this. Note the environment variable reference, $CFGVER:

nix
http://localhost:5555/v3/services/haproxy/configuration/backends/myservers?version=$CFGVER
nix
http://localhost:5555/v3/services/haproxy/configuration/backends/myservers?version=$CFGVER

List frontends Jump to heading

To get a list of frontends, make a GET request to the frontends endpoint:

nix
curl -X GET \
  --user admin:adminpwd \
  "http://localhost:5555/v3/services/haproxy/configuration/frontends"
nix
curl -X GET \
  --user admin:adminpwd \
  "http://localhost:5555/v3/services/haproxy/configuration/frontends"
output
json
[
  {
    "default_backend": "webservers",
    "maxconn":2000,
    "mode":"http",
    "name": "www"
  }
]
output
json
[
  {
    "default_backend": "webservers",
    "maxconn":2000,
    "mode":"http",
    "name": "www"
  }
]
nix
curl -X GET \
  --user admin:adminpwd \
  "http://localhost:5555/v2/services/haproxy/configuration/frontends"
nix
curl -X GET \
  --user admin:adminpwd \
  "http://localhost:5555/v2/services/haproxy/configuration/frontends"
output
json
{
  "_version": 99,
  "data": [
    {
      "default_backend": "webservers",
      "maxconn":2000,
      "mode":"http",
      "name": "www"
    }
  ]
}
output
json
{
  "_version": 99,
  "data": [
    {
      "default_backend": "webservers",
      "maxconn":2000,
      "mode":"http",
      "name": "www"
    }
  ]
}

List a specific frontend Jump to heading

To get information about a specific frontend, make a GET request with the name of the frontend. Below, we view information for the frontend named www:

nix
curl -X GET \
  --user admin:adminpwd \
  "http://localhost:5555/v3/services/haproxy/configuration/frontends/www"
nix
curl -X GET \
  --user admin:adminpwd \
  "http://localhost:5555/v3/services/haproxy/configuration/frontends/www"
output
json
{
  "default_backend": "webservers",
  "maxconn":2000,
  "mode":"http",
  "name": "www"
}
output
json
{
  "default_backend": "webservers",
  "maxconn":2000,
  "mode":"http",
  "name": "www"
}
nix
curl -X GET \
  --user admin:adminpwd \
  "http://localhost:5555/v2/services/haproxy/configuration/frontends/www"
nix
curl -X GET \
  --user admin:adminpwd \
  "http://localhost:5555/v2/services/haproxy/configuration/frontends/www"
output
json
{
   "_version": 99,
   "data":{
      "default_backend":"webservers",
      "maxconn":2000,
      "mode":"http",
      "name":"www"
   }
}
output
json
{
   "_version": 99,
   "data":{
      "default_backend":"webservers",
      "maxconn":2000,
      "mode":"http",
      "name":"www"
   }
}

Add a frontend Jump to heading

To add a frontend, make a POST request to the frontends endpoint. Send the fields to set in the body of the request. Below, we create a new frontend named myfrontend. Note that prior to making the POST request, you must first capture the current version in an environment variable (CFGVER in this example) and use the value in your request.

nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v3/services/haproxy/configuration/version)
curl -X POST \
  --user admin:adminpwd \
  -H "Content-Type: application/json" \
  -d '{
        "name": "myfrontend",
        "mode": "http",
        "default_backend": "webservers",
        "maxconn": 2000
      }' \
  "http://localhost:5555/v3/services/haproxy/configuration/frontends?version=$CFGVER"
nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v3/services/haproxy/configuration/version)
curl -X POST \
  --user admin:adminpwd \
  -H "Content-Type: application/json" \
  -d '{
        "name": "myfrontend",
        "mode": "http",
        "default_backend": "webservers",
        "maxconn": 2000
      }' \
  "http://localhost:5555/v3/services/haproxy/configuration/frontends?version=$CFGVER"
nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v2/services/haproxy/configuration/version)
curl -X POST \
  --user admin:adminpwd \
  -H "Content-Type: application/json" \
  -d '{
        "name": "myfrontend",
        "mode": "http",
        "default_backend": "webservers",
        "maxconn": 2000
      }' \
  "http://localhost:5555/v2/services/haproxy/configuration/frontends?version=$CFGVER"
nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v2/services/haproxy/configuration/version)
curl -X POST \
  --user admin:adminpwd \
  -H "Content-Type: application/json" \
  -d '{
        "name": "myfrontend",
        "mode": "http",
        "default_backend": "webservers",
        "maxconn": 2000
      }' \
  "http://localhost:5555/v2/services/haproxy/configuration/frontends?version=$CFGVER"

Replace a frontend Jump to heading

To make changes to a frontend, you must replace it entirely. To replace an existing frontend, make a PUT request to the frontends endpoint, passing the name of the frontend at the end of the URL path. Note that prior to making the PUT request, you must first capture the current version in an environment variable (CFGVER in this example) and use the value in your request. Here, we replace the frontend named www:

nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v3/services/haproxy/configuration/version)
curl -X PUT \
  --user admin:adminpwd \
  -H "Content-Type: application/json" \
  -d '{
        "name": "www",
        "mode": "tcp",
        "default_backend":
        "webservers",
        "maxconn": 1000
      }' \
  "http://localhost:5555/v3/services/haproxy/configuration/frontends/www?version=$CFGVER"
nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v3/services/haproxy/configuration/version)
curl -X PUT \
  --user admin:adminpwd \
  -H "Content-Type: application/json" \
  -d '{
        "name": "www",
        "mode": "tcp",
        "default_backend":
        "webservers",
        "maxconn": 1000
      }' \
  "http://localhost:5555/v3/services/haproxy/configuration/frontends/www?version=$CFGVER"
nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v2/services/haproxy/configuration/version)
curl -X PUT \
  --user admin:adminpwd \
  -H "Content-Type: application/json" \
  -d '{
        "name": "www",
        "mode": "tcp",
        "default_backend":
        "webservers",
        "maxconn": 1000
      }' \
  "http://localhost:5555/v2/services/haproxy/configuration/frontends/www?version=$CFGVER"
nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v2/services/haproxy/configuration/version)
curl -X PUT \
  --user admin:adminpwd \
  -H "Content-Type: application/json" \
  -d '{
        "name": "www",
        "mode": "tcp",
        "default_backend":
        "webservers",
        "maxconn": 1000
      }' \
  "http://localhost:5555/v2/services/haproxy/configuration/frontends/www?version=$CFGVER"

Delete a frontend Jump to heading

To delete a frontend, use the DELETE method, passing the name of the frontend as part of the URL path. ote that prior to making the DELETE request, you must first capture the current version in an environment variable (CFGVER in this example) and use the value in your request. Below we delete the frontend named www:

nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v3/services/haproxy/configuration/version)
curl -X DELETE \
  --user admin:adminpwd \
  "http://localhost:5555/v3/services/haproxy/configuration/frontends/www?version=$CFGVER"
nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v3/services/haproxy/configuration/version)
curl -X DELETE \
  --user admin:adminpwd \
  "http://localhost:5555/v3/services/haproxy/configuration/frontends/www?version=$CFGVER"
nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v2/services/haproxy/configuration/version)
curl -X DELETE \
  --user admin:adminpwd \
  "http://localhost:5555/v2/services/haproxy/configuration/frontends/www?version=$CFGVER"
nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v2/services/haproxy/configuration/version)
curl -X DELETE \
  --user admin:adminpwd \
  "http://localhost:5555/v2/services/haproxy/configuration/frontends/www?version=$CFGVER"

Do you have any suggestions on how we can improve the content of this page?

Previous page Tutorials Next page Bind to an address
© 2025 HAProxy Technologies, LLC. All Rights Reserved
Manage Cookie Preferences