HAProxy ALOHA

Manage GSLB

This page applies to:

  • HAProxy ALOHA 18.5 and newer

Running HAProxy Enterprise?

See Manage GSLB, which also covers installing and configuring the module.

Overview Jump to heading

You can use HAProxy Data Plane API on HAProxy ALOHA to manage the appliance’s Global Server Load Balancing (GSLB) configuration. It reads and changes zones, records, answer lists, answer records, and GeoIP maps through the /services/gslb endpoints, and validates every change before it takes effect.

The gslb section is already present in the API’s configuration file, /app/var/management/lib/dataplaneapi/dataplaneapi.yaml, and points to the GSLB configuration is manages at /etc/gslb/gslb.conf, so there is nothing to install or configure.

Tasks Jump to heading

Every request on this page targets port 5555, the HAProxy ALOHA appliance’s API port, with the admin:admin credential.

List zones Jump to heading

nix
curl --request GET \
--user admin:admin \
"http://localhost:5555/v3/services/gslb/configuration/zones"
nix
curl --request GET \
--user admin:admin \
"http://localhost:5555/v3/services/gslb/configuration/zones"
output
json
[]
output
json
[]

Add a zone Jump to heading

Adding a zone needs the current GSLB configuration version, so read it first and pass it in the request:

nix
CFGVER=$(curl -s -u admin:admin http://localhost:5555/v3/services/gslb/configuration/version)
curl --request POST \
--user admin:admin \
--header "Content-Type: application/json" \
-d '{
"name": "other.example.net",
"ttl": 600,
"records": [
{
"name": "@",
"params": {
"type": "SOA",
"primary_master": "ns1.other.example.net.",
"mail": "admin.other.example.net.",
"serial": 1,
"refresh": 7200,
"retry": 1800,
"expire": 259200,
"ncache": 900
}
},
{
"name": "@",
"params": {
"type": "NS",
"hostname": "ns1.other.example.net."
}
},
{
"name": "ns1",
"params": {
"type": "A",
"ipv4_address": "203.0.113.9"
}
}
]
}' \
"http://localhost:5555/v3/services/gslb/configuration/zones?version=$CFGVER"
nix
CFGVER=$(curl -s -u admin:admin http://localhost:5555/v3/services/gslb/configuration/version)
curl --request POST \
--user admin:admin \
--header "Content-Type: application/json" \
-d '{
"name": "other.example.net",
"ttl": 600,
"records": [
{
"name": "@",
"params": {
"type": "SOA",
"primary_master": "ns1.other.example.net.",
"mail": "admin.other.example.net.",
"serial": 1,
"refresh": 7200,
"retry": 1800,
"expire": 259200,
"ncache": 900
}
},
{
"name": "@",
"params": {
"type": "NS",
"hostname": "ns1.other.example.net."
}
},
{
"name": "ns1",
"params": {
"type": "A",
"ipv4_address": "203.0.113.9"
}
}
]
}' \
"http://localhost:5555/v3/services/gslb/configuration/zones?version=$CFGVER"
output
json
{
"name": "other.example.net",
"records": [
{
"name": "@",
"params": {
"type": "SOA",
"primary_master": "ns1.other.example.net.",
"mail": "admin.other.example.net.",
"serial": 1,
"refresh": 7200,
"retry": 1800,
"expire": 259200,
"ncache": 900
}
},
{
"name": "@",
"params": {
"type": "NS",
"hostname": "ns1.other.example.net."
}
},
{
"name": "ns1",
"params": {
"type": "A",
"ipv4_address": "203.0.113.9"
}
}
],
"ttl": 600
}
output
json
{
"name": "other.example.net",
"records": [
{
"name": "@",
"params": {
"type": "SOA",
"primary_master": "ns1.other.example.net.",
"mail": "admin.other.example.net.",
"serial": 1,
"refresh": 7200,
"retry": 1800,
"expire": 259200,
"ncache": 900
}
},
{
"name": "@",
"params": {
"type": "NS",
"hostname": "ns1.other.example.net."
}
},
{
"name": "ns1",
"params": {
"type": "A",
"ipv4_address": "203.0.113.9"
}
}
],
"ttl": 600
}

Read the zones Jump to heading

nix
curl --request GET \
--user admin:admin \
"http://localhost:5555/v3/services/gslb/configuration/zones"
nix
curl --request GET \
--user admin:admin \
"http://localhost:5555/v3/services/gslb/configuration/zones"
output
json
[
{
"name": "other.example.net",
"records": [
{
"name": "@",
"params": {
"type": "SOA",
"primary_master": "ns1.other.example.net.",
"mail": "admin.other.example.net.",
"serial": 1,
"refresh": 7200,
"retry": 1800,
"expire": 259200,
"ncache": 900
}
},
{
"name": "@",
"params": {
"type": "NS",
"hostname": "ns1.other.example.net."
}
},
{
"name": "ns1",
"params": {
"type": "A",
"ipv4_address": "203.0.113.9"
}
}
],
"ttl": 600
}
]
output
json
[
{
"name": "other.example.net",
"records": [
{
"name": "@",
"params": {
"type": "SOA",
"primary_master": "ns1.other.example.net.",
"mail": "admin.other.example.net.",
"serial": 1,
"refresh": 7200,
"retry": 1800,
"expire": 259200,
"ncache": 900
}
},
{
"name": "@",
"params": {
"type": "NS",
"hostname": "ns1.other.example.net."
}
},
{
"name": "ns1",
"params": {
"type": "A",
"ipv4_address": "203.0.113.9"
}
}
],
"ttl": 600
}
]

To read a single zone, add its name to the path:

nix
curl --request GET \
--user admin:admin \
"http://localhost:5555/v3/services/gslb/configuration/zones/other.example.net"
nix
curl --request GET \
--user admin:admin \
"http://localhost:5555/v3/services/gslb/configuration/zones/other.example.net"

Delete a zone Jump to heading

To remove a zone, make a DELETE request to the zones endpoint with the zone name in the path and the current version in the query string. To replace a zone instead, send the whole zone again in a PUT request to the same path; the body is the same as the one in Add a zone, with your changes applied.

nix
CFGVER=$(curl -s -u admin:admin http://localhost:5555/v3/services/gslb/configuration/version)
curl --request DELETE \
--user admin:admin \
"http://localhost:5555/v3/services/gslb/configuration/zones/other.example.net?version=$CFGVER"
nix
CFGVER=$(curl -s -u admin:admin http://localhost:5555/v3/services/gslb/configuration/version)
curl --request DELETE \
--user admin:admin \
"http://localhost:5555/v3/services/gslb/configuration/zones/other.example.net?version=$CFGVER"
output
text
HTTP 202
output
text
HTTP 202

See also Jump to heading

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