Contents

Overview

text
Load Balancer object relationships

Real IP objects represent actual server hosts, such as web servers. A Real IP may refer to a GoGrid server in any of our datacenters or to other servers hosted elsewhere.

Virtual IP objects combine one or more Real IP objects behind a GoGrid-assigned IP address.

Health Checker objects run periodic checks on Real IP servers, temporarily remove them from a Virtual IP when they stop functioning correctly, then re-add them when they resume correct operations.

Listener objects represent the load balancers which listen for connections to Virtual IPs and redirect them to Real IPs, based on Health Checker results and other configuration options.

Data types

  • idinfo fields may contain upper- and lowercase letters, numbers, and hyphens.
  • All returned timestamps are in UTC.

Health Checker

API calls to access and modify load balancer health checks.

Health Checker URLs

  • /{customerid}/loadbalancer/healthchecker
    • HTTP Method Support: GET
  • /{customerid}/loadbalancer/healthchecker/{idinfo}
    • HTTP Method Support: GET, POST, PUT, DELETE
URI Parameter Type Description
customerid long Your customer id

Health Checker Object Description

Name Required Type Version Constraints Description
idinfo yes string 2.0 read-only after creation Identifier of the Health Checker object. Max length size is 128 characters. This value cannot be changed after object creation. Once used, no other Health Checker object may ever be created with the same idinfo in the same data center.
name yes string 2.0   Name of this Health Checker object. Max length size is 255 characters. No two Health Checker objects in the same datacenter may have the same name at the same time.
description   string 2.0   Description field for this Health Checker object. Max length size is 1024 characters.
checkertype yes string 2.0   The health checker type which controls the service health check for load balancing. The valid string values are:
  • uritest - Perform an HTTP GET request on the URI specified in checkerparameter. This checker works well for regular, non-SSL web servers.
  • connect - Test for a successful IP connection. This is a good choice for non-web servers such as databases, email, etc. It does not use the checkerparameter as it is only checking connections on the port.
  • sslcheck - Test for an SSL connection on the Real IP server. This verifies that clients can open an encrypted connection to the server, but not that the server is returning correct results (such as successfully serving web pages).
checkerparameter   map 2.0   A map that acts as input for this Health Checker.

The valid key/string values for uritest are:

  • uri - The URI of the resource to test on the real IP retrieved by an HTTP GET request. Default is /
  • host - The hostname to be passed to the test server. If host is specified, the Health Checker will use HTTP 1.1. Otherwise, HTTP 1.0 is used. Default is None.
intervalms   long 2.0   Time between checks, in milliseconds. Values must be between 4,000 and 300,000, and the default value is 10,000.
timeoutms   long 2.0   Health check timeout, in milliseconds. Values must be between 2,000 and 60,000, and the default value is 5,000.
checkstring   string 2.0   If given and checkertype is set to 'uritest', then this value must be found in the body of a health check response for it to pass.
datacenter   string 2.0 read-only Datacenter where this Health Checker lives.
createdby   string 2.0 read-only User identity who created this object.
modifiedby   string 2.0 read-only User identity who modified this object.
deletedby   string 2.0 read-only User identity who deleted this object.
createdon   datetime 2.0 read-only Date time when this object was created. All returned timestamps are in UTC.
modifiedon   datetime 2.0 read-only Date time when this object was last modified on. All returned timestamps are in UTC.

Real IP

API calls to access and modify load balancer Real IPs objects. Real IP objects are pointers to IPs. They may reference IPs anywhere (not just GoGrid IPs) .

Real IP URL

  • /{customerid}/loadbalancer/realip
    • HTTP Method Support: GET
  • /{customerid}/loadbalancer/realip/{idinfo}
    • HTTP Method Support: GET, POST, PUT, DELETE


URI Parameter Type Description
customerid long Your customer id

Real IP Object Description

Name Required Type Version Constraints Description
idinfo yes string 2.0 read-only after creation Identifier of the Real IP object. Max length size is 128 characters. This value cannot be changed after object creation. Once used, no other Real IP object may ever be created with the same idinfo in the same data center.
name yes string 2.0   Name of this Real IP object. Max length size is 255 characters. No two Real IP objects in the same datacenter may have the same name at the same time.
description   string 2.0   Description field for this Real IP object. Max length size is 1024 characters.
address yes string 2.0   Real IP address to be load balanced to. Must be a valid IPv4 address.
enabled   boolean 2.0   Whether this Real IP object should accept connections through the Listener.
weight   int 2.0   The weight of this Real IP object, from 1 to 255. Default is 100.
gridlocal   boolean 2.0 read-only "true" if this Real IP object is a part of GoGrid's own network, or "false" if it resides elsewhere.
datacenter   string 2.0 read-only Datacenter where this Real IP lives.
createdby   string 2.0 read-only User identity who created this object.
modifiedby   string 2.0 read-only User identity who modified this object.
deletedby   string 2.0 read-only User identity who deleted this object.
createdon   datetime 2.0 read-only Date time when this object was created. All returned timestamps are in UTC.
modifiedon   datetime 2.0 read-only Date time when this object was last modified on. All returned timestamps are in UTC.

Virtual IP

API calls to access and modify load balancer Virtual IP objects.

Virtual IP URLs

  • /{customerid}/loadbalancer/virtualip
    • HTTP Method Support: GET
  • /{customerid}/loadbalancer/virtualip/{idinfo}
    • HTTP Method Support: GET, POST, PUT, DELETE
URI Parameter Type Description
customerid long Your customer id

Virtual IP Object Description

Name Required Type Version Constraints Description
idinfo yes string 2.0 read-only after creation Identifier of the Virtual IP object. Max length size is 128 characters. This value cannot be changed after object creation. Once used, no other Virtual IP object may ever be created with the same name in the same data center.
name yes string 2.0   Name of this Virtual IP object. Max length size is 255 characters. No two Virtual IP objects in the same datacenter may have the same name at the same time.
description   string 2.0   Description field for this Virtual IP object. Max length size is 1024 characters.
address   string 2.0 read-only Virtual IP address. This address will be auto-assigned on creation and cannot be modified.
realips yes list 2.0   List of URIs of Real IP objects that this Virtual IP will load balance to.
listeners   list 2.0 read-only List of URIs of Listener objects that this Virtual IP is attached to.
datacenter   string 2.0 read-only Datacenter where this Virtual IP lives. This field is a read-only attribute.
createdby   string 2.0 read-only User identity who last modified this object.
modifiedby   string 2.0 read-only User identity who last modified this object.
deletedby   string 2.0 read-only User identity who deleted this object.
createdon   datetime 2.0 read-only Date time when this object was created. All returned timestamps are in UTC.
modifiedon   datetime 2.0 read-only Date time when this object was last modified on. All returned timestamps are in UTC.

Listener

API calls to access and modify load balancer Listeners.

Listener URLs

  • /{customerid}/loadbalancer/listener
    • HTTP Method Support: GET
  • /{customerid}/loadbalancer/listener/{idinfo}
    • HTTP Method Support: GET, POST, PUT, DELETE
URI Parameter Type Description
customerid long Your customer id

Listener Object Description

Name Required Type Version Constraints Description
idinfo yes string 2.0 read-only after creation Identifier of the Listener object. Max length size is 128 characters. This value cannot be changed after object creation. Once used, no other Listener object may ever be created with the same idinfo in the same data center.
name yes string 2.0   Name of this Listener object. Max length size is 255 characters. No two Listener objects in the same datacenter may have the same name at the same time.
description   string 2.0   Description field for this Listener object. Max length size is 1024 characters.
virtualip   object 2.0 auto generated IP of Virtual IP object that this Listener balances connections for.
virtualport yes int 2.0   Port on the Virtual IP to listen on for incoming connections.
realport yes int 2.0   Port to connect to Real IP servers on.
protocol yes string 2.0   IP Protocol type for this Listener. The valid string values are:
  • tcp - Balance TCP/IP traffic
application yes string 2.0   Application support for this Listener. The valid string values are:
  • none - No application support (raw socket)
  • http - HTTP X-Forwarded-For / Cookie persistence
healthchecker yes string 2.0   URI of Health Checker object used to monitor the Real IP objects.
healthcheckeradjustment yes string 2.0   The health checker adjustment controls how load balancing reacts to a health check result. The valid string values are:
  • boolean - On/Off. A failed health check will remove a Real IP server from the pool of servers that the Listener forwards connections to. A successful check afterward will add it back into the pool.
routingmode yes string 2.0   The routing setup for load balanced traffic. The valid string values are:
  • connect - Connect by TCP
balanceralgorithm yes string 2.0   The load balancing algorithm. The valid string values are:
  • rr - The Round Robin balancer algorithm uses weighting to schedule the rotation of Real IP servers behind a Listener. This can be used to distribute loads more heavily to faster or closer servers. This is a good balancing method for routing HTTP traffic or other types of connections with short durations.
  • wlc - The Weighted Least Connections balancer uses weighting when choosing between multiple servers with the same number of open connections. This is a reasonable choice for long-lasting connections, such as to a database server.
  • source - The Source Address Hashing balancer will route connections to servers based on each client's address so that multiple connections from the same client will be directed to the same server. Weighting is used to send more connections to highly weighted servers. This balancing method can be used to implement a best-effort, unguaranteed type of persistence for non-HTTP connections or for HTTP clients that refuse to set session cookies. Be aware that the mapping of new connections to servers changes whenever a healthchecker adds or removes a server from the Listener.
Notes on weighting

In general terms, weighted algorithms choose a server proportionally to its weight divided by the total of all servers' weights. For example, if there are two servers - "A" with weight 2 and "B" with weight 1 - then "A" will be chosen 2/3 of the time and "B" will be selected 1/3 of the time. The order in which the servers are selected is unspecified and subject to change, so no particular pattern should be expected or counted on.

persistencemode yes string 2.0   The persistence mode controls the style of client-to-Real IP stickiness in the load balancer. The valid string values are:
  • ipsubnet - Clients in the same /24 IP subnet will be routed to the same server for a limited period of time.
  • none - No persistence.
  • servercookie - Persist based on server cookie. This is only valid for Listeners with "application" set to "http".
persistencecontroldata yes string 2.0   When "persistencemode" set to "servercookie", this is the name of that cookie. Default is "lbcookie".
datacenter   string 2.0 read-only Datacenter where this Listener lives.
createdby   string 2.0 read-only User identity who created this object.
modifiedby   string 2.0 read-only User identity who modified this object.
deletedby   string 2.0 read-only User identity who deleted this object.
createdon   datetime 2.0 read-only Date time when this object was created. All returned timestamps are in UTC.
modifiedon   datetime 2.0 read-only Date time when this object was last modified on. All returned timestamps are in UTC.

Load Balancer Status

Listener Status

  • /{customerid}/loadbalancer/listener/{listeneridinfo}/status
    • HTTP Method Support: GET
URI Parameter Type Description
customerid long Your customer id

Returns that Listener object's status, which will be one of:

    • UNK - unknown
    • INI - initializing
    • OPEN - accepting connections

Real IP Status

  • /{customerid}/loadbalancer/listener/{listeneridinfo}/realipstats/{realipidinfo}/check_status
    • HTTP Method Support: GET
URI Parameter Type Description
customerid long Your customer id
listeneridinfo string The idinfo of the Listener to retrieve status from

Returns the status of a Real IP attached to the Listener's Virtual IP object, which will be one of:

    • UNK - unknown
    • INI - initializing
    • SOCKERR - socket error
    • L4OK - check passed on layer 4, no upper layers testing enabled
    • L4TMOUT - layer 1-4 timeout
    • L4CON - layer 1-4 connection problem, for example "Connection refused" (tcp rst) or "No route to host" (icmp)
    • L6OK - check passed on layer 6
    • L6TOUT - layer 6 (SSL) timeout
    • L6RSP - layer 6 invalid response - protocol error
    • L7OK - check passed on layer 7
    • L7OKC - check conditionally passed on layer 7, for example 404 with disable-on-404
    • L7TOUT - layer 7 (HTTP/SMTP) timeout
    • L7RSP - layer 7 invalid response - protocol error
    • L7STS - layer 7 response error, for example HTTP 5xx

Load Balancer Statistics

APIs to retrieve statistics for a particular virtualip, attached real IPs.

Statistics URLS

  • /{customerid}/loadbalancer/listener/{listeneridinfo}/stats/{statname}/{span} (For listener summary statistics)
  • /{customerid}/loadbalancer/listener/{listeneridinfo}/realipstats/{realipidinfo}/{statname}/{span} (For per-realip statistics)
    • HTTP Method Support: GET
URI Parameter Type Description
customerid long Your customer id
listeneridinfo string The idinfo of the Listener to retrieve stats from
realipidinfo string The idinfo of the Real IP to retrieve stats from
statname string The different types of stats supported are:
  • bin (Bytes/sec IN)
  • bout (Bytes/sec OUT)
  • qcur (Queue Depth)
  • rate (Request Rate)
  • scur (Current Sessions)
  • hrsp_2xx (HTTP 2XX Responses)
  • hrsp_3xx (HTTP 3XX Responses)
  • hrsp_4xx (HTTP 4XX Responses)
  • hrsp_5xx (HTTP 5XX Responses)
  • hrsp_other (HTTP Protocol Error Responses)
  • chkfail (Count of failed health checks)
  • check_status (Last health check status, supported only for realipstats, current data only, as a string)
  • status (Current VIP status, not allowed in realipstats, current data only, as a string)

Statistics Object Description

A stats call will return a JSON array containing pairs of data:


Name Type Version Description
timestamp long 2.0 The UNIX timestamp corresponding to the timeslice of the statistic point

Examples

Add Real IP Object

POST /12345/loadbalancer/realip/realip1-idinfo

Content:
{
    "name": "realip1",
    "description": "This is a real server",
    "address": "121.57.130.154",
    "enabled": true,
    "weight": 100

}

Retrieve a Real IP Object

GET /12345/loadbalancer/realip/realip1-idinfo

Content:
{
    "idinfo": "realip1-idinfo", 
    "name": "realip1", 
    "description": "This is a real server",
    "address": "121.57.130.154",
    "enabled": true,
    "weight": 100
    "gridlocal": true, 
    "datacenter" "US-West-1
    "createdby": "testuser@gogrid.com",  
    "modifiedby": "testuser@gogrid.com", 
    "deletedby": null,
    "createdon": "2013-02-26T18:31:54.220",
    "modifiedon": "2013-02-26T18:31:54.220", 
    "deletedon": null

}

Edit a Real IP Object

PUT /12345/loadbalancer/realip/realip1-idinfo

Content:
{
    "name": "realip1",
    "description": "This is a real server",
    "address": "121.57.130.154",
    "enabled": true,
    "weight": 100

}

Deleting a Real IP Object

DELETE /12345/loadbalancer/realip/realip1-idinfo

Personal tools