Supplementary Service Load Balancer v 1.0 2012. 6
Table of Contents 1.Outline... 2 1. 1 Outline of Load balancer... 2 1.1.1 Characteristics of Load balancer... 2 1. 2 API request... 3 1.2.1 Authentication-signed document... 4 1.2.2 Command types... 5 1.2.3 Parameter... 5 1.3 API response... 6 1.3.1 API response formats... 6 1.3.2 ASYNCHRONOUS COMMANDS RESPONSE... 7 1.3.3 ERROR HANDLING... 9 2. Tips on API use (QUICK START)... 11 2.1 Composition of Load balancer on web server... 11 2.2 Change in addition/deletion of target web server of Load balancer... 11 3. Commands... 12 3.1 API for Load balancer management... 12 3.1.1 CREATELOADBALANCER... 12 3.1.2 DELETELOADBALANCER... 13 3.1.3 UPDATELOADBALANCER... 14 3.1.4 LISTLOADBALANCERS... 15 3.2 SERVICE RESOURCE MANAGEMENET API... 15 3.2.1 ADDLOADBALANCERWEBSERVER... 16 3.2.2 REMOVELOADBALANCERWEBSERVER... 17 3.2.3 LISTLOADBALANCERWEBSERVERS... 18
Revision History Version Revision details Reporting date 1.0 Official distribution version 2012. 6. 20.
1. Outline This document presents Load balancer API standard. It includes APIrequest/response message, explanation on public commands and examples. Users can create and manage Load balancer resource by utilizing Load balancer API. 1. 1 Outline of Load balancer It plays a role of dispersing a client s operation requests to multiple servers and there are two types of Load balancer in kt ucloud: basic Load balancer (free of charge) and supplementary Load balancer. (charged). Basic Load balancer : Free-of-charge Load balancer provided to virtual router granted on each customer Supplementary Load balancer : Charged Load balancer provided for a customer who wants better performance * Hereafter Load balancer refers to supplementary one. 1.1.1 Characteristics of Load balancer Items Security aspects Scale aspects Service aspects Performance aspects Convenience aspects Description Outstanding performance in defending SynAttack compared to the basic one Basic Load balancer suitable for middle/small-sized customers, Supplementary one suitable for middle/large-sized customer requiring high performance Basic service only providing TCP load balancing, supplementary Load balancer providing both TCP and UDP load balancing Web server Keepalive should be set as On to realize innovative web server load reduction using TCP Offload and to utilize this function. Unable to check Client IP in basic Load balancer, Providing Client IP using Http header in supplementary Load balancer (limited on web service)
1. 2 API request API request message is composed as below. (1)API URL + (2) Request command + (3) Command parameter + (4) Response format + (5)API Key + (6) Authentication-signed document Values and description of each field are shown in the table below. Field Description (1) API URL - ucloud server API URL - Value : https://api.ucloudbiz.olleh.com/en-us/loadbalancer/v1/client/api? (2) Request command - Command for requesting computing resources (creation, deletion, checking and other commands) - Syntax : command=command name, [see Chapter 3 for details] (3) Command parameter - Parameter related to request command - Syntax : [&field=value]*, [see Chapter 3 for details] (4) Response format - It supports XML and JSON response formats. [Optional field] - Syntax : &response=[xml json], xml as default. (5) API Key - API Key by user accounts (check on ucloudbiz site) (6) Authentication-signed - Syntax : &apikey=apikey - Authentication-signed document for checking authority for executing API request message document - Syntax : &signature= Authentication-signed document * API Key and Secret Key Checking (1) Login to https://ucloudbiz.olleh.com/en-us (2) Select cloud console. (3) Select ucloud server tab > Check API Key menu.
API Request Sample https://api.ucloudbiz.olleh.com/server/v1/client/api?command=listvirtualmachines&name=vm_33111&s tate=running&response=xml&apikey=mivr6x&signature=zc1u%2b03yj592lz%2bgma3ac%2fqthws% 3D Analysis on API Request Sample (1) https://api.ucloudbiz.olleh.com/server/v1/client/api? API URL (2) command=listvirtualmachines Request command (3) &name=vm_33111&state=running Command parameter (4) &response=xml Response format (5) &apikey=mivr6x API Key (6) &signature=zc1u%2b03yj592lz%2bgma3ac%2fqthws%3d Authentication-signed document 1.2.1 Authentication-signed document Authentication is executed by API Key and authentication-signed document on ucloud server. Authentication-signed document is created by using Secret Ket issued by users, HMAC SHA-1 algorithm and command string (number 2 to 5). [Creation of Authentication-signed document] Example for Secret Key : keokzhd Example for command string :_command=listvirtualmachines&name=vm_33111&state=running &response=xml&apikey=mivr6x (1) Encode each field and values of command string. URL encoding : Make blanks encoded as %20. [No + ] API request message : API_URL + String encoded with URL + &signature=authentication-signed document (2) Lowercase command string. (3) Set field names in alphabetical order. apikey=mivr6x&command=listvirtualmachines&name=vm_33111&response=xml&state=ru nning (4) Encode command string by using Secret Key and HMAC SHA 1 hash algorithm. The following is java sample code. Mac mac = Mac.getInstance ( "HmacSHA1" ); SecretKeySpec keyspec = new SecretKeySpec(secretkey.getBytes(), "HmacSHA1"); mac.init( keyspec ); mac.update ( commandstring.getbytes() ); byte[] encryptedbytes = mac.dofinal(); Sample_URL http://docs.cloud.com/cloudstack_documentation/developer's_guide%3a_cloudstack#si gning_api_requests (5) Lastly, after Base64 encoding on obtained byte arrangement, execute URL encoding once more with UTF - 8. Created authentication-signed document and API request message are as follows. Authentication-signed document : ZC1u%2B03yj592LZ%2BgmA3ac%2FQThws%3D API request message :
https://api.ucloudbiz.olleh.com/server/v1/client/api?command=listvirtualmachines&name=vm_33111&st ate=running&response=xml&apikey=mivr6x&signautre=zc1u%2b03yj592lz%2bgma3ac%2fqthws %3D 1.2.2 Command types It executes commands of long-time implementation such as VM / DISK volume creation with asynchronous commands and others with synchronous ones. It is classified by marking (A) on asynchronous commands in Chapter 3. Explanation on commands and command parameter which do not exist in CloudStack is marked with (*). 1.2.3 Parameter As aforementioned, parameter executed in API request exists in pairs (field=value) and the following is rules of using upper and lower case. field : Not case-sensitive, case- sensitive only on command. value : Case-sensitive.
1.3 API response It describes procedures for API response checking according to explanation on supported response format and command types (synchronous and asynchronous commands). 1.3.1 API response format xml and json are supported as API response formats and the format can be designated as response=xml in API request. When information on the relevant field does not exist in results of command execution, defined field and values may not be displayed. The following is an example for response format. Response Sample Format xml <listipaddressesresponse> <allocatedipaddress> <ipaddress>192.168.10.141</ipaddress> <allocated>2009-09-18t13:16:10-0700</allocated> <zoneid>4</zoneid> <zonename>wc</zonename> <issourcenat>true</issourcenat> </allocatedipaddress> </listipaddressesresponse> json { "listipaddressesresponse" : { "allocatedipaddress" : [ { "ipaddress" : "192.168.10.141", "allocated" : "2009-09-18T13:16:10-0700", "zoneid" : "4", "zonename" : "WC", "issourcenat" : "true" } ] } }
1.3.2 Asynchronous Commands Response It executes commands of long-time implementation such as VM / DISK volume creation with asynchronous commands and others with synchronous ones. Procedures for checking API response on synchronous and asynchronous commands differ as in the following. API Commands Procedures for checking response Synchronous commands (1) Command execution by API request (2) Checking results of command execution Asynchronous commands (1) Command execution by API request (2) Checking return of jobid (operation ID) (3) Execution of command queryasyncjobresult (conveying by jobid factors) (4) Checking command execution progress (jobstatus) 0:in progress, 1:success, 2:failure [Result shown on jobresult] ** Check command results by regularly performing (3) and (4) until jobstatus becomes 1 or 2. The following is an example of results from asynchronous commands. Checking Sample asynchronous commands (1) API request (Command execution) https://api.ucloudbiz.olleh.com/server/v1/client/api? command=listvirtualmachines &name=vm_33111&state=running&response=xml &apikey=mivr6x &signature=zc1u%2b03yj592lz%2bgma3ac%2fqthws%3d (2)Return of command response <deployvirtualmachineresponse> <jobid> 37120 </ jobid> <id> 100 </ id> </ deployvirtualmachineresponse> (3) Execution of queryasyncjobresult https://api.ucloudbiz.olleh.com/server/v1/client/api? command=queryasyncjobresult&jobid=37120 &apikey=h6kxwcratdqfwf3xa &signature=z5f11yym6yzqomy9b%2f4%3d
(4) jobstatus = 0 [in progress] <queryasyncjobresult> <jobid>37120</jobid> <jobstatus>0</jobstatus> <jobprocstatus>1</jobprocstatus> <queryasyncjobresult> (4) jobstatus = 1 [success] <queryasyncjobresultresponse cloud-stack-version="2.2.1.66"> <jobid>37120</jobid> <jobstatus>1</jobstatus> <jobprocstatus>0</jobprocstatus> <jobresultcode>0</jobresultcode> <jobresulttype>object</jobresulttype> <jobresult> <virtualmachine> <id>100</id> <state>running</state>.. </virtualmachine> </jobresult> </queryasyncjobresultresponse> (4) jobstatus = 2 [failure] <queryasyncjobresult> <jobid>37120</jobid> <jobstatus>2</jobstatus> <jobprocstatus>0</jobprocstatus> <jobresultcode>551</jobresultcode> <jobresulttype>text</jobresulttype> <jobresult> Unable to deploy virtual machine id = 10 due to not enough capacity </jobresult> <queryasyncjobresult>
1.3.3 Error Handling Error information is returned as a response when API request goes wrong or errors occur in processing. Error information consists of error code <errorcode> and error text <errortext>. <?xml version="1.0" encoding="utf-8"?> <listvirtualmachinesresponse cloud-stack-version="2.2.13.20111117130644"> <errorcode>401</errorcode> <errortext>unable to verify user credentials and/or request signature</errortext> </listvirtualmachinesresponse> Error codes currently supported are as follows. Error Code Description 200 PUBLIC_PORT_IN_USE_ERROR 210 RESOURCE_NOT_FOUND_ERROR 401 AUTHENTICATION_ERROR 406 MALICIOUS_CODE_INJECTION 430 MALFORMED_PARAMETER_ERROR 431 PARAM_ERROR 432 UNSUPPORTED_ACTION_ERROR 433 PAGE_LIMIT_EXCEED 503 EXCESSIVE_TRAFFIC_ERROR 504 INTERNAL_ERROR (TIMEOUT) 530 INTERNAL_ERROR 531 ACCOUNT_ERROR 532 ACCOUNT_RESOURCE_LIMIT_ERROR 533 INSUFFICIENT_CAPACITY_ERROR 534 RESOURCE_UNAVAILABLE_ERROR 535 RESOURCE_ALLOCATION_ERROR 536 RESOURCE_IN_USE_ERROR 537 NETWORK_RULE_CONFLICT_ERROR [Example 1] <?xml version="1.0" encoding="iso-8859-1"?> <deployvirtualmachineresponse cloud-stack-version="2.2.13.20111117130644"> <errorcode>431</errorcode> <errortext>unable to find zone by id=2111</errortext> </deployvirtualmachineresponse> [Example 2] <?xml version="1.0" encoding="iso-8859-1"?> <errorresponse cloud-stack-version="2.2.13.20111117130644"> <errorcode>432</errorcode> <errortext>the given command does not exist</errortext> </errorresponse>
2. Tips on API use (Quick Start) This chapter describes a few tips for utilizing Load balancer API. 2.1 Composition of Load balancer on web server For composing Load balancer on two web servers created by ucloud server, perform the following procedures. (1) Create Load balancer with command of createloadbalancer (see 3.1.1) (2) Register web server on Load balancer with command of addloadbalancerwebserver. (see 2.2.1) (3) Conduct operation in (2) as many times as the number of web server. (see 2.2.1) (4) Check normality of registration with command of listloadbalancerwebservers. (see 2.2.3) 2.2 Change in addition/deletion of target web server of Load balancer For adding/deleting web server on an existing Load balancer, perform the following procedures. (1) Check information on target Load balancer with command of listloadbalancers (see 2.1.4) (2) Check web server registered on Load balancer with command of listloadbalancerwebservers (see 2.2.3) (3) Delete the relevant web server with command of removeloadbalancerwebserver (see 2.2.2) (4) Register a new web server to be added on Load balancer with command of addloadbalancerwebserver. (see 2.2.1) (5) Check normality of registration with command of listloadbalancerwebservers.(see 2.2.3)
3. Commands This chapter describes Load balancer commands, information on command parameter and response to commands by grouping depending on functions for better understanding. ${API_URL} variable used in the example is API URL for Load balancer (https://api.ucloudbiz.olleh.com/loadbalancer/v1/client/api?). 3.1 API for Load balancer management It describes commands related to creation and deletion of Load balancer. 3.1.1 createloadbalancer It is a command for creating Load balancer provided as a supplementary service of ucloud. Price for the product is not provided in API but in uloudbiz site. Command parameter Parameter Name Description Required name Name of Load balancer TRUE bandwidth Maximum bandwidth of Load balancer (100 300 500) TRUE loadbalanceroption Options for load balancing (roundrobin leastconnection srciphash srciphashport) TRUE serviceport Service port TRUE infourl URL for information in exceeding bandwidth TRUE Items in response results Response Name loadbalancerid serviceip serviceport name Description LoadBalancer id Service ip of Load balancer Service port of Load balancer Name of Load balancer bandwidth Maximum bandwidth of Load balancer (100 300 500) loadbalanceroption Options for load balancing (roundrobin leastconnection srciphash srciphashport) serviceport infourl Service port URL for information in exceeding bandwidth Example Sample 1 Request for creation of Load balancer ${API_URL}command=createLoadBalancer &name=lb1&bandwidth=100&loadbalanceroption=roundrobin&serviceport=80&infourl=http://www.lb.com /error.html&apikey=h6kxwcratdqfwf3xa&signature=bfytuy4bdocpk%3d Sample 2 Response to creation of Load balancer
{ "createloadbalancerresponse": { "loadbalancerid": "109", "serviceip": "14.63.252.225", "serviceport": "80", "name": "lbtest01", "bandwidth": "100", "loadbalanceroption": "roundrobin", "infourl": "http://www.lbtest.com/error.html" } } 3.1.2 deleteloadbalancer It makes a created Load balancer deleted. Command parameter Parameter Name Description Required loadbalancerid LoadBalancer id TRUE Items in response results Response Name success displaytext Description Success or Failure (true false) Detailed results of processing Example Sample 1 Request for deletion of Load balancer ${API_URL}command=deleteLoadBalancer&loadbalancerid=100 &apikey=h6kxwcratdqfwf3xa&signature=bfytuy4bdocpk%3d Sample 2 Response to deletion of Load balancer { "deleteloadbalancerresponse": { "success": true, "displaytext": "109 loadbalancer is deleted." } } 3.1.3 updateloadbalancer It makes changes on a created Load balancer. Command parameter : None Parameter Name Description Required loadbalancerid LoadBalancer id TRUE loadbalanceroption Options for Load balancing (roundrobin leastconnection srciphash srciphashport) TRUE infourl URL for information in exceeding bandwidth FALSE Items in response results : identical with those of createloadbalancer Example
Sample 1 updateloadbalancer Request ${API_URL}command=updateLoadBalancer&loadbalancerid=100&loadbalanceroption=srciphash&apiK ey=h6kxwcratdqfwf3xa&signature=bfytuy4bdocpk%3d Sample 2 updateloadbalancer Response { "createloadbalancerresponse": { "loadbalancerid": "109", "serviceip": "14.63.252.225", "serviceport": "80", "name": "lbtest01", "bandwidth": "100", "loadbalanceroption": "leastconnection", "infourl": "www.lbtest01.com/error.html" } } 3.1.4 listloadbalancers It checks the list of created Load balancer. Command parameter : None Parameter Name Description Required loadbalancerid LoadBalancer id FALSE name Name of Load balancer FALSE Items in response results : identical with those of createloadbalancer Example Sample 1 listloadbalancer Request ${API_URL}command=listLoadBalancers& id=100 &apikey=h6kxwcratdqfwf3xa&signature=bfytuy4bdocpk%3d Sample 2 listloadbalancer Response {"listloadbalancerresponse":{ "count":1,"loadbalancer":[ {"bandwidth":100, "infourl":"www.lbtest.com/error.html", "loadbalancerid":110, "loadbalanceroption":"", "name":"lbtest01", "serviceip":"14.63.252.223", "serviceport":"80"} ]}} 3.2 API for management on service resource It describes commands on addition/deletion of web server to be a target of Load balancer. 3.2.1 addloadbalancerwebserver It describes commands on addition of web server. Command parameter Parameter Name Description Required
loadbalancerid LoadBalancer id TRUE virtualmachineid Web server id TRUE ipaddressid ID on public ip to be used by web server TRUE publicport Public port to be used in virtual router port forwarding TRUE privateport Service port of web server TRUE Items in response results Response Name serviceid loadbalancerid virtualmachineid ipaddressid publicport privateport Description Service id LoadBalancer id Web server id ID on public ip to be used by web server Public port to be used in virtual router port forwarding Service port on web server Example Sample 1 addloadbalancerwebserver Request ${API_URL}command=addLoadBalancerWebServer&loadbalancerid=100&virtaulmachineid=10 &ipaddressid=5&publicport=100&privateport=80 &apikey=h6kxwcratdqfwf3xa&signature=bfytuy4bdocpk%3d Sample 2 addloadbalancerwebserver Response { "addloadbalancerwebserverresponse": { "serviceid": 10, "loadbalancerid": 100, "virtualmachineid": 10, "ipaddressid": 5, "publicport": 100, "privateport": 80 } } Reference Check virtualmachine id request/response sample https://api.ucloudbiz.olleh.com/server/v1/client/api?command=listvirtualmachines &apikey=hml3yalu4r&sign ature=9v82nnfrhwwto1ohmmgq0%2ffmg38%3d <?xml version="1.0" encoding="iso-8859-1"?> <listvirtualmachinesresponse cloud-stack-version="2.2.13.20111117130644"> <count>1</count> <virtualmachine> <id>31626</id> <name>i-172-31626-vm</name> <displayname>i-172-31626-vm</displayname> <account>test_m123456_s1234</account> <domainid>4</domainid> <domain>epc_user</domain> The rest is omitted.
Reference Method for checing ipaddress id request/response sample https://api.ucloudbiz.olleh.com/server/v1/client/api? command=listpublicipaddresses&apikey=hml3yalu4r&signature=c6tvga TFxQDYpcEpxONeTaU4PJo%3D <xml version="1.0" encoding="iso-8859-1"?> <listpublicipaddressesresponse cloud-stack-version="2.2.13.20111117130644"> <count>1</count> <publicipaddress> <id>2779</id> <ipaddress>14.63.219.129</ipaddress> <allocated>2011-12-29t16:05:25+0900</allocated> The rest is omitted. 3.2.2 removeloadbalancerwebserver It describes commands on deletion of information on web server to be a target of security service. Command parameter Parameter Name Description Required serviceid Service id TRUE Items in response results Response Name success displaytext Description Success or Failure (true false) Detailed results of processing Example Sample 1 removeloadbalancerwebserver Request ${API_URL}command=removeLoadBalancerWebServer&serviced=20 &apikey=h6kxwcratdqfwf3xa&signature=bfytuy4bdocpk%3d Sample 2 removeloadbalancerwebserver Response { "removeloadbalancerwebserverresponse": { "success": true, "displaytext": "100 loadbalancer webserver is deleted." } } 3.2.3 listloadbalancerwebservers It checks information on web server registered on Load balancer. Command parameter Parameter Name Description Required
loadbalancerid LoadBalancer id TRUE Items in response results Response Name loadbalancerid serviceid virtualmachineid ipaddressid publicport privateport currentsession status Description LoadBalancer id Service id Web server id ID on public ip to be used by web server Public port to be used in virtual router port forwarding Service port on web server The number of current sessions on web server State of web server Example Sample 1 listloadbalancerwebservers Request ${API_URL}command= listloadbalancerwebservers &loadbalancerid=100&apikey=h6kxwcratdqfwf3xa&signature=bfytuy4bdocpk%3d Sample 2 listloadbalancerwebservers Response { "listloadbalancerwebserversresponse": { "loadbalancerid": 100, "serviceid": 10 } }