Tutorials

Manage backends

On this page

In your load balancer configuration, a backend defines a pool of servers to load balance.

You can manage backends programmatically by calling the API endpoint /services/haproxy/configuration/backends.

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 backends Jump to heading

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

nix
curl -X GET \
  --user admin:adminpwd \
  "http://localhost:5555/v3/services/haproxy/configuration/backends"
nix
curl -X GET \
  --user admin:adminpwd \
  "http://localhost:5555/v3/services/haproxy/configuration/backends"
output
json
[
  {
    "balance": {
      "algorithm": "roundrobin"
    },
    "default_server": {
      "alpn": "h2",
      "check": "enabled",
      "maxconn": 30,
      "weight": 100
    },
    "mode": "http",
    "name": "webservers"
  }
]
output
json
[
  {
    "balance": {
      "algorithm": "roundrobin"
    },
    "default_server": {
      "alpn": "h2",
      "check": "enabled",
      "maxconn": 30,
      "weight": 100
    },
    "mode": "http",
    "name": "webservers"
  }
]
nix
curl -X GET \
  --user admin:adminpwd \
  "http://localhost:5555/v2/services/haproxy/configuration/backends"
nix
curl -X GET \
  --user admin:adminpwd \
  "http://localhost:5555/v2/services/haproxy/configuration/backends"
output
json
{
  "_version": 99,
  "data": [
    {
      "balance": {
        "algorithm": "roundrobin"
      },
      "default_server": {
        "alpn": "h2",
        "check": "enabled",
        "maxconn": 30,
        "weight": 100
      },
      "mode": "http",
      "name": "webservers"
    }
  ]
}
output
json
{
  "_version": 99,
  "data": [
    {
      "balance": {
        "algorithm": "roundrobin"
      },
      "default_server": {
        "alpn": "h2",
        "check": "enabled",
        "maxconn": 30,
        "weight": 100
      },
      "mode": "http",
      "name": "webservers"
    }
  ]
}

List a specific backend Jump to heading

To get information about a specific backend, make a GET request with the name of the backend. Below, we get information about the backend named webservers:

nix
curl -X GET \
  --user admin:adminpwd \
  "http://localhost:5555/v3/services/haproxy/configuration/backends/webservers"
nix
curl -X GET \
  --user admin:adminpwd \
  "http://localhost:5555/v3/services/haproxy/configuration/backends/webservers"
output
json
{
  "balance": {
    "algorithm": "roundrobin"
  },
  "default_server": {
    "alpn": "h2",
    "check": "enabled",
    "maxconn": 30,
    "weight": 100
  },
  "mode": "http",
  "name": "webservers"
}
output
json
{
  "balance": {
    "algorithm": "roundrobin"
  },
  "default_server": {
    "alpn": "h2",
    "check": "enabled",
    "maxconn": 30,
    "weight": 100
  },
  "mode": "http",
  "name": "webservers"
}
nix
curl -X GET \
  --user admin:adminpwd \
  "http://localhost:5555/v2/services/haproxy/configuration/backends/webservers"
nix
curl -X GET \
  --user admin:adminpwd \
  "http://localhost:5555/v2/services/haproxy/configuration/backends/webservers"
output
json
{
  "_version": 99,
  "data":{
    "balance": {
      "algorithm": "roundrobin"
    },
    "default_server": {
      "alpn": "h2",
      "check": "enabled",
      "maxconn": 30,
      "weight": 100
    },
    "mode": "http",
    "name": "webservers"
  }
}
output
json
{
  "_version": 99,
  "data":{
    "balance": {
      "algorithm": "roundrobin"
    },
    "default_server": {
      "alpn": "h2",
      "check": "enabled",
      "maxconn": 30,
      "weight": 100
    },
    "mode": "http",
    "name": "webservers"
  }
}

Add a backend Jump to heading

To add a backend, make a POST request to the backends endpoint. Send the fields to set in the body of the request. 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. Below, we create a new backend named myservers:

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": "myservers",
    "mode": "http",
    "balance": {
      "algorithm": "roundrobin"
    },
    "default_server": {
      "alpn": "h2",
      "check": "enabled",
      "check_alpn": "h2",
      "maxconn": 30,
      "weight": 100
    }
  }' \
  "http://localhost:5555/v3/services/haproxy/configuration/backends?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": "myservers",
    "mode": "http",
    "balance": {
      "algorithm": "roundrobin"
    },
    "default_server": {
      "alpn": "h2",
      "check": "enabled",
      "check_alpn": "h2",
      "maxconn": 30,
      "weight": 100
    }
  }' \
  "http://localhost:5555/v3/services/haproxy/configuration/backends?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": "myservers",
    "mode": "http",
    "balance": {
      "algorithm": "roundrobin"
    },
    "default_server": {
      "alpn": "h2",
      "check": "enabled",
      "check_alpn": "h2",
      "maxconn": 30,
      "weight": 100
    }
  }' \
  "http://localhost:5555/v2/services/haproxy/configuration/backends?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": "myservers",
    "mode": "http",
    "balance": {
      "algorithm": "roundrobin"
    },
    "default_server": {
      "alpn": "h2",
      "check": "enabled",
      "check_alpn": "h2",
      "maxconn": 30,
      "weight": 100
    }
  }' \
  "http://localhost:5555/v2/services/haproxy/configuration/backends?version=$CFGVER"

Replace a backend Jump to heading

To make changes to a backend, you must replace it entirely. To replace an existing backend, make a PUT request to the backends endpoint, passing the name of the backend 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:

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": "myservers",
    "mode": "http",
    "balance": {
      "algorithm": "roundrobin"
    },
    "default_server": {
      "alpn": "h2",
      "check": "enabled",
      "check_alpn": "h2",
      "maxconn": 30,
      "weight": 50
    }
  }' \
  "http://localhost:5555/v3/services/haproxy/configuration/backends/myservers?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": "myservers",
    "mode": "http",
    "balance": {
      "algorithm": "roundrobin"
    },
    "default_server": {
      "alpn": "h2",
      "check": "enabled",
      "check_alpn": "h2",
      "maxconn": 30,
      "weight": 50
    }
  }' \
  "http://localhost:5555/v3/services/haproxy/configuration/backends/myservers?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": "myservers",
    "mode": "http",
    "balance": {
      "algorithm": "roundrobin"
    },
    "default_server": {
      "alpn": "h2",
      "check": "enabled",
      "check_alpn": "h2",
      "maxconn": 30,
      "weight": 50
    }
  }' \
  "http://localhost:5555/v2/services/haproxy/configuration/backends/myservers?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": "myservers",
    "mode": "http",
    "balance": {
      "algorithm": "roundrobin"
    },
    "default_server": {
      "alpn": "h2",
      "check": "enabled",
      "check_alpn": "h2",
      "maxconn": 30,
      "weight": 50
    }
  }' \
  "http://localhost:5555/v2/services/haproxy/configuration/backends/myservers?version=$CFGVER"

Delete a backend Jump to heading

To delete a backend, use the DELETE method, passing the name of the backend as part of the URL path. Note 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 backend named myservers:

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/backends/myservers?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/backends/myservers?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/backends/myservers?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/backends/myservers?version=$CFGVER"

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

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