Skip to end of metadata
Go to start of metadata

Manage GSLB via the API

The Technology Behind GSLB

Global Server Load Balancing (GSLB) is built around two Internet technologies:

  • DNS, which allows us to redirect a user to a certain IP address or another DNS name in response to the initial DNS name request.
  • Anycast and BGP, which allows multiple GSLB servers to share the same IP address, and a user's request to be directed to the GSLB server that is topologically closest.


The manage-gslb-zone, manage-gslb-domain, and manage-gslb-group tools allow you to directly manage your globally load balanced domains. These GSLB CLIs are built around the following concepts:

Zone: The top level domain / Start of Authority (SOA) for the GSLB server. This corresponds to your NS delegation. It is set by AppNexus Support to avoid security concerns.
Domain: The domain name you wish to globally load balance.
Resource Group: An abstraction which represents a container for resources (see below). Each domain should contain one or more resource groups. Groups are assigned to domains in specific datacenters, and they direct traffic that has been routed to that datacenter via BGP. Like a local load-balancing pool, you first create the group and then populate it with one or more resources.
Resource: An IP address or CNAME to which you are sending traffic on behalf of the domain name. Each resource group may consist of either a single CNAME record or any number of IP addresses. For each DNS request, GSLB will select one of the domain's groups according to max-traffic parameter.

Steps and Walk-through Example

At each step below, we will walk through load balancing to an instance (IP in NYM1 and an instance (IP in LAX1.

1. Create a GSLB Zone via AppNexus Support

Before you can create a GSLB domain, AppNexus Support must set up a zone to delegate responsibility to the GSLB server for that part of the domain. You will also need to delegate name server rights on your end using one of two possible ways:

a) Delegate your domain name to name servers, namely and
b) Set up a CNAME (say, pointing to

Once the zone is created, you may modify or delete it using the manage-gslb-zone tool.

Walk-through task: Contact AppNexus Support through the Customer Portal and ask them to create the zone

2. Create a GSLB Domain

Next, create a domain with the manage-gslb-domain command. The only mandatory parameter for creating a GSLB domain is --name, which is the domain name you wish to load balance. You may also specify the following if desired:

  • A failover resource. This can be either an IP address or CNAME. It will be returned in the DNS reply for the domain in case when all domain resources are inactive.
  • A monitor type. This can be either TCP, SSL or NONE. Default is TCP. If you use NONE, you must set up your own monitoring system or monitor manually. If there is no monitor, the domain's resources will be marked "inactive" unless they are manually activated.
  • Custom request and search strings for monitoring.
  • Port through which those strings should be communicated. Default port is 80 for both TCP and SSL monitors.
  • A description of the domain.
  • Metadata about the domain.

A NOTE on monitoring: GSLB monitoring knows nothing about high-level protocols like HTTP, etc. It simply opens a telnet-like connection to the given port, sends a request string, reads the response until peer closes connection, and searches for the presence of the search_string in the answer.

Please also note that the same port is used for monitoring all resources of a given domain in all datacenters.

Walk-through task: Create the domain

manage-gslb-domain create -n --failover-ip -d load_balanced_website --username <USERNAME>
$ manage-gslb-domain list --verbose --username <USERNAME>
|                                                        GSLB domains                                                                                     |
| id  | domain             | zone              | failover_resource | monitor_type | request_string         | search_string | port | description           |
| 156 |  | |           | tcp          | GET / HTTP/1.0\r\n\r\n | 200 OK        |   80 | load_balanced_website |
3. Create a Resource Group for Each Datacenter

Each GSLB domain requires at least one resource group, and you will most likely want a resource group for every datacenter. Let's look at a brief version of the manage-gslb-group create command.

manage-gslb-group create -n name [--cname domain | --ip address] [--metadata string | --metadata-file path] [-d description]
  • The name is single required parameter which allows to set name of the GSLB group.
  • The cname/ip allow to bind resource(s) to the group at the time of its creation. Please note that you may bind one (and only one) CNAME or one or more IPs to the group.
  • The metadata/metadata-file allow to specify metadata about the group.
  • The description sets a description of the group.
  • Only one group can be created per command.

Walk-through Task: Create resource groups for resources that are located in each datacenter.

manage-gslb-group create -n mycompany-nym1 --username <USERNAME>
manage-gslb-group create -n mycompany-lax1 --username <USERNAME>
4. Add Resources to Groups

Each group must contain either a single CNAME resource or one or more IP addresses. For each DNS request, GSLB will select one of the domain's groups according to max-traffic parameter (see below).

  • It's recommended to include resources belonging to one datacenter into the group. E.g. in the below example these two groups contain only resources belonging to NYM1 DC and LAX1 DC correspondingly. Then you can assign the groups to the domain in any datacenter so that users who are initially routed to, say, NYM1 will receive an IP address in LAX1.
  • Generally speaking, resources added to groups are not necessary be in the AppNexus datacenters at all. AppNexus GSLB is able to load-balance AppNexus-hosted resources as well as external resources.
  • If a group contains multiple resources, GSLB will return all resources in the group to a DNS request. This allows you to specify multiple A records.
  • As shown in the above paragraph, you may add one resource at the time of group creation. Or, you may add resources later as shown below.

While you can add multiple IP addresses to a group, consider instead creating multiple groups with a single IP address each. This will give you more flexibility in setting max-traffic, and in deactivating resources.

Walk-through Task: Add the resource to the mycompany-nym1 group. Add the resource to the mycompany-lax1 group.

manage-gslb-group add-resource --group-id mycompany-nym1 --ip --username <USERNAME>
manage-gslb-group add-resource --group-id mycompany-lax1 --ip --username <USERNAME>
$ manage-gslb-group list-resources --username <USERNAME>
|          GSLB resources          |
| resource | group_id              |
| | mycompany-lax1 (1125) |
| | mycompany-nym1 (1124) |
5. Assign Groups to the Domain

Now you need to assign just created/populated groups to the domain. In the simplest case the group(s) containing resources from NYM1 are being assigned to the domain in NYM1 datacenter (the same rule works for group(s) containing resources from LAX1 – they are being assigned to to the domain in LAX1 datacenter). For more complicated setups, please see section 'Max-traffic' below.

manage-gslb-domain add-group -D 156 --datacenter-id NYM1 -G mycompany-nym1
manage-gslb-domain add-group -D 156 --datacenter-id LAX1 -G mycompany-lax1
$ manage-gslb-domain list-groups --username <USERNAME>
|                                                                     GSLB   groups                                                               |
| group_id              | active | datacenter_id | domain_id               | served_count | unserved_count | max_traffic (%) | actual_traffic (%) |
| mycompany-lax1 (1125) |      1 | LAX1          | (156) |            0 |              1 |             100 |                  0 |
| mycompany-nym1 (1124) |      1 | NYM1          | (156) |            0 |              1 |             100 |                  0 |

As soon as the monitor gets a positive response, it will mark the resource as UP.

$ manage-gslb-domain list-resources --filter
|                                   GSLB resources                                            |
| resource          | state | group_id              | datacenter_id | domain_id               |
|  | UP    | mycompany-lax1 (1125) | LAX1          | (156) |
|  | UP    | mycompany-nym1 (1124) | NYM1          | (156) |

If you've created domain with monitor type NONE, you must manually activate the resources using these commands:

manage-gslb-domain activate-resource -D 156 --datacenter-id NYM1 -G mycompany-nym1 --ip --username <USERNAME>
manage-gslb-domain activate-resource -D 156 --datacenter-id LAX1 -G mycompany-lax1 --ip --username <USERNAME>

To take care of all GSLB traffic, you MUST map a domain to at least one gslb group in ALL datacenters. (currently LAX1, NYM1, and AMS1). Users directed by BGP to a datacenter without a group will see their DNS requests fail. Note that NYM2 and NYM1 are both served by NYM1. As AppNexus adds more datacenters throughout the world, existing domain/group connections will be replicated to best preserve existing traffic routing characteristics.

You can use

manage-gslb-domain list-datacenters

to see which datacenters advertise GSLB.


The max-traffic parameter is a property of groups assigned to domains, and is used to distribute traffic once it has been initially routed through BGP to the GSLB server.

  • Absolute value of max-traffic defines maximum amount of total traffic routed to the datacenter that can be handled by the group. For example, if you know that the group cannot handle more than 75% of total traffic routed to LAX1 DC you should set max-traffic 75 on assigning the group to domain in LAX1 DC.
  • Relative value of max-traffic only matters when there is more than one group assigned to the domain in a particular datacenter. So if you want the NYM1 GTSB servers to send 80 percent of traffic to IP and 20 percent of traffic to, you will need to assign two groups to the domain in NYM1 DC; the 'mycompany-nym1' group with max-traffic 80 and the 'mycompany-lax1' group with max-traffic 20.
  • When there are multiple resources within a group, all resources in the group will be returned in response to the DNS request.
  • You can set max-traffic when you assign a group to the domain, but you can also modify max-traffic at any time through the manage-gslb-domain modify-group command.
  • It's convinient to keep sum of max-traffics in single dtacenter equal to 100.
  • Zero max-traffic has a special meaning of failover group for given datacenter. Traffic will go to group with max-traffic 0 if, and only if, resources of all other groups in the datacenter fail monitoring, but resources belonging to group with max-traffic 0 monitored OK.
  • It's possible that your resource groups may become overloaded (a situation when actual traffic exceeds the max-traffic value). For example, say your traffic is divided among two resource groups each containing a single resource and any one resource can only handle half the load (max-traffic is set to 50% for each group). If one of your resources fails, the another one could be overloaded and fail as well. To prevent this, you can add more groups to the domain or to add more resources to existing groups (and to increase the max-traffic values after that).
  • Please note the difference between global and datacenter-specific failovers:
    • Resources in datacenter-specific failover groups are monitored as well as "ordinary" resources.
    • Global failover resources are not monitored.

Some examples

1) You want to route users to the closest datacenter — Proximity Routing.
2) Because you have more resources in LAX1, you want 70% of traffic to end up there and 30% to end up in NYM1. If your users are evenly distributed geographically, then equal amounts of traffic initially go to LA and to New York.
3) All traffic is directed to the IP in LA, but an IP New York is set up as a failover.

A Note on Anycasting and BGP

After a domain is delegated to our GSLB servers in order to enable GSLB, users are routed to either the New York, the Los Angeles datacenter or the Amsterdam datacenter through anycasting and BGP, depending on which is "closer" or a faster trip. Once they have been routed, the GSLB server in that datacenter will continue the routing. This means that the GSLB server in NYM1, the GSLB server in LAX1 and the GSLB server in AMS1 will all give out different information. See our Global Load Balancing Overview for more information on BGP and anycasting.

Further Reading

  • No labels