API

grid.loadbalancer.add

From GoGrid



Contents

This call will add a single load balancer object to your grid. This method follows a common add pattern.

Data Center-Specific Behavior

Your GoGrid account includes IP addresses in both our US-West-1 and US-East-1 data centers, with each data center having its own IP address range. The IP address you choose as your virtual IP address determines the data center to which the load balancer is added. For example, your load balancer will be added to US-East-1 if you specify a US-East-1 IP as the virtual IP address. Note that the virtual and real IP addresses must be from the same data center.

To access data center functionality, you must set your version parameter (v) to 1.5 or higher.


Request

URL


Role Based Access Control Permissions

  • Super User
  • System User

Input Request Query Parameters

Required Name Version Type Description
Required api_key 1.0 string An API Key generated by GoGrid.
  sig 1.0 string An MD5 Signature that signs each and every API request. Instructions on how to generate this signature can be found here.
v 1.0 string The version of the API. For more information, see API Versions.
  • For version 1.3, set parameter to 1.3
  name string The name of this load balancer. There is a 20 character limit on this field.
  virtualip.ip 1.0 string The IPv4 of the virtual IP for this load balancer. This must be a publicly available IP.
  virtualip.port 1.0 int The port associated with the value of virtualip.ip that constitutes the virtual IP port pair.
  • Must be a positive integer value > 0.
  realiplist.n.ip 1.0 string The IP for an IP/port pair in the real IP list for this load balancer. n is the index of the element and should start with 0 or 1. Input will iterate with consecutive integers until the parameters stop. It is associated with the matching value of realiplist.n.ip that constitutes one real IP/port pair in the real IP list.
  realiplist.n.port 1.0 int The port associated with the matching value of realiplist.n.ip that constitutes one real IP/port pair in the real IP list.
  • Must be a positive integer value > 0.
Optional description 1.0 string Descriptive text to describe this load balancer.
  loadbalancer.type 1.0 string The load balancer type of this load balancer. This can be an int or string representing the load balancer option's id or name respectively.
  • Default is round robin.
  • To list loadbalancer.type values, call common.lookup.list with lookup set to loadbalancer.type
  loadbalancer.persistence 1.0 string The persistence type of this load balancer. The load balancer type of this load balancer. This can be an int or string representing the load balancer persistence types option's id or name respectively.
  • Default is none.
  • To list loadbalancer.persistence values, call common.lookup.list with lookup set to loadbalancer.persistence
format 1.0 string The output format of the response. For more information, see Output Formats.
  • For JSON, set parameter to json.
  • For XML, set parameter to xml.
  • For CSV, set parameter to csv.
  • Default is json.

Sample Request

To add a load balancer with the virtual ip:port of 192.200.10.101:80 and three real ips 192.200.10.102, 192.200.10.103, 192.200.10.104 all on port 80: 

https://api.gogrid.com/api/grid/loadbalancer/add
  ?name=My+First+Load+Balancer
  &virtualip.ip=192.200.10.101
  &virtualip.port=80
  &realiplist.0.ip=192.200.10.102
  &realiplist.0.port=80
  &realiplist.1.ip=192.200.10.103
  &realiplist.1.port=80
  &realiplist.2.ip=192.200.10.104
  &realiplist.2.port=80
  &description=This+is+text+to+describe+this+load+balancer
  &type=round robin
  &persistence=none
  ... auth parameters ...


Response


A common add response for Load Balancers.

JSON Response

{
    "list": [{
        "datacenter": {
            "description": "US West 1 Datacenter",
            "id": 1,
            "name": "US-West-1",
            "object": "option"
        },
        "name": "lb05",
        "object": "loadbalancer",
        "os": {
            "description": "The F5 Load Balancer.",
            "id": 1,
            "name": "F5",
            "object": "option"
        },
        "persistence": {
            "description": "",
            "id": 1,
            "name": "None",
            "object": "option"
        },
        "realiplist": [
            {
                "ip": {
                    "datacenter": {
                        "description": "US West 1 Datacenter",
                        "id": 1,
                        "name": "US-West-1",
                        "object": "option"
                    },
                    "id": 204896,
                    "ip": "204.113.12.38",
                    "object": "ip",
                    "public": true,
                    "state": {
                        "description": "IP is available to use",
                        "id": 1,
                        "name": "Unassigned",
                        "object": "option"
                    },
                    "subnet": "204.113.12.26/255.255.255.240"
                },
                "object": "ipportpair",
                "port": 80
            },
            {
                "ip": {
                    "datacenter": {
                        "description": "US West 1 Datacenter",
                        "id": 1,
                        "name": "US-West-1",
                        "object": "option"
                    },
                    "id": 204895,
                    "ip": "204.113.12.39",
                    "object": "ip",
                    "public": true,
                    "state": {
                        "description": "IP is available to use",
                        "id": 1,
                        "name": "Unassigned",
                        "object": "option"
                    },
                    "subnet": "204.113.12.26/255.255.255.240"
                },
                "object": "ipportpair",
                "port": 80
            }
        ],
        "state": {
            "description": "Loadbalancer is enabled and on.",
            "id": 1,
            "name": "On",
            "object": "option"
        },
        "type": {
            "description": "",
            "id": 1,
            "name": "Round Robin",
            "object": "option"
        },
        "virtualip": {
            "ip": {
                "datacenter": {
                    "description": "US West 1 Datacenter",
                    "id": 1,
                    "name": "US-West-1",
                    "object": "option"
                },
                "id": 204894,
                "ip": "204.113.12.40",
                "object": "ip",
                "public": true,
                "state": {
                    "description": "IP is reserved or in use",
                    "id": 2,
                    "name": "Assigned",
                    "object": "option"
                },
                "subnet": "204.113.12.26/255.255.255.240"
            },
            "object": "ipportpair",
            "port": 80
        }
    }],
    "method": "/grid/loadbalancer/add",
    "status": "success",
    "summary": {
        "numpages": 0,
        "returned": 1,
        "start": 0,
        "total": 1
    }
}

XML Response

<gogrid>
  <response method="/grid/loadbalancer/add" status="success">
    <summary total="1" start="0" numpages="0" returned="1"/>
    <list>
      <object name="loadbalancer">
        <attribute name="id"></attribute>
        <attribute name="name">lb05</attribute>
        <attribute name="description"></attribute>
        <attribute name="virtualip">
          <object name="ipportpair">
            <attribute name="ip">
              <object name="ip">
                <attribute name="id">204894</attribute>
                <attribute name="ip">204.113.12.40</attribute>
                <attribute name="state">
                  <object name="option">
                    <attribute name="id">2</attribute>
                    <attribute name="name">Assigned</attribute>
                    <attribute name="description">IP is reserved or in use</attribute>
                  </object>
                </attribute>
                <attribute name="subnet">204.113.12.26/255.255.255.240</attribute>
                <attribute name="public">true</attribute>
                <attribute name="datacenter">
                  <object name="option">
                    <attribute name="id">1</attribute>
                    <attribute name="name">US-West-1</attribute>
                    <attribute name="description">US West 1 Datacenter</attribute>
                  </object>
                </attribute>
              </object>
            </attribute>
            <attribute name="port">8080</attribute>
          </object>
        </attribute>
        <attribute name="type">
          <object name="option">
            <attribute name="id">1</attribute>
            <attribute name="name">Round Robin</attribute>
            <attribute name="description"></attribute>
          </object>
        </attribute>
        <attribute name="persistence">
          <object name="option">
            <attribute name="id">1</attribute>
            <attribute name="name">None</attribute>
            <attribute name="description"></attribute>
          </object>
        </attribute>
        <attribute name="realiplist">
          <list>
            <object name="ipportpair">
              <attribute name="ip">
                <object name="ip">
                  <attribute name="id">204896</attribute>
                  <attribute name="ip">204.113.12.38</attribute>
                  <attribute name="state">
                    <object name="option">
                      <attribute name="id">1</attribute>
                      <attribute name="name">Unassigned</attribute>
                      <attribute name="description">IP is available to use</attribute>
                    </object>
                  </attribute>
                  <attribute name="subnet">204.113.12.26/255.255.255.240</attribute>
                  <attribute name="public">true</attribute>
                  <attribute name="datacenter">
                    <object name="option">
                      <attribute name="id">1</attribute>
                      <attribute name="name">US-West-1</attribute>
                      <attribute name="description">US West 1 Datacenter</attribute>
                    </object>
                  </attribute>
                </object>
              </attribute>
              <attribute name="port">8080</attribute>
            </object>
            <object name="ipportpair">
              <attribute name="ip">
                <object name="ip">
                  <attribute name="id">204895</attribute>
                  <attribute name="ip">204.113.12.39</attribute>
                  <attribute name="state">
                    <object name="option">
                      <attribute name="id">1</attribute>
                      <attribute name="name">Unassigned</attribute>
                      <attribute name="description">IP is available to use</attribute>
                    </object>
                  </attribute>
                  <attribute name="subnet">204.113.12.26/255.255.255.240</attribute>
                  <attribute name="public">true</attribute>
                  <attribute name="datacenter">
                    <object name="option">
                      <attribute name="id">1</attribute>
                      <attribute name="name">US-West-1</attribute>
                      <attribute name="description">US West 1 Datacenter</attribute>
                    </object>
                  </attribute>
                </object>
              </attribute>
              <attribute name="port">8080</attribute>
            </object>
          </list>
        </attribute>
        <attribute name="os">
          <object name="option">
            <attribute name="id">1</attribute>
            <attribute name="name">F5</attribute>
            <attribute name="description">The F5 Load Balancer.</attribute>
          </object>
        </attribute>
        <attribute name="state">
          <object name="option">
            <attribute name="id">1</attribute>
            <attribute name="name">On</attribute>
            <attribute name="description">Loadbalancer is enabled and on.</attribute>
          </object>
        </attribute>
        <attribute name="datacenter">
          <object name="option">
            <attribute name="id">1</attribute>
            <attribute name="name">US-West-1</attribute>
            <attribute name="description">US West 1 Datacenter</attribute>
          </object>
        </attribute>
      </object>
    </list>
  </response>
</gogrid>

CSV Response

# SUCCESS, /grid/loadbalancer/add, TOTAL, 1, START, 0, RETURNED, 1
# id,name,description,virtualip.ip.id,virtualip.ip.ip,virtualip.ip.subnet,virtualip.ip.public,virtualip.port,type.id,type.name,type.description,persistence.id,persistence.name,persistence.description,os.id,os.name,os.description,state.id,state.name,state.descriptionrealiplist.1.ip.id,realiplist.1.ip.ip,realiplist.1.ip.subnet,realiplist.1.ip.public,realiplist.1.port
,Test,My Load Balancer,138803,216.121.62.34,216.121.62.32/255.255.255.240,true,2300,1,Round Robin,,1,None,,1,F5,The F5 Load Balancer.,1,On,Loadbalancer is enabled and on.138806,216.121.62.37,216.121.62.32/255.255.255.240,true,2400,

Error Codes

Status Code Description
400 IllegalArgumentException Any problems with input parameters will generate an IllegalArgumentException.
401 Unauthorized This error code will occur when the role tied to the API Key in your request has the wrong Access Controls.
403 Authentication Failed This error code will occur when your request is not properly signed. Make sure your have a valid API key and secret and that you are properly generating a request signature. Ensure that the clock on the computer from which you are making the request is synchronized woth the GoGrid API Server.
404 Not Found This error will occur if you have specified a method that does not exist or any other URL does not exists on the API Server.
500 UnexpectedError These types of errors indicate an internal system problem. Depending on the severity of the error and whether not it is blocking your development, report the error to GoGrid support by emailing the response to apisupport@gogrid.com.
Retrieved from "http://wiki.gogrid.com/wiki/index.php/API:grid.loadbalancer.add"
Personal tools