API and CLI Release 0.176
NEW FEATURES IN RELEASE 0.176
This release introduces a new API for directly managing Global Server Load Balancing (GSLB) via a set of new GSLB servers, independent from the F5 servers now in use. We introduce this API below, but we encourage you to visit https://wiki.appnexus.com/display/documentation/Managing+Global+Server+Load+Balancing for a more detailed description of the API and a walk-through guide. For a general overview of GSLB, please see https://wiki.appnexus.com/display/documentation/Global+Load+Balancing+Documentation.
The set of CLI tools for this API are: manage-gslb-zone, manage-gslb-domain, manage-gslb-group. These CLIs are built around the following concepts:
- Zone: The top level domain / Start of Authority (SOA) for the GSLB server. This corresponds to your name server delegation. It is set by AppNexus Support to avoid security concerns.
- Domain: The domain name you wish to globally load balance.
- Resource Group: Each GSLB domain contains one or more resource groups. Groups are associated with specific datacenters and 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. 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 weight parameters, described below.
Before you can manage GSLB, AppNexus Support must set up a zone to delegate responsibility to the GSLB server for that part of the domain. Once the zone is created, you can manage it with the tool "manage-gslb-zone".
manage-gslb-zone list --sort name
manage-gslb-zone modify -z example.com --description 'use as example'
manage-gslb-zone delete -z 12
The only requirement to create a GSLB domain is a domain name. You can also specify a failover resource (either CNAME or IP address), monitor type, monitoring port, search and request strings, a description, and metadata. You can then list, modify, and delete domains.
manage-gslb-domain create --name test.example.com --failover-cname failover.example.com --monitor-type ssl --port 443 manage-gslb-domain list --filter name=example.com manage-gslb-domain modify –D 14 --request-string 'GET /status.php HTTP/1.0rnrn' --search-string 'ready: 1'
manage-gslb-domain delete –D master.example.com
Groups are attached to a specific datacenter and contain resources. For each DNS request GSLB will return all the resources in one of the groups in that datacenter. The decision on which resource group should be returned depends on the groups' weights, described below.
manage-gslb-group add --domain-id 27 --datacenter-id NYM1 manage-gslb-group modify --group-id NYM1:123 --weight 50 manage-gslb-group list manage-gslb-group remove --group-id NYM1:123
A group may contain either one CNAME resource (domain name) or one or more IP addresses (A records). It is important to note that the resource does not have to be in the same datacenter as the group; you may want to send traffic originally routed by BGP to one datacenter to an IP address in a different datacenter. Also, resource activation is only required if you are not using the GSLB server's TCP or SSL monitoring.
manage-gslb-group add-resource -G NYM:123 --ip 188.8.131.52 manage-gslb-group remove-resource -G NYM1:123 --ip 184.108.40.206 manage-gslb-group activate-resource -G NYM1:123 --cname mycompany.example.com manage-gslb-group deactivate-resource -G NYM1:123 --cname mycompany.example.com
To distribute traffic to various IPs or CNAMES, you will use the "--weight" parameter for the manage-gslb-group command. Weighting divides traffic among different groups in the same datacenter. For example, if you want the NYM1 load balancer to send 80 percent of traffic to IP 220.127.116.11 and 20 percent of traffic to 18.104.22.168, you will make two groups; one containing IP 22.214.171.124 and set at weight 80 and one containing IP 126.96.36.199 and set at weight 20.
manage-gslb-group add -D test.example.com --datacenter-id NYM1 --ip 188.8.131.52 --weight 80 manage-gslb-group add -D test.example.com --datacenter-id NYM1 --ip 184.108.40.206 --weight 20 manage-gslb-group modify -G NYM1:35 --weight 30 --max-usage 60
This release introduces a new tool for directly managing your Access Control List (ACL). This tool is a part of the existing "manage-vlan" CLI tool and consists of the following commands:
- manage-vlan get-acl. Lists the current ACL for your VLAN. If you specify the --file optional parameter, you can output the ACL to the corresponding file.
- manage-vlan set-acl. Replaces the current ACL with a new one. If you attempt to erase the ACL completely, you will be prompted to enter "-force" as a precaution.
- manage-vlan append-acl. Appends one or more new ACEs to the end of the current VLAN ACL.
- manage-vlan validate-acl. Validates the syntax and semantics of ACEs without applying them to your VLAN.
Note that ACEs can be read either from a file or via a standard input.
manage-vlan get-acl --vlan-id NYM1:2071
manage-vlan set-acl --vlan-id NYM1:2071 --file nym1-vlan2071.acl manage-vlan validate-acl --file /path/to/file/acl.example cat /path/to/file/acl.example | manage-vlan validate-acl -
For more details on the ACL API and ACL syntax, please see https://wiki.appnexus.com/display/documentation/Managing+ACLs.
1. You can now specify file permissions as three octal digits in the "--upload" parameter of the "manage-instance launch" command. An omitted digit is assumed to be a leading zero.
--metadata and --metadata-file parameters were added to the "manage-instance launch" command. This creates consistency with other CLI tools.
3. Metadata can now be modified for custom load balancing pools, as it already can be for standard pools.