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.

Note

The version parameter in DELETE, POST, and PUT requests must match the system’s current version. The APIv3 examples in this section use a GET request to /v3/services/haproxy/configuration/version to retrieve the version and populate the CFGVER environment variable for the URL version parameter.

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. 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:

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. 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
© 2024 HAProxy Technologies, LLC. All Rights Reserved
Manage Cookie Preferences