v2.3.2 API Guide A comprehensive description of API requests with code and output samples. Document version Document release date 1.7 21st November 2012 document revisions 1 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 Contents 1. 2. 3. Introduction ................................................................................................................. 15 1.1 Documentation conventions....................................................................................................... 16 1.2 FAQs ............................................................................................................................................ 16 Roles ............................................................................................................................ 18 2.1 Get the list of roles...................................................................................................................... 18 2.2 Get role details ............................................................................................................................ 19 2.3 Edit a role .................................................................................................................................... 19 2.4 Add a new role ............................................................................................................................ 20 2.5 Delete a role ................................................................................................................................ 20 2.6 Edit a user’s role assignment ...................................................................................................... 21 2.7 Get the list of all permissions...................................................................................................... 21 Billing plans .................................................................................................................. 23 3.1 Get the list of billing plans .......................................................................................................... 24 3.2 Add a billing plan ......................................................................................................................... 25 3.3 Get billing plan details ................................................................................................................ 26 3.4 Edit a billing plan ......................................................................................................................... 26 3.5 Delete a billing plan .................................................................................................................... 27 3.6 View base resources for a billing plan ........................................................................................ 27 3.7 Add base resource limits to a billing plan ................................................................................... 28 3.7.1 Add Virtual Machines base resource limits ...........................................................................................28 3.7.2 Add other base resource limits ..............................................................................................................29 3.7.3 Add limits for template groups and hypervisor zones ...........................................................................30 3.7.4 Add limits for data store zones ..............................................................................................................31 3.7.5 Add limits for network zones .................................................................................................................32 3.7.6 Add limits for edge groups .....................................................................................................................33 3.7.7 Add limits for backup server zones ........................................................................................................34 3.8 Edit base resources of a billing plan............................................................................................ 36 3.9 Delete a base resource from a billing plan ................................................................................. 36 3.10 Get CPUs details .......................................................................................................................... 36 3.11 Get CPU Priority details............................................................................................................... 38 2 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 4. 5. 3.12 Get memory details .................................................................................................................... 39 3.13 Get disk size details ..................................................................................................................... 40 3.14 Get IP address details.................................................................................................................. 41 3.15 Get VM monit details .................................................................................................................. 43 3.16 Get virtual machine details ......................................................................................................... 44 3.17 Get template details ................................................................................................................... 45 3.18 Get template & backup storage details ...................................................................................... 46 3.19 Get backup details ...................................................................................................................... 47 3.20 Get template groups details ....................................................................................................... 48 3.21 Get hypervisor zones details ....................................................................................................... 49 3.22 Get data store zone details ......................................................................................................... 50 3.23 Get network zone details ............................................................................................................ 52 3.24 Get edge group details ................................................................................................................ 54 3.25 Get backup server zone details ................................................................................................... 55 Currencies .................................................................................................................... 57 4.1 Get the list of currencies ............................................................................................................. 57 4.2 Get currency details .................................................................................................................... 58 4.3 Edit currencies............................................................................................................................. 59 4.4 Add a currency ............................................................................................................................ 60 4.5 Delete a currency ........................................................................................................................ 61 Users ............................................................................................................................ 62 5.1 Get the list of users ..................................................................................................................... 62 5.2 Get user details ........................................................................................................................... 65 5.3 Create a user ............................................................................................................................... 65 5.4 Edit a user ................................................................................................................................... 66 5.5 Generate API key......................................................................................................................... 67 5.6 Suspend a user ............................................................................................................................ 69 5.7 Activate a user ............................................................................................................................ 69 5.8 Delete a user ............................................................................................................................... 69 5.9 View user’s statistics ................................................................................................................... 70 5.10 View user's statistics for a particular period ............................................................................... 71 3 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 6. 7. 8. 9. 5.11 View billing statistics for a user .................................................................................................. 74 5.12 See user’s monthly bills .............................................................................................................. 74 5.13 See user’s payments ................................................................................................................... 75 5.14 Add a payment ............................................................................................................................ 75 5.15 Edit a payment ............................................................................................................................ 76 5.16 Delete a payment ........................................................................................................................ 76 5.17 See VMs of a particular user ....................................................................................................... 77 5.18 See user limits ............................................................................................................................. 77 5.19 Hypervisors used by a users’ VMs............................................................................................... 78 5.20 User’s data store zones ............................................................................................................... 79 5.21 User’s network zones .................................................................................................................. 79 User additional fields .................................................................................................... 80 6.1 Get the list of additional fields .................................................................................................... 80 6.2 See an additional field details ..................................................................................................... 80 6.3 Create new additional field ......................................................................................................... 81 6.4 Edit additional field ..................................................................................................................... 82 6.5 Delete additional field................................................................................................................. 82 6.6 Search a user by additional field parameter ............................................................................... 82 User groups .................................................................................................................. 84 7.1 Get the list of user groups........................................................................................................... 84 7.2 Get the user group details .......................................................................................................... 84 7.3 Create a user group..................................................................................................................... 84 7.4 Edit a user group ......................................................................................................................... 85 7.5 Delete a user group..................................................................................................................... 85 Whitelist IPs ................................................................................................................. 87 8.1 Get the list of whitelist IPs .......................................................................................................... 87 8.2 Get whitelist IPs details ............................................................................................................... 87 8.3 Edit a whitelisted IP..................................................................................................................... 88 8.4 Add a whitelisted IP .................................................................................................................... 88 8.5 Delete a whitelisted IP ................................................................................................................ 89 Firewall Rules for VMs .................................................................................................. 90 4 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 9.1 Get the list of firewall rules......................................................................................................... 90 9.2 Edit a firewall rule ....................................................................................................................... 91 9.3 Add a firewall rule ....................................................................................................................... 91 9.4 Apply a firewall rule .................................................................................................................... 92 9.5 Delete a firewall rule ................................................................................................................... 93 9.6 Set default firewall rules ............................................................................................................. 93 10. Data store zones ....................................................................................................... 95 10.1 Get the list of data store zones ................................................................................................... 95 10.2 Add a data store zone ................................................................................................................. 95 10.3 Get data store zone details ......................................................................................................... 96 10.4 Edit a data store zone ................................................................................................................. 96 10.5 Delete a data store zone ............................................................................................................. 97 10.6 Get the list of data stores attached to a data store zone ........................................................... 97 10.7 Attach a data store to a data store zone .................................................................................... 99 10.8 Detach a data store from a data store zone ............................................................................... 99 11. Network zones ........................................................................................................ 100 11.1 Get the list of network zones .................................................................................................... 100 11.2 Add a network zone .................................................................................................................. 100 11.3 Get network zone details .......................................................................................................... 101 11.4 Edit a network zone .................................................................................................................. 101 11.5 Delete a network zone .............................................................................................................. 102 11.6 Attach a network to a network zone ........................................................................................ 102 11.7 Remove a network from a network zone ................................................................................. 102 12. Hypervisor zones ..................................................................................................... 104 12.1 Get the list of hypervisor zones ................................................................................................ 104 12.2 Add a hypervisor zone .............................................................................................................. 104 12.3 Get hypervisor zone details ...................................................................................................... 105 12.4 Edit a hypervisor zone ............................................................................................................... 105 12.5 Delete a hypervisor zone .......................................................................................................... 106 12.6 Get the list of hypervisors attached to hypervisor zone........................................................... 106 12.7 Attach/remove a hypervisor from a hypervisor zone ............................................................... 107 5 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 12.8 Get the list of data store joins attached to a hypervisor zone ................................................. 107 12.9 Add a data store join to a hypervisor zone ............................................................................... 107 12.10 Remove a data store join from a hypervisor zone ................................................................ 108 12.11 Get the list of network joins attached to this hypervisor zone ............................................ 109 12.12 Attach a new network join to a hypervisor zone .................................................................. 109 12.13 Remove a network join from a hypervisor zone ................................................................... 110 13. Backup server zones ................................................................................................ 111 13.1 Get the list of backup server zones........................................................................................... 111 13.2 Get backup server zone details ................................................................................................. 111 13.3 Create a backup server zone ..................................................................................................... 112 13.4 Edit a backup server zone ......................................................................................................... 112 13.5 Delete a backup server zone ..................................................................................................... 113 13.6 Get the list of servers assigned to backup server zone ............................................................ 113 13.7 Assign backup server to backup server zone ............................................................................ 114 13.8 Unasign backup server from backup server zone ..................................................................... 115 14. Hypervisors ............................................................................................................. 116 14.1 Get the list of hypervisors ......................................................................................................... 116 14.2 Get the list of unassigned hypervisors ...................................................................................... 117 14.3 Get hypervisor details ............................................................................................................... 118 14.4 Add a new hypervisor ............................................................................................................... 120 14.5 Edit a hypervisor ....................................................................................................................... 121 14.6 Reboot a hypervisor .................................................................................................................. 121 14.7 Get the list of VMs running on the hypervisor ......................................................................... 122 14.8 Get the list of data store joins attached to the hypervisor....................................................... 122 14.9 Add a data store join to the hypervisor .................................................................................... 123 14.10 Remove a data store join from the hypervisor ..................................................................... 123 14.11 Get the list of network joins of the hypervisor ..................................................................... 124 14.12 Add a network join to the hypervisor ................................................................................... 124 14.13 Remove a network join from the hypervisor ........................................................................ 125 14.14 Delete a hypervisor ............................................................................................................... 125 15. Networks ................................................................................................................ 127 6 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 15.1 Get the list of networks ............................................................................................................ 127 15.2 Get network details................................................................................................................... 127 15.3 Edit a network ........................................................................................................................... 128 15.4 Rebuild VM network ................................................................................................................. 129 15.5 Add a network ........................................................................................................................... 129 15.6 Delete a network....................................................................................................................... 130 16. Network Interfaces.................................................................................................. 131 16.1 Get the list of VM network interfaces ...................................................................................... 131 16.2 Get network interface details ................................................................................................... 132 16.3 Edit a network interface ........................................................................................................... 132 16.4 Add a network interface to a VM.............................................................................................. 132 16.5 Delete a network interface ....................................................................................................... 133 17. IP Addresses............................................................................................................ 135 17.1 Get the list of network IP addresses ......................................................................................... 135 17.2 Edit an IP address ...................................................................................................................... 136 17.3 Create an IP address record ...................................................................................................... 136 17.4 Delete an IP address ................................................................................................................. 137 18. IP address joins ....................................................................................................... 139 18.1 Get the list of IP address joins................................................................................................... 139 18.2 Assign an IP address join to a VM ............................................................................................. 140 18.3 Delete an IP address join........................................................................................................... 140 19. Data stores.............................................................................................................. 142 19.1 Get the list of data stores.......................................................................................................... 142 19.2 Get data store details................................................................................................................ 142 19.3 Add a new data store ................................................................................................................ 143 19.4 Edit a data store ........................................................................................................................ 144 19.5 Delete a data store.................................................................................................................... 145 20. Backup servers ........................................................................................................ 146 20.1 Get the list of backup servers ................................................................................................... 146 20.2 Get backup server details ......................................................................................................... 147 20.3 Add new backup server............................................................................................................. 149 7 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 20.4 Edit a backup server .................................................................................................................. 150 20.5 Delete a backup server ............................................................................................................. 150 20.6 Search backups ......................................................................................................................... 151 21. Disks ....................................................................................................................... 154 21.1 Get the list of disks.................................................................................................................... 154 21.2 Get the list of VM disks ............................................................................................................. 155 21.3 Add a new disk .......................................................................................................................... 155 21.4 Edit a disk .................................................................................................................................. 156 21.5 Migrate a disk ........................................................................................................................... 156 21.6 Delete a disk .............................................................................................................................. 157 21.7 View disk IOPS ........................................................................................................................... 158 21.8 Build a disk ................................................................................................................................ 158 21.9 Unlock a disk ............................................................................................................................. 159 21.10 Enable autobackups for a disk .............................................................................................. 159 21.11 Disable autobackups for a disk ............................................................................................. 160 21.12 Get the list of schedules for a disk ........................................................................................ 160 21.13 Add a schedule to a disk ....................................................................................................... 161 21.14 Get the list of backups available for a disk ........................................................................... 162 22. Templates ............................................................................................................... 164 22.1 Get the list of system templates ............................................................................................... 164 22.2 Get the list of custom templates (user templates) ................................................................... 165 22.3 Get the template details ........................................................................................................... 165 22.4 Make a template public ............................................................................................................ 167 22.5 Delete a template ..................................................................................................................... 167 23. Template groups ..................................................................................................... 168 23.1 See the list of template groups ................................................................................................. 168 23.2 Get template group details ....................................................................................................... 168 23.3 Edit a template group ............................................................................................................... 169 23.4 Add a template group ............................................................................................................... 170 23.5 Delete a template group ........................................................................................................... 171 23.6 Get the list of templates attached to a group .......................................................................... 171 8 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 23.7 Attach a template to a group .................................................................................................... 172 23.8 Detach a template from a group .............................................................................................. 172 23.9 Change price for a template in the group ................................................................................. 173 24. Software Licenses.................................................................................................... 174 24.1 Get the list of software licenses................................................................................................ 174 24.2 Get software license details ...................................................................................................... 175 24.3 Edit a software license .............................................................................................................. 176 24.4 Add a software license .............................................................................................................. 176 24.5 Delete a software license .......................................................................................................... 177 25. Resolvers ................................................................................................................ 178 25.1 Get the list of resolvers ............................................................................................................. 178 25.2 Get resolver details ................................................................................................................... 178 25.3 Edit a resolver ........................................................................................................................... 179 25.4 Add a resolver ........................................................................................................................... 179 25.5 Delete a resolver ....................................................................................................................... 180 26. Virtual Machines ..................................................................................................... 181 26.1 Get the list of VMs .................................................................................................................... 181 26.2 Get VM details .......................................................................................................................... 184 26.3 Create a VM .............................................................................................................................. 184 26.4 Build a VM ................................................................................................................................. 186 26.5 Edit a VM ................................................................................................................................... 187 26.6 Change a VM owner .................................................................................................................. 188 26.7 Reset root password ................................................................................................................. 188 26.8 Set SSH keys .............................................................................................................................. 189 26.9 Migrate a VM ............................................................................................................................ 189 26.10 Set VIP status ........................................................................................................................ 190 26.11 Destroy a VM......................................................................................................................... 190 26.12 Resize a VM ........................................................................................................................... 190 26.13 Suspend a VM ....................................................................................................................... 191 26.14 Unsuspend a VM ................................................................................................................... 192 26.15 Unlock a VM .......................................................................................................................... 192 9 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 26.16 Start up a VM ........................................................................................................................ 192 26.17 Shut down a VM .................................................................................................................... 193 26.18 Stop a VM .............................................................................................................................. 193 26.19 Reboot a VM ......................................................................................................................... 193 26.20 Reboot in recovery ................................................................................................................ 194 26.21 Segregate a VM ..................................................................................................................... 194 26.22 Open a VM console ............................................................................................................... 195 26.23 Billing statistics for a VM ....................................................................................................... 195 27. VM Autoscaling ....................................................................................................... 198 27.1 Get the list of autoscaling rules for a VM ................................................................................. 198 27.2 Create autoscaling rule for VM ................................................................................................. 199 27.3 Edit autoscaling rule for a VM................................................................................................... 200 27.4 Delete autoscaling rules ............................................................................................................ 200 28. Load Balancers ........................................................................................................ 201 28.1 Get the list of load balancing clusters ....................................................................................... 201 28.2 Get load balancing cluster details ............................................................................................. 205 28.3 Edit load balancing cluster details ............................................................................................ 206 28.4 Add a load balancing cluster ..................................................................................................... 207 28.5 Add nodes to cluster type ......................................................................................................... 210 28.6 Remove nodes from cluster type .............................................................................................. 211 28.7 Configure autoscaling type ....................................................................................................... 211 28.8 Delete a load balancing cluster ................................................................................................. 213 28.9 Configure load balancing cluster ports ..................................................................................... 213 28.10 Get the list of load balancers ................................................................................................ 214 28.11 Get load balancer details ...................................................................................................... 216 28.12 Edit a load balancer............................................................................................................... 217 28.13 Start up a load balancer ........................................................................................................ 218 28.14 Stop a load balancer.............................................................................................................. 218 28.15 Shut down a load balancer.................................................................................................... 218 28.16 Unlock a load balancer .......................................................................................................... 219 28.17 Rebuild a load balancer......................................................................................................... 219 10 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 28.18 Suspend a load balancer ....................................................................................................... 219 28.19 View load balancer billing statistics ...................................................................................... 220 29. CDN Edge Servers .................................................................................................... 224 29.1 View edge servers ..................................................................................................................... 224 29.2 View edge server details ........................................................................................................... 226 29.3 Create edge server .................................................................................................................... 226 29.4 Edit edge server ........................................................................................................................ 228 29.5 Reboot edge server ................................................................................................................... 228 29.6 Reboot in recovery .................................................................................................................... 229 29.7 Startup edge server................................................................................................................... 229 29.8 Shut down edge Server ............................................................................................................. 229 29.9 Stop edge server ....................................................................................................................... 230 29.10 Rebuild edge server .............................................................................................................. 230 29.11 Suspend/unsuspend edge server .......................................................................................... 231 29.12 Rerun edge creation scripts .................................................................................................. 231 29.13 Unlock edge server................................................................................................................ 232 29.14 Delete edge server ................................................................................................................ 232 29.15 Migrate edge server .............................................................................................................. 232 29.16 Open the server console ....................................................................................................... 233 29.17 Segregate edge server........................................................................................................... 233 29.18 Reset root password ............................................................................................................. 234 29.19 Change edge server owner ................................................................................................... 234 29.20 Set VIP status ........................................................................................................................ 235 29.21 Edit admin note ..................................................................................................................... 235 29.22 CDN edge server disks ........................................................................................................... 236 29.23 CDN edge server backups ..................................................................................................... 236 29.24 CDN edge server network interfaces .................................................................................... 237 29.25 IP address joins ..................................................................................................................... 237 29.26 Rebuild Network for edge server .......................................................................................... 238 29.27 Firewall rules for CDN edge servers ...................................................................................... 238 29.28 Billing statistics for CDN edge server .................................................................................... 239 11 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 30. CDN Resources ........................................................................................................ 243 30.1 Enable CDN ............................................................................................................................... 243 30.2 View the list of CDN resources.................................................................................................. 243 30.3 View CDN resource basic details............................................................................................... 244 30.4 View CDN resource advanced details ....................................................................................... 245 30.5 View the list of available edge groups ...................................................................................... 246 30.6 Create CDN Resource ................................................................................................................ 248 30.7 Create CDN Resource with advanced settings .......................................................................... 248 30.8 Edit CDN resource ..................................................................................................................... 250 30.9 Edit CDN resource advanced settings ....................................................................................... 251 30.10 Prefetch CDN resource content ............................................................................................ 251 30.11 Purge CDN resource content ................................................................................................ 252 30.12 Delete CDN resource ............................................................................................................. 252 30.13 View bandwidth statistics ..................................................................................................... 253 30.14 View billing statistics for a resource ..................................................................................... 254 31. CDN Edge groups ..................................................................................................... 256 31.1 View CDN edge groups.............................................................................................................. 256 31.2 View CDN edge group details.................................................................................................... 256 31.3 Create CDN edge group ............................................................................................................ 259 31.4 Edit CDN edge group ................................................................................................................. 259 31.5 Delete CDN edge group ............................................................................................................ 260 31.6 Assign location to the group ..................................................................................................... 260 31.7 Unassign location from the group ............................................................................................ 261 32. CDN usage statistics ................................................................................................ 262 33. DNS setup ............................................................................................................... 263 33.1 Get DNS domain details ............................................................................................................ 263 33.2 Set up DNS domain ................................................................................................................... 263 33.3 Edit DNS domain ....................................................................................................................... 264 33.4 Get the list of glue records........................................................................................................ 264 34. 34.1 DNS zone ................................................................................................................ 266 Get the list of own DNS zones................................................................................................... 266 12 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 34.2 Get the list of users DNS zones ................................................................................................. 266 34.3 Get the domain zone details ..................................................................................................... 267 34.4 Add new DNS zone .................................................................................................................... 268 34.5 Delete DNS zone ....................................................................................................................... 268 34.6 Get the list of name servers ...................................................................................................... 269 34.7 Get the list of DNS Zone Records .............................................................................................. 269 34.8 Get a particular record’s details................................................................................................ 273 34.9 Create DNS record .................................................................................................................... 274 34.10 Edit DNS records ................................................................................................................... 275 34.11 Delete a record...................................................................................................................... 277 35. Backups .................................................................................................................. 278 35.1 Get the list of VM backups ........................................................................................................ 278 35.2 Create a disk backup ................................................................................................................. 279 35.3 Convert a backup to a template ............................................................................................... 279 35.4 Restore a backup....................................................................................................................... 280 35.5 Delete a backup ........................................................................................................................ 280 36. Autobackup presets ................................................................................................ 282 36.1 Get the list of autobackup presets............................................................................................ 282 36.2 Get autobackup preset details .................................................................................................. 283 36.3 Edit an autobackup preset ........................................................................................................ 283 37. Schedules ................................................................................................................ 285 37.1 Get the list of schedules............................................................................................................ 285 37.2 Get schedule details .................................................................................................................. 286 37.3 Edit a schedule .......................................................................................................................... 287 37.4 Delete a schedule ...................................................................................................................... 288 38. License .................................................................................................................... 289 38.1 Get license details ..................................................................................................................... 289 38.2 Edit license details..................................................................................................................... 289 39. SSH keys.................................................................................................................. 291 39.1 View SSH keys ........................................................................................................................... 291 39.2 Add a SSH key............................................................................................................................ 291 13 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 39.3 Edit a SSH key ............................................................................................................................ 292 39.4 Delete a SSH key. ...................................................................................................................... 292 40. Statistics ................................................................................................................. 294 41. Background task daemon ........................................................................................ 296 41.1 Start background task daemon ................................................................................................. 296 41.2 Stop background task daemon ................................................................................................. 296 41.3 Reload background task daemon ............................................................................................. 297 41.4 Get background task daemon status ........................................................................................ 297 42. Transactions............................................................................................................ 298 42.1 Get the list of transactions ........................................................................................................ 298 42.2 Get the list of a VM’s transactions ............................................................................................ 299 42.3 Get a particular transaction’s details ........................................................................................ 300 43. Logs ........................................................................................................................ 301 43.1 Get the list of log items ............................................................................................................. 301 43.2 Get log item details ................................................................................................................... 301 44. 44.1 System configuration .............................................................................................. 303 View system configuration........................................................................................................ 303 45. Version ................................................................................................................... 307 46. Document revisions................................................................................................. 308 14 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 1. Introduction The API enables cloud integration with third party applications – for example, a billing application like Ubersmith. You can manage every aspect of your cloud through the API. • • • The OnAPP API is RESTful All function calls respond to xml and JSON requests All function calls need authentication (Basic HTTP or API key) To authenticate using HTTP Basic, just use your username/password combination. Curl example: curl –u user:userpass To authenticate using API key, put your account email as a login and the key to the server as a password. XML example curl –u user:userpass -H 'Accept: application/xml' -H 'Content-type: application/xml' http://onapp.test/virtual_machines.xml JSON example curl -u [email protected]:88c3d9ecfa2de8497e038cb5a1a5e2ce62ba0e755 -H 'Accept: application/json' -H 'Content-type: application/json' http://onapp.test/users.json The API returns appropriate HTTP status codes for every request: 200 OK The request completed successfully 201 Scheduled The request has been accepted and scheduled for processing 403 Forbidden The request is correct, but could not be processed. 404 Not Found The requested URL is incorrect or the resource does not exist. For example, if you request to delete a user with ID {5}, but there is no such a user in the cloud, you will get a 404 error. 422 Unprocessable Entity The sent parameters are erroneous. 500 Internal Server Error An error occurred. Please contact support. 15 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 1.1 Documentation conventions The table below represents all the existing formatting and naming conventions: Convention user:userpass Explanation stands for username:password combination Example Admin:123456 onapp.test stands for address, where your Control Panel is located Example.com :id stands for the resource ID 23 italics all the parameters are italicised currency_code *(asterisk) marks the required parameters label * monospace indicates request examples in XML or Json GET code marks the console request and response examples curl -i -X DELETE -u user:userpass -url http://onapp.test/roles/:id.xml emphasis notes, warnings, and other important information The role for a particular user is output 1.2 /roles.xml on /users/:id request FAQs Q: Is it possible to enable API access via https? A: We can enable https for your cloud, which can be used for both WebUI access and API access. Or you can do so yourself: the Apache config file is located at /etc/httpd/conf.d/onapp.conf Q: Can you create a VM on behalf of another user? A: No. It is possible to switch VM owners, however. Refer to Change a VM owner section for details. Q: How are passwords stored – in plain text? A: No, passwords are not stored in plain text. Except for a login and password combination, you can use email + API key combination to authorize a user via the API. API keys can be generated and changed 16 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 easily on a user’s profile page (as well as through the API). For security reasons we recommend users authenticate through the API key, not the login and password. Q: Which parameters are required, and which are optional? A: Required parameters are marked in this guide with an asterisk (*) 17 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 2. Roles This class manages roles assigned to users. A role itself maintains a set of permissions that gives an access to cloud resources and control panel functionality. You can easily regulate roles (and users in turn) using view/edit/delete options. 2.1 Get the list of roles This method gets the list of all the roles available in the system: GET GET /roles.xml /roles.json XML Output example <?xml version="1.0" encoding="UTF-8"?> <roles> <role> <label>Administrator</label> <created_at>2010-05-26T13:34:58Z</created_at> <updated_at>2010-07-18T21:16:14Z</updated_at> <id>1</id> <identifier>admin</identifier> <permissions> <permission> <label>Any action on virtual machines</label> <created_at>2010-05-26T13:34:58Z</created_at> <updated_at>2010-05-26T13:34:58Z</updated_at> <id>1</id> <identifier>virtual_machines</identifier> </permission> ... <permission></permission> </permissions> </role> </roles> Where: roles – an array of all roles with their details and assigned permissions label – role title created_at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format updated_at – the date when the role was updated in the [YYYY][MM][DD]T[hh][mm][ss]Z format id – role ID identifier – role identifier permissions – an array with all the permissions assigned to this role, where: • • • label – permission tytel (permission on an action) created_at – time in [YYYY][MM][DD]T[hh][mm][ss]Z format updated_at – time in [YYYY][MM][DD]T[hh][mm][ss]Z format 18 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 • • 2.2 id – permission ID identifier – permission identifier Get role details This method will output the details for a particular user role. GET GET /roles/:id.xml /roles/:id.json XML Output example <?xml version="1.0" encoding="UTF-8"?> <role> <label>TT</label> <created_at type="datetime">2011-02-11T11:20:00Z</created_at> <updated_at type="datetime">2011-02-11T13:56:44Z</updated_at> <id type="integer">3</id> <identifier>gkue74amkiznb7</identifier> <permissions type="array"> <permission> <label>Any action Sysadmin Tools</label> <created_at type="datetime">2011-02-11T10:35:16Z</created_at> <updated_at type="datetime">2011-02-11T10:35:16Z</updated_at> <id type="integer">4</id> <identifier>sysadmin_tools.read</identifier> </permission> </permissions> </role> For details refer Get the list of roles section The role for a particular user is output on /users/:id request 2.3 Edit a role Use the Put method to edit a role: PUT PUT /roles/:id.xml /roles/:id.json XML Request example curl -i -X PUT -u user:userpass -H 'Accept: application/xml' -H 'Content-type: application/xml' -d '<role><label>changed</label><permission_ids type="array"><permissions_id>12</permissions_id><permissions_id>14</permissions_id><pe rmissions_id>6</permissions_id><permissions_id>1</permissions_id></permission_ids></ro le>' --url http://onapp.test/roles/:id.xml JSON Request example 19 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 curl -i -X PUT -u user:userpass -H 'Accept: application/json' -H 'Content-type: application/json' -d '{"role":{"label":"jsonchanged","permission_ids":[1,2,3,4,5,6,7,8,9]}}' --url http://onapp.test/roles/:id.json Where you can change: label – role title permission_ids – ID of permissions, which you want to assign to this role 2.4 Add a new role POST POST /roles.xml /roles.json XML Request example curl -i -X POST -u user:userpass -H 'Accept: application/xml' -H 'Content-type: application/xml' -d '<role><label>New_role_xml</label><permission_ids type="array"><permission_id>12</permission--_id><permission_id>14</permission-_id><permission_id>16</permission_id><permission_id>11</permission_id><permission_id>1 0</permission_id><permission_id>35</permission_id></permission_ids></role>' --url http://onapp.test/roles.xml JSON Request example curl -i -X POST -u user:userpass -H 'Accept: application/json' -H 'Content-type: application/json' -d '{"role":{"label":"New_role_json","permission_ids":[12,14,16,11,10,35]}}' --url http://onapp.test/roles.json The following parameters should be sent: label * permission-id 2.5 the new role label (required) the ID of the permission you would like to assign to this role (optional) Delete a role Use the following method to delete a user role: DELETE DELETE /roles/:id.xml /roles/:id.json XML Request example curl -i -X DELETE -u user:userpass --url http://onapp.test/roles/:id.xml 20 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 JSON Request example curl -i -X DELETE -u user:userpass --url http://onapp.test/roles/:id.json This returns an HTTP 200 response if the role is deleted, or HTTP 404 if the user with the specified ID isn’t found. 2.6 Edit a user’s role assignment To change a role, assigned to the user, add new role (or set of roles), use this request: PUT PUT /users/:id.xml /users/:id.json XML Request example curl -i -X PUT -u user:userpass -H 'Accept: application/xml' -H 'Content-type: application/xml' -d '<user><role_ids>3</role_ids><role_ids>1</role_ids></user>' --url http://onapp.test/users/:id.xml JSON Request example curl -i -X PUT -u user:userpass -H 'Accept: application/json' -H 'Content-type: application/json' -d '{"user":{role_ids:[“3”,”1”]}}' --url http://onapp.test/users/:id.json Where: role_ids – ID of role(s) you want to assign to the user This returns an HTTP 200 response if roles are changed, or HTTP 404 if the specified role ID isn’t found. 2.7 Get the list of all permissions To get the list of all available permissions, use the following request: GET GET /permissions.xml /permissions.json Output example 21 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 <?xml version="1.0" encoding="UTF-8"?> <permissions> <permission> <label>Any action on virtual machines</label> <created_at>2010-05-26T13:34:58Z</created_at> <updated_at>2010-05-26T13:34:58Z</updated_at> <id>1</id> <identifier>virtual_machines</identifier> </permission> ... <permission></permission> ... </permissions> Where: label – permission title (permission on an action) created_at – time in [YYYY][MM][DD]T[hh][mm][ss]Z format updated_at – time in [YYYY][MM][DD]T[hh][mm][ss]Z format id – permission ID identifier – permission identifier 22 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 3. Billing plans This class manages billing plans, which incorporate prices and resource limits for users. Billing plans can be associated with hypervisor, network and data store zones, as well as template groups. Consequently, these plans enable you to control overall user resource limits, and limits for resources in different zones of the cloud. To manage billing plans and their resources for a particular user, specify the request by a user_id parameter, e.g: GET /users/:user_id/billing_plans/:billing_plan_id/base_resources.xml These are the resources you can limit and set prices for, along with the units in which they are measured: Virtual Machine resources Unit CPU CPU core/hour CPU Priority CPU priority/hour Disk Size GB/hour Memory Mb/hour IP Address IP/hour Virtual Machine VM/hour Template & Backup Storage GB/hour Data store zone resources Disk size GB/hour Data read Gb/per Gb Data written Gb/per Gb Input requests per request Output requests per request 23 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 Network zone resources 3.1 IP Address IP Port Speed MB/hour Data received Gb/per Gb Data sent Gb/per Gb Get the list of billing plans To get the list of billing plans created in your cloud, use the following method: GET GET /billing_plans.xml /billing_plans.json XML Output example <?xml version="1.0" encoding="UTF-8"?> <billing_plans type="array"> <billing_plan> <label>default billing</label> <created_at type="datetime">2011-02-11T12:35:17+02:00</created_at> <base_resources type="array"> <base_resource> <created_at type="datetime">2011-02-14T16:11:51+02:00</created_at> <limits> <limit_free>4</limit_free> <limit>12</limit> </limits> <updated_at type="datetime">2011-02-14T16:11:51+02:00</updated_at> <billing_plan_id type="integer">1</billing_plan_id> <id type="integer">14</id> <unit nil="true"></unit> <label>CPU</label> <resource_name>cpu</resource_name> <prices> <price_on>5.000000</price_on> <price_off>2.000000</price_off> </prices> </base_resource> <updated_at type="datetime">2011-03-19T10:13:33+02:00</updated_at> <monthly_price type="decimal">20.0</monthly_price> <id type="integer">103</id> <show_price type="boolean">true</show_price> <currency_code>USD</currency_code> </billing_plan> </billing_plans> 24 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 Explanation of the data returned: Label created_at updated_at the billing plan name the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format the date when the billing plan was updated in the [YYYY][MM][DD]T[hh][mm][ss]Z format the billing type ID an array o resource limits and prices for the resources included into this plan the currency that users are charged in within this billing plan true if users can see the prices set up for them, otherwise false. monthly fee for this billing plan Id base_resources currency_code show_price monthly_price 3.2 Add a billing plan To add a new billing plan: POST POST /billing_plans.xml /billing_plans.json XML Request example curl -i -X POST http://onapp.test/billing_plans.xml -d ‘<billing_plan><label>billing_label</label><currency_code></currency_code><monthly_pri ce>10</monthly_price></billing_plan>’ -u user:userpass -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON request example curl -i -X POST http://onapp.test/billing_plans.json -d ‘{billing_plan:{label:”billing_label”,currency_code:””,monthly_price:”10”}}’ -u user:userpass -H 'Accept: application/json' -H 'Content-type: application/json' The following parameters should be sent: label * currency_code monthly_price * the billing plan name the currency that users will be charged in within this billing plan. Optional, if none specified USD will be applied Set monthly fee for plan usage. 25 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 Response example: {"billing_plan":{"label":"billing label","created_at":"2011-0419T14:01:34+03:00","updated_at":"2011-0419T14:01:34+03:00","base_resources":[],"id":105,"monthly_price":"10","currency_code":" ","show_price":null}} 3.3 Get billing plan details This method outputs the details for a particular billing plan: GET GET /billing_plans/:id.xml /billing_plans/:id.json Output example <?xml version="1.0" encoding="UTF-8"?> <billing_plan> <label>user33</label> <created_at type="datetime">2011-01-14T14:06:45Z</created_at> <updated_at type="datetime">2011-01-14T16:15:16Z</updated_at> <id type="integer">13</id> <currency_code>EUR</currency_code> <show_price type="boolean">false</show_price> </billing_plan> Explanation of the data returned: label created_at the billing plan name the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format the date when the billing plan was updated in the [YYYY][MM][DD]T[hh][mm][ss]Z format updated_at id currency_code the billing type ID the currency that users are charged in within this billing plan True, if users can see the prices set up for them, otherwise false. show_price 3.4 Edit a billing plan To edit an existing plan: PUT PUT /billing_plans/:id.xml /billing_plans/:id.json XML Request example 26 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 curl -i -X PUT http://onapp.test/billing_plans/:billing_plan_id.xml -d ‘<billing_plan><label>new_label</label><currency_code></currency_code><monthly_price>1 0</monthly_price></billing_plan>’ -u user:userpass -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X PUT http://onapp.test/billing_plans/:billing_plan_id.json -d ‘{billing_plan:{label:”new_label”,currency_code:””,monthly_price:”10”}}’ -u user:userpass -H 'Accept: application/json' -H 'Content-type: application/json' With this method you can edit the following parameters: 3.5 label the desired billing plan name currency_code the code of the currency you're going to charge in. Currently, you can choose between USD, EUR or GBP. show_price Specify if users can see plan prices Delete a billing plan To delete a billing plan: DELETE DELETE /billing_plans/:id.xml /billing_plans/:id.json XML Request example curl -i -X DELETE http://onapp.test/billing_plans/:billing_plan_id.xml -u user:userpass -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X DELETE http://onapp.test/billing_plans/billing_plan_id.json -u user:userpass -H 'Accept: application/json' -H 'Content-type: application/json' Returns HTTP 200 response on successful processing, and HTTP 404 when there is no billing plan with a requested ID, or URL is incorrect. 3.6 View base resources for a billing plan To view which base resources were added to a particular billing plan, use the following method: GET GET /billing_plans/:billing_plan_id/base_resources.xml /billing_plans/:billing_plan_id/base_resources.json 27 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 This API call returns only those base resources (and their details), which are assigned to this billing plan. See the following sections to learn more about base resources and their details. 3.7 Add base resource limits to a billing plan To add base resources to the billing plan, use the following request: POST POST /billing_plans/:billing_plan_id/base_resources.xml /billing_plans/:billing_plan_id/base_resources.json Base resources can be priced differently: some may have different prices, depending whether VM is on or off (Virtual Machines base resource limits); some of the resources are charged per unit, regardless if they are on or off (Other base resource limits); another type of resource serves only as a limit to the billing plan, without any charges (Template groups limits, Hypervisor zone limits). See below for examples of each. 3.7.1 Add Virtual Machines base resource limits XML Request example curl -i -X POST http://onapp.test/billing_plans/:billing_plan_id/base_resources.xml -d '<base_resource><resource_class>Resource::[resource_name]</resource_class><billing_pla n_id>21</billing_plan_id><limit>30</limit><limit_free>10</limit_free><prices><price_on >10</price_on><price_off>5</price_off></prices></base_resource>' -u user:userpass -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X POST http://onapp.test/billing_plans/:billing_plan_id/base_resources.json d'{"base_resource":{"resource_class":"Resource::[resource_name]","billing_plan_id":"21 ","limits":{"limit":"30","limit_free":"10"},"prices":{"price_on":"10","price_off":"5"} }}' -u user:userpass -H 'Accept: application/json' -H 'Content-type: application/json' Parameters: resource_class * - the name of the base resource you add to the billing plan in the following format: Resource:[resource_name], where [resource_name] can be: [resource_name] UI Label Cpu Cpu_share Memory Disk_size Ip_address CPU limit CPU priority limit Memory limit Disk Size limit IP Address limit 28 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 id * - the ID of the billing plan. You have to send it, even though it is in the URL address limit - sets maximum amount of units of the resource limit_free - amount of units which are given for free price_on - price, when the VM is on price_off - price, when the VM is off 3.7.2 Add other base resource limits XML Request example curl -i -X POST http://onapp.test/billing_plans/:billing_plan_id/base_resources.xml -d '<base_resource><resource_class>Resource::[resource_name]</resource_class><billing_pla n_id>21</billing_plan_id><limit>30</limit><limit_free>10</limit_free><prices><price>10 </price></prices></base_resource>' -u user:userpass -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X POST http://onapp.test/billing_plans/:billing_plan_id/base_resources.json d'{"base_resource":{"resource_class":"Resource::[resource_name]","billing_plan_id":"21 ","limits":{"limit":"30","limit_free":"10"},"prices":{"price":"10"}}}' -u user:userpass -H 'Accept: application/json' -H 'Content-type: application/json' Parameters: resource_class * - the name of the base resource you add to the billing plan in the following format: Resource:[resource_name], where [resource_name] can be: [resource_name] UI Label Vm_monit Vm_limit Template Storage_disk_size Backup Monit limit Virtual Machine limit Template limit Templates & Backups Storage limit Backups limit id * - the ID of the billing plan. You have to send it, even though it is in the URL address limit - sets maximum amount of units of the resource limit_free - amount of units which are given for free price – price per unit 29 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 3.7.3 Add limits for template groups and hypervisor zones XML Request example curl -i -X POST -u user:userpass -H'Content-type: application/xml' -H'Accept: application/xml' http://onapp.test/billing_plans/21/base_resources.xml d'<base_resource><resource_class>Resource::[resource_name]</resource_class><billing_pl an_id>21</billing_plan_id><target_id>22</target_id><target_type>[target_type]</target_ type></base_resource>' JSON Request example curl -i -X POST -u user:userpass -H'Content-type: application/json' -H'Accept: application/json' http://onapp.test/billing_plans/21/base_resources.json d'{"base_resource":{"resource_class":"Resource::[resource_name]","billing_plan_id":"21 ","target_id":"22","target_type":"[target_type]"}}' Parameters: resource_class * -the name of the base resource you add to the billing plan in the following format: Resource:[resource_name], where [resource_name] can be: [resource_name] UI Label TemplateGroup HypervisorGroup Limits for Template Groups Limits for Hypervisor Zones id * -the ID of the billing plan. You have to send it, even though it is in the URL address target_type* - the type of the group you add to the billing plan limits: [target_type] UI Label ImageTemplateGroup Limits for Template Groups HypervisorGroup Limits for Hypervisor Zones target_id* - the ID of the group (or zone) you add to billing plan limits Check the ID of the necessary group (zone) with following calls: GET /settings/image_template_groups.xml(json) GET /settings/hypervisor_zones.xml(json) 30 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 3.7.4 Add limits for data store zones By adding data store zone resources to a billing plan, you limit the user only to the data stores in that zone. XML Request example curl -i -X POST -u uesr:userpass -H'Content-type: application/xml' -H'Accept: application/xml' http://onapp.test/billing_plans/:billing_plan_id/base_resources.xml d'<base_resource><resource_class>Resource::DataStoreGroup</resource_class><billing_pla n_id>41</billing_plan_id><target_id>56</target_id><target_type>DataStoreGroup</target_ type><limits><limit_free>1</limit_free><limit>20</limit><limit_reads_completed_free>2< /limit_reads_completed_free><limit_data_written_free>3</limit_data_written_free><limit _data_read_free>4</limit_data_read_free><limit_writes_completed_free>5</limit_writes_c ompleted_free></limits><prices><price_data_written>6</price_data_written><price_off>7< /price_off><price_on>8</price_on><price_data_read>9</price_data_read><price_writes_com pleted>10</price_writes_completed><price_reads_completed>11</price_reads_completed></p rices><limit_type>hourly</limit_type></base_resource>' JSON Request example curl -i -X POST -u user:userpass -H'Content-type: application/json' -H'Accept: application/json' http://onapp.test/billing_plans/:billing_plan_id/base_resources.json d'{"base_resource":{"resource_class":"Resource::DataStoreGroup","billing_plan_id":"41" ,"target_id":"56","target_type":"DataStoreGroup","limits":{"limit_free":"1","limit":"2 0","limit_reads_completed_free":"2","limit_data_written_free":"3","limit_data_read_fre e":"4","limit_writes_completed_free":"5"},"limit_type":"hourly","prices":{"price_data_ written":"6","price_off":"7","price_on":"8","price_data_read":"9","price_writes_comple ted":"10","price_reads_completed":"11"}}}' Where: resource_class * -the name of the base resource you add to the billing plan in the following format: Resource::[DataStoreGroup] billing_plan_id * - the ID of the billing plan. You have to send it, even though it is in the URL address target_type * - the type of the group you add to the billing plan limits: [DataStoreGroup] target_id * - the ID of the group (or zone) you add to billing plan limits Check the ID of the necessary data store zone with GET /data_store_zones.xml.xml(json) call. limit_free – free disk space on data store zone limit – maximum available disk space limit_type – limit type set for the resource; can be hourly or monthly limit_data_written_free - the amount of data users get for free for write operations (in GB) 31 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 limit_data_read_free - the amount of data users get for free for read operations (in GB) limit_reads_completed_free - the maximum number (in millions) of Input requests which can happen at once limit_writes_completed_free - the maximum number (in millions) of Output requests which can happen at once price_data_read – price per GB of data for read operations price_data_written - price per GB of data for write operations price_on – price per GB of disk size, when VM is on price_off - price per GB of disk size, when VM is off price_writes_completed – price per million of Output requests which can happen at once price_reads_completed - price per million of Input requests which can happen at once 3.7.5 Add limits for network zones By adding network zone resources to a billing plan, you limit the user only to the network(s) in that zone. XML Request example curl -i -X POST -u user:userpass -H'Content-type: application/xml' -H'Accept: application/xml' http://onapp.test/billing_plans/:billing_plan_id/base_resources.xml d'<base_resource><resource_class>Resource::NetworkGroup</resource_class><billing_plan_ id>41</billing_plan_id><target_id>33</target_id><target_type>NetworkGroup</target_type ><limits><limit_ip>20</limit_ip><limit_rate>20</limit_rate><limit_data_sent_free>1</li mit_data_sent_free><limit_rate_free>2</limit_rate_free><limit_ip_free>3</limit_ip_free ><limit_data_received_free>4</limit_data_received_free></limits><prices><price_ip_off> 6</price_ip_off><price_ip_on>2</price_ip_on><price_rate_off>3</price_rate_off><price_r ate_on>4</price_rate_on><price_data_sent>5</price_data_sent><price_data_received>6</pr ice_data_received></prices><limit_type>hourly</limit_type></base_resource>' JSON Request example curl -i -X POST -u user:userpass -H'Content-type: application/json' -H'Accept: application/json' http://onapp.test/billing_plans/:billing_plan_id/base_resources.json d'{"base_resource":{"resource_class":"Resource::NetworkGroup","billing_plan_id":"41"," target_id":"33","target_type":"NetworkGroup","limits":{"limit_ip":"20","limit_rate":"2 0","limit_data_sent_free":"1","limit_rate_free":"2","limit_ip_free":"3","limit_data_re ceived_free":"4"},"limit_type":"hourly","prices":{"price_ip_off":"6","price_ip_on":"2" ,"price_rate_off":"3","price_rate_on":"4","price_data_sent":"5","price_data_received": "6"}}}' Where: 32 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 resource_class * -name of the base resource you add to the billing plan in the following format: Resource::NetworkGroup billing_plan_id * - ID of the billing plan. You have to send it, even though it is in the URL address target_type * - type of the group you add to the billing plan limits: [NetworkGroup] target_id * - ID of the network zone you add to billing plan limits Check the ID of the necessary network zone with GET /network_zones.xml.xml(json) call. limit_ip - the total amount of IP addresses limit_ip_free - the amount of IP addresses users get for free limit_data_sent_free - the amount of data users can send for free limit_data_received_free - the amount of data users can receive for free limit_rate - the total available port speed users limit_rate_free - the port speed users get for free price_ip_on – price per IP when VM is on price_ip_off - price per IP when VM is off price_rate_on – price for port speed (Mbps) when VM is on price_rate_off - price for port speed (Mbps) when VM is off price_data_sent – price for sent data per GB per hour price_data_received – price for received data per GB per hour limit_type – limit type set for the resource; can be hourly or monthly 3.7.6 Add limits for edge groups By assigning edge groups to a billing plan, you set the prices for the bandwidth users signed up for this plan consume. XML request example: 33 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 curl -i -X POST -u user:userpass http://onapp.test/billing_plans/15/resource_edge_groups.xml -d '<base_resource><target_id>4</target_id><price>10.5</price><billing_plan_id>15</billin g_plan_id><target_type>EdgeGroup</target_type></base_resource>' -H 'Accept: application/xml' -H 'Content-type: application/xml' Json request example: curl -i -X POST -d '{"base_resource":{"target_id":"4","price":"10","billing_plan_id":"15","target_type":" EdgeGroup"}}' -u user:userpass http://onapp.test/billing_plans/15/resource_edge_groups.json -H 'Accept: application/json' -H 'Content-type: application/json' Where: target_id* – the ID of the edge group you add to a billing plan price – price per Gb of bandwidth billing_plan_id* - ID of the billing plan. You have to send it, even though it is in the URL address target_type* - type of the group you add to the billing plan limits: [EdgeGroup] 3.7.7 Add limits for backup server zones By adding backup server zone resources to a billing plan, you limit the user only to the backup servers in that zone. XML Request example curl -i -X POST -u user:userpass http://onapp.test/billing_plans/:id/base_resources.xml -d '<base_resource><resource_class>Resource::BackupServerGroup</resource_class><billing_p lan_id>182</billing_plan_id><target_id>28</target_id><target_type>BackupServerGroup</t arget_type><limits><limit_backup_free>2</limit_backup_free><limit_backup>10</limit_bac kup><limit_backup_disk_size_free>2</limit_backup_disk_size_free><limit_backup_disk_siz e>10</limit_backup_disk_size><limit_template_free>2</limit_template_free><limit_templa te>10</limit_template><limit_template_disk_size_free>2</limit_template_disk_size_free> <limit_template_disk_size>10</limit_template_disk_size></limits><prices><price_backup> 50</price_backup><price_backup_disk_size>50</price_backup_disk_size><price_template_di sk_size>50</price_template_disk_size><price_template>50</price_template></prices></bas e_resource>' -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example 34 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 curl -i -X POST -u user:userpass http://onapp.test/billing_plans/:id/base_resources.json -d '{"base_resource": {"resource_class": "Resource::BackupServerGroup","billing_plan_id": "182","target_id": "28","target_type": "BackupServerGroup","limits":{"limit_backup_free":"2", "limit_backup":"10", "limit_backup_disk_size_free":"2", "limit_backup_disk_size":"10", "limit_template_free":"2", "limit_template":"10", "limit_template_disk_size_free":"2", "limit_template_disk_size":"10"}, "prices": {"price_backup":"50", "price_backup_disk_size":"50", "price_template_disk_size":"50", "price_template":"50"}}}' -H 'Accept: application/json' -H 'Content-type: application/json' Where: label – name of the backup server zone assigned to the billing plan resource_name – the name of the base resource. In this case it is BackupServerGroup created at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format target_id – backup server zone id limits – an array of limits set up for this resource limit_backup_free –the number of backups user gets for free limit_backup – the total number of backups allowed limit_backup_disk_size_free –disk size user gets for free to store their backups limit_backup_disk_size – maximum backup disk size allowed limit_template_disk_size – maximum template disk size allowed limit_template – the total number of templates allowed limit_template_free –the number of templates user gets for free limit_template_disk_size_free – template disk size user gets for free updated at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format billing_plan_id * - the ID of the billing plan id – resource ID unit – a unit per which the price is set price_backup – price per backup over limit price_template – price per template over limit 35 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 price_template_disk_size – price per GB of template disk size over limit limit type – this parameter doesn’t mean anything for backup server zone resource 3.8 Edit base resources of a billing plan To change limits and prices for a base resource, use the following request: PUT PUT /billing_plans/:billing_plan_id/base_resources/:id.xml /billing_plans/:billing_plan_id/base_resources/:id.json XML Request example curl -i -X PUT -u user:userpass --url http://onapp.test/billing_plans/:billing_plan_id/base_resources/:id.xml -d '<base_resource><prices><price_on>0.1</price_on><price_off>0.01</price_off></prices></ base_resource>' -H 'Accept: application/xml’ -H 'Content-type: application/xml' JSON Request example curl -i -X PUT -u user:userpass --url http://onapp.test/billing_plans/:billing_plan_id/base_resources/:id.json -d '{"base_resource":{"prices":{"price_on":0.1,"price_off":0.01}}}' -H 'Accept: application/json' -H 'Content-type: application/json' You can check ID of the required base resource with GET method. 3.9 DELETE DELETE Delete a base resource from a billing plan /billing_plans/:billing_plan_id/base_resources/:id.xml /billing_plans/:billing_plan_id/base_resources/:id.json XML Request example curl -i -X DELETE -u user:userpass http://onapp.test/billing_plans/:billing_plan_id/base_resources/:id.xml JSON Request example curl -i -X DELETE -u user:userpass http://onapp.test/billing_plans/:billing_plan_id/base_resources/:id.json 3.10 Get CPUs details To get details for CPU resource of a particular billing plan, use the following methods: GET GET /billing_plans/:billing_plan_id/base_resources/:id.xml /billing_plans/:billing_plan_id/base_resources/:id.json 36 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 You can check ID of the required base resource with GET method: GET /billing_plans/:billing_plan_id/base_resources.xml GET /billing_plans/:billing_plan_id/base_resources.json An array of billing plan and CPU resource details will be returned. XML Output example <base_resource> <label>CPU</label> <created_at type="datetime">2012-03-15T15:35:42+02:00</created_at> <target_id nil="true"/> <limits> <limit_free>10</limit_free> <limit>50</limit> </limits> <updated_at type="datetime">2012-03-15T15:35:42+02:00</updated_at> <billing_plan_id type="integer">375</billing_plan_id> <id type="integer">1355</id> <unit nil="true"/> <resource_name>cpu</resource_name> <prices> <price_on>1.00000000</price_on> <price_off>1.00000000</price_off> </prices> <limit_type>hourly</limit_type> </base_resource> Where: label – name of the edge group assigned to the billing plan created_at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format limits – an array of limits set up for this resource limit free - the number of CPU cores that users get for free limit - the total number of CPU cores billing_plan_id * - the ID of the billing plan id – resource ID resource_name – the name of the base resource. In this case it is CPU price_on - the prices per CPU core per hour for powered on VMs price_off - the prices per CPU core per hour for powered off VMs 37 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 limit_type – hourly or monthly limit type set for the resource 3.11 Get CPU Priority details To get details of a particular CPU priority resource, use the following method: GET GET /billing_plans/:billing_plan_id/base_resources/:id.xml /billing_plans/:billing_plan_id/base_resources/:id.json You can check ID of the required base resource with GET method: GET /billing_plans/:billing_plan_id/base_resources.xml GET /billing_plans/:billing_plan_id/base_resources.json XML Output example <base_resource> <label>CPU Priority</label> <created_at type="datetime">2012-03-15T15:45:16+02:00</created_at> <target_id nil="true"/> <limits> <limit_free>10</limit_free> <limit>60</limit> </limits> <updated_at type="datetime">2012-03-15T15:45:16+02:00</updated_at> <billing_plan_id type="integer">375</billing_plan_id> <id type="integer">1358</id> <unit nil="true"/> <resource_name>cpu_share</resource_name> <prices> <price_on>1.00000000</price_on> <price_off>2.00000000</price_off> </prices> <limit_type>hourly</limit_type> </base_resource> The system will output the details of the billing plan, as well as the following CPU Shares resource details: label – name of the edge group assigned to the billing plan created_at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format limits – an array of limits set up for this resource limit - the total of CPU Priority allowed within this billing plan (in %) limit free - the limit of CPU Priority users get for free within this billing plan (in %) updated at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format 38 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 billing_plan_id * - the ID of the billing plan id – resource ID resource_name – the name of the base resource. In this case it is CPU priority price_on - the price for the resource for powered on VMs price_off - the price for the resource for powered off VMs limit_type – hourly or monthly limit type set for the resource 3.12 Get memory details To get details of a Memories resource for a particular billing plan, use the following method: GET GET /billing_plans/:billing_plan_id/base_resources/:id.xml /billing_plans/:billing_plan_id/base_resources/:id.json You can check ID of the required base resource with GET method: GET /billing_plans/:billing_plan_id/base_resources.xml GET /billing_plans/:billing_plan_id/base_resources.json XML Output example <base_resource> <label>Memory</label> <created_at type="datetime">2012-03-15T15:55:59+02:00</created_at> <target_id nil="true"/> <limits> <limit_free>50</limit_free> <limit>1000</limit> </limits> <updated_at type="datetime">2012-03-15T15:55:59+02:00</updated_at> <billing_plan_id type="integer">375</billing_plan_id> <id type="integer">1360</id> <unit>mb</unit> <resource_name>memory</resource_name> <prices> <price_on>1.00000000</price_on> <price_off>2.00000000</price_off> </prices> <limit_type>hourly</limit_type> </base_resource> Where: label – name of the edge group assigned to the billing plan 39 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 created_at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format limits – an array of limits set up for this resource limit_free - the amount of free RAM users get limit - the entire amount of RAM updated at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format billing_plan_id * - the ID of the billing plan id – resource ID unit – a unit per which the price is set resource_name – the name of the base resource. In this case it is memory price_on - the price for memory per MB for powered on VM price_off - the price for memory per MB for powered off VM limit_type – hourly or monthly limit type set for the resource 3.13 Get disk size details To see details for a Disk size resource: GET GET /billing_plans/:billing_plan_id/base_resources/:id.xml /billing_plans/:billing_plan_id/base_resources/:id.json You can check ID of the required base resource with GET method: GET /billing_plans/:billing_plan_id/base_resources.xml GET /billing_plans/:billing_plan_id/base_resources.json XML Output example <base_resource> <label>Disk Size</label> <created_at type="datetime">2012-03-15T15:59:37+02:00</created_at> <target_id nil="true"/> <limits> <limit_free>10</limit_free> <limit>100</limit> </limits> <updated_at type="datetime">2012-03-15T15:59:37+02:00</updated_at> <billing_plan_id type="integer">375</billing_plan_id> <id type="integer">1361</id> 40 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 <unit>gb</unit> <resource_name>disk_size</resource_name> <prices> <price_on>5.00000000</price_on> <price_off>4.00000000</price_off> </prices> <limit_type>hourly</limit_type> </base_resource> Where: label – name of the edge group assigned to the billing plan created_at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format limits – an array of limits set up for this resource limit_free - the number of free GBs users can allocate to their disks limit - the total number of GB users can allocate to their disks updated at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format billing_plan_id * - the ID of the billing plan id – resource ID resource_name – the name of the base resource. In this case it is disk size unit – a unit per which the price is set price_on - the prices per GB for powered on VM’s per hour price_off - the prices per GB for powered off VM’s per hour limit_type – hourly or monthly limit type set for the resource 3.14 Get IP address details To get details for an IP Address resource: GET GET /billing_plans/:billing_plan_id/base_resources/:id.xml /billing_plans/:billing_plan_id/base_resources/:id.json You can check ID of the required base resource with GET method: GET /billing_plans/:billing_plan_id/base_resources.xml GET /billing_plans/:billing_plan_id/base_resources.json 41 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 XML Output example <base_resource> <label>IP Address</label> <created_at type="datetime">2012-03-15T16:02:31+02:00</created_at> <target_id nil="true"/> <limits> <limit_free>5</limit_free> <limit>10</limit> </limits> <updated_at type="datetime">2012-03-15T16:02:31+02:00</updated_at> <billing_plan_id type="integer">375</billing_plan_id> <id type="integer">1362</id> <unit nil="true"/> <resource_name>ip_address</resource_name> <prices> <price_on>2.00000000</price_on> <price_off>1.00000000</price_off> </prices><limit_type>hourly</limit_type> </base_resource> Where: label – name of the edge group assigned to the billing plan created_at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format limits – an array of limits set up for this resource limit_free - the number of IP Addresses users get for free limit - the total number of IP Addresses users get updated at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format billing_plan_id * - the ID of the billing plan id – resource ID resource_name – the name of the base resource. In this case it is IP address price_on- the price per IP Address for powered on Vms price_off - the price per IP Address for powered off VMs limit_type – hourly or monthly limit type set for the resource 42 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 3.15 Get VM monit details The number of VMs using Autoscaling a user can create for free as well as total amount of such VMs. You can also set the price for the VMs using Autoscaling (per VM). GET GET /billing_plans/:billing_plan_id/base_resources/:id.xml /billing_plans/:billing_plan_id/base_resources/:id.json You can check ID of the required base resource with GET method: GET /billing_plans/:billing_plan_id/base_resources.xml GET /billing_plans/:billing_plan_id/base_resources.json XML Output example <base_resource> <label>Monit</label> <created_at type="datetime">2012-03-15T16:14:03+02:00</created_at> <target_id nil="true"/> <limits> <limit_free>5</limit_free> <limit>10</limit> </limits> <updated_at type="datetime">2012-03-15T16:14:03+02:00</updated_at> <billing_plan_id type="integer">375</billing_plan_id> <id type="integer">1363</id> <unit nil="true"/> <resource_name>vm_monit</resource_name> <prices> <price>1.00000000</price> </prices> <limit_type>hourly</limit_type> </base_resource> Where: label – name of the edge group assigned to the billing plan created_at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format limits – an array of limits set up for this resource limit – maximum number of VM using Autoscaling limit_free - the number of VMs using Autoscaling a user can create for free updated at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format billing_plan_id * - the ID of the billing plan id – resource ID 43 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 resource_name – the name of the base resource. In this case it is monit price - price per VM limit_type – hourly or monthly limit type set for the resource 3.16 Get virtual machine details To see the limits set for a Virtual Machines resource: GET GET /billing_plans/:billing_plan_id/base_resources/:id.xml /billing_plans/:billing_plan_id/base_resources/:id.json You can check ID of the required base resource with GET method: GET /billing_plans/:billing_plan_id/base_resources.xml GET /billing_plans/:billing_plan_id/base_resources.json XML Output example <base_resource> <label>Virtual Machine</label> <created_at type="datetime">2012-03-15T16:19:27+02:00</created_at> <target_id nil="true"/> <limits> <limit_free>4</limit_free> <limit>10</limit> </limits> <updated_at type="datetime">2012-03-15T16:19:27+02:00</updated_at> <billing_plan_id type="integer">375</billing_plan_id> <id type="integer">1364</id> <unit nil="true"/> <resource_name>vm_limit</resource_name> <prices nil="true"/> <limit_type>hourly</limit_type> </base_resource> Where: label – name of the edge group assigned to the billing plan created_at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format limits – an array of limits set up for this resource limit_free - the number of Virtual Machines users can create for free limit - the total amount of virtual machines allowed 44 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 updated at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format billing_plan_id * - the ID of the billing plan id – resource ID resource_name – the name of the base resource. In this case it is virtual machine limit_type – hourly or monthly limit type set for the resource 3.17 Get template details GET GET /billing_plans/:billing_plan_id/base_resources/:id.xml /billing_plans/:billing_plan_id/base_resources/:id.json You can check ID of the required base resource with GET method: GET /billing_plans/:billing_plan_id/base_resources.xml GET /billing_plans/:billing_plan_id/base_resources.json XML Output example <base_resource> <label>Template</label> <created_at type="datetime">2012-03-15T16:27:37+02:00</created_at> <target_id nil="true"/> <limits> <limit_free>10</limit_free> <limit>30</limit> </limits> <updated_at type="datetime">2012-03-15T16:27:37+02:00</updated_at> <billing_plan_id type="integer">375</billing_plan_id> <id type="integer">1365</id> <unit>gb</unit> <resource_name>template</resource_name> <prices> <price>5.00000000</price> </prices> <limit_type>hourly</limit_type> </base_resource> Where: label – name of the edge group assigned to the billing plan created_at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format limits – an array of limits set up for this resource limit_free - the number of custom templates users can create for free 45 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 limit - the total amount of custom templates allowed updated at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format billing_plan_id * - the ID of the billing plan id – resource ID resource_name – the name of the base resource. In this case it is template price – price per template limit_type – hourly or monthly limit type set for the resource 3.18 Get template & backup storage details To get details about the disk space limits and prices allocated to Backups and Templates, use the following method: GET GET /billing_plans/:billing_plan_id/base_resources/:id.xml /billing_plans/:billing_plan_id/base_resources/:id.json You can check ID of the required base resource with GET method: GET /billing_plans/:billing_plan_id/base_resources.xml GET /billing_plans/:billing_plan_id/base_resources.json XML Output example <base_resource> <label>Templates & Backups Storage</label> <created_at type="datetime">2012-03-15T15:51:17+02:00</created_at> <target_id nil="true"/> <limits> <limit_free>4</limit_free> <limit>1000</limit> </limits> <updated_at type="datetime">2012-03-15T15:51:17+02:00</updated_at> <billing_plan_id type="integer">375</billing_plan_id> <id type="integer">1359</id> <unit>gb</unit> <resource_name>storage_disk_size</resource_name> <prices> <price>3.00000000</price> </prices> <limit_type>hourly</limit_type> </base_resource> Where: 46 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 label – name of the edge group assigned to the billing plan created_at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format limits – an array of limits set up for this resource limit_free - the amount of free disk space (in GB) users can allocate to store backups and templates together limit - the total disk space users can allocate to store backups and templates together updated at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format billing_plan_id * - the ID of the billing plan id – resource ID resource_name – the name of the base resource. In this case it is template & backup storage unit – a unit per which the price is set price - price per GB limit_type – hourly or monthly limit type set for the resource 3.19 Get backup details GET GET /billing_plans/:billing_plan_id/base_resources/:id.xml /billing_plans/:billing_plan_id/base_resources/:id.json You can check ID of the required base resource with GET method: GET /billing_plans/:billing_plan_id/base_resources.xml GET /billing_plans/:billing_plan_id/base_resources.json XML Output example <base_resource> <label>Backups</label> <created_at type="datetime">2012-03-15T16:37:56+02:00</created_at> <target_id nil="true"/> <limits> <limit_free>10</limit_free> <limit>50</limit> </limits> <updated_at type="datetime">2012-03-15T16:37:56+02:00</updated_at> <billing_plan_id type="integer">375</billing_plan_id> <id type="integer">1366</id> <unit>gb</unit> <resource_name>backup</resource_name> <prices> <price>5.00000000</price> 47 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 </prices> <limit_type>hourly</limit_type> </base_resource> Where: label – name of the edge group assigned to the billing plan created_at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format limits – an array of limits set up for this resource limit_free - the number of backups users can create for free limit - the total amount of backups allowed updated at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format billing_plan_id * - the ID of the billing plan id – resource ID resource_name – the name of the base resource. In this case it is backup unit – a unit per which the price is set price – price per backup limit_type – hourly or monthly limit type set for the resource 3.20 Get template groups details GET GET /billing_plans/:billing_plan_id/base_resources/:id.xml /billing_plans/:billing_plan_id/base_resources/:id.json You can check ID of the required base resource with GET method: GET /billing_plans/:billing_plan_id/base_resources.xml GET /billing_plans/:billing_plan_id/base_resources.json XML Output example <base_resource> <label>az_TG</label> <created_at type="datetime">2012-03-15T16:56:27+02:00</created_at> <target_id type="integer">29</target_id> <limits nil="true"/> <updated_at type="datetime">2012-03-15T16:56:27+02:00</updated_at> 48 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 <billing_plan_id type="integer">375</billing_plan_id> <id type="integer">1368</id> <unit nil="true"/> <resource_name>template_group</resource_name> <prices nil="true"/> <limit_type>hourly</limit_type> </base_resource> Where: label - the name of the template group you set as a limit to the current billing plan created_at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format target_id – the id of the template group updated at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format billing_plan_id * - the ID of the billing plan id – resource ID resource_name – the name of the base resource. In this case it is template group limit_type – hourly or monthly limit type set for the resource When you add a template group to a billing plan, you limit the number of preconfigured system templates available to a user signed up for this billing plan – they can only choose from templates available in that template group. 3.21 Get hypervisor zones details GET GET /billing_plans/:billing_plan_id/base_resources/:id.xml /billing_plans/:billing_plan_id/base_resources/:id.json You can check ID of the required base resource with GET method: GET /billing_plans/:billing_plan_id/base_resources.xml GET /billing_plans/:billing_plan_id/base_resources.json XML Output example <base_resource> <label>hvz</label> <created_at type="datetime">2012-03-15T16:59:18+02:00</created_at> 49 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 <target_id type="integer">1</target_id> <limits nil="true"/> <updated_at type="datetime">2012-03-15T16:59:18+02:00</updated_at> <billing_plan_id type="integer">375</billing_plan_id> <id type="integer">1369</id> <unit nil="true"/> <resource_name>hypervisor_group</resource_name> <prices nil="true"/> <limit_type>hourly</limit_type> </base_resource> Where: label - the name of the hypervisor zone you set as a limit to the current billing plan created_at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format target_id – the id of the hypervisor zone updated at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format billing_plan_id * - the ID of the billing plan id – resource ID resource_name – the name of the base resource. In this case it is hypervisor zone limit_type – hourly or monthly limit type set for the resource By adding hypervisor zone resources to a billing plan, you limit the user only to the hypervisors in that zone. 3.22 Get data store zone details GET GET /billing_plans/:billing_plan_id/base_resources/:id.xml /billing_plans/:billing_plan_id/base_resources/:id.json You can check ID of the required base resource with GET method: GET /billing_plans/:billing_plan_id/base_resources.xml GET /billing_plans/:billing_plan_id/base_resources.json XML Output example: <base_resource> <label>dsz</label> <created_at type="datetime">2012-03-15T17:05:33+02:00</created_at> <target_id type="integer">2</target_id> <limits> <limit_reads_completed_free>20</limit_reads_completed_free> 50 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 <limit_data_written_free>30</limit_data_written_free> <limit_data_read_free>30</limit_data_read_free> <limit_free>60</limit_free> <limit_writes_completed_free>20</limit_writes_completed_free> </limits> <updated_at type="datetime">2012-03-15T17:05:33+02:00</updated_at> <billing_plan_id type="integer">375</billing_plan_id> <id type="integer">1370</id> <unit>gb</unit> <resource_name>data_store_group</resource_name> <prices> <price_writes_completed>1.00000000</price_writes_completed> <price_reads_completed>1.00000000</price_reads_completed> <price_on>1.00000000</price_on> <price_data_written>1.00000000</price_data_written> <price_off>1.00000000</price_off> <price_data_read>1.00000000</price_data_read> </prices> <limit_type>hourly</limit_type> </base_resource> Where: label - the name of the hypervisor zone you set as a limit to the current billing plan created_at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format target_id – the id of the data store zone limits – an array of limits set up for this resource limit_free – free disk space on data store zone limit – maximum available disk space limit_data_written_free - the amount of data users get for free for write operations (in GB) limit_data_read_free - the amount of data users get for free for read operations (in GB) limit_reads_completed_free - the maximum number (in millions) of Input requests which can happen at once limit_writes_completed_free - the maximum number (in millions) of Output requests which can happen at once updated at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format billing_plan_id * - the ID of the billing plan id – resource ID resource_name – the name of the base resource. In this case it is data store zone 51 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 price_data_read – price per GB of data for read operations price_data_written - price per GB of data for write operations price_on – price per GB of disk size, when VM is on price_off - price per GB of disk size, when VM is off price_writes_completed – price per million of Output requests which can happen at once price_reads_completed - price per million of Input requests which can happen at once limit_type – hourly or monthly limit type set for the resource 3.23 Get network zone details GET GET /billing_plans/:billing_plan_id/base_resources/:id.xml /billing_plans/:billing_plan_id/base_resources/:id.json You can check ID of the required base resource with GET method: GET /billing_plans/:billing_plan_id/base_resources.xml GET /billing_plans/:billing_plan_id/base_resources.json XML Output example <base_resource> <label>ntz</label> <created_at type="datetime">2012-03-15T17:13:40+02:00</created_at> <target_id type="integer">3</target_id> <limits> <limit_data_received_free>10</limit_data_received_free> <limit_rate>20</limit_rate> <limit_data_sent_free>10</limit_data_sent_free> <limit_rate_free>10</limit_rate_free> <limit_ip>10</limit_ip> <limit_ip_free>5</limit_ip_free> </limits> <updated_at type="datetime">2012-03-15T17:13:40+02:00</updated_at> <billing_plan_id type="integer">375</billing_plan_id> <id type="integer">1371</id> <unit>gb</unit> <resource_name>network_group</resource_name> <prices> <price_data_received>1.00000000</price_data_received> <price_ip_off>1.00000000</price_ip_off> <price_rate_off>1.00000000</price_rate_off> <price_ip_on>1.00000000</price_ip_on> <price_data_sent>1.00000000</price_data_sent> <price_rate_on>1.00000000</price_rate_on> </prices> <limit_type>hourly</limit_type> </base_resource> 52 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 Where: label - the name of the hypervisor zone you set as a limit to the current billing plan created_at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format target_id – the id of the data store zone limits – an array of limits set up for this resource limit_ip - the total amount of IP addresses limit_ip_free - the amount of IP addresses users get for free limit_data_sent_free - the amount of data users can send for free limit_data_received_free - the amount of data users can receive for free limit_rate - the total available port speed users limit_rate_free - the port speed users get for free updated at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format billing_plan_id * - the ID of the billing plan id – resource ID resource_name – the name of the base resource. In this case it is network zone price_ip_on – price per IP when VM is on price_ip_off - price per IP when VM is off price_rate_on – price for port speed (Mbps) when VM is on price_rate_off - price for port speed (Mbps) when VM is off price_data_sent – price for sent data per GB per hour price_data_received – price for received data per GB per hour limit_type – hourly or monthly limit type set for the resource 53 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 3.24 Get edge group details To get details about the backup server zone limits and prices, use the following method: GET GET /billing_plans/:billing_plan_id/base_resources/:id.xml /billing_plans/:billing_plan_id/base_resources/:id.json You can check ID of the required base resource with GET method: GET /billing_plans/:billing_plan_id/base_resources.xml GET /billing_plans/:billing_plan_id/base_resources.json XML Output example <base_resource> <label>WHMCS Edge Group</label> <resource_name>backup_server_group</resource_name> <created_at type="datetime">2012-03-15T18:08:57+02:00-09T09:48:21Z</created_at> <target_id type="integer">30</target_id> <limits> <limit_free type="integer">0</limit_free> </limits> <updated_at type="datetime">2012-03-15T18:08:57+02:00</updated_at> <billing_plan_id type="integer">375</billing_plan_id> <id type="integer">1374</id> <unit>gb</unit> <resource_name>edge_group</resource_name> <prices> <price>2.00000000</price> </prices> <limit_type>hourly</limit_type> </base_resource Where: label – name of the edge group assigned to the billing plan created_at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format target_id – backup server zone id limits – an array of limits set up for this resource limit_ free –the number of GB user gets for free updated at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format billing_plan_id * - the ID of the billing plan resource_name – the name of the base resource. In this case it is edge group 54 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 id – resource ID unit – a unit per which the price is set price – price per GB over limit limit_type – hourly or monthly limit type set for the resource 3.25 Get backup server zone details To get details of the backup server zone limits and prices, use the following method: GET GET /billing_plans/:billing_plan_id/base_resources/:id.xml /billing_plans/:billing_plan_id/base_resources/:id.json You can check ID of the required base resource with GET method: GET /billing_plans/:billing_plan_id/base_resources.xml GET /billing_plans/:billing_plan_id/base_resources.json XML Output example <base_resource> <label>bsz</label> <created_at type="datetime">2012-03-15T17:38:14+02:00</created_at> <target_id type="integer">28</target_id> <limits> <limit_backup_free>200</limit_backup_free> <limit_backup_disk_size_free>50200</limit_backup_disk_size_free> <limit_template_disk_size>100150</limit_template_disk_size> <limit_template>2070</limit_template> <limit_template_free>530</limit_template_free> <limit_backup_disk_size>100</limit_backup_disk_size> <limit_backup>40</limit_backup> <limit_backup_disk_size>450</limit_backup_disk_size> <limit_backup/> <limit_template_disk_size_free>50</limit_template_disk_size_free> <limit_backup_free>20</limit<updated_at type="datetime">2012-0209T09:48:21Z</updated_at> <id type="integer">787</id> <prices><price_backup_free>1.00000000</price_backup> </limits> <updated_at type="datetime">2012-03-15T17:38:14+02:00</updated_at> <billing_plan_id type="integer">375</billing_plan_id> <id type="integer">1372</id> <unit>gb</unit> <resource_name>backup_server_group</resource_name> <prices> <price_backup_disk_size>1.00000000</price_backup_disk_size> <price_template_disk_size>1.00000000</price_template_disk_size> <price_template>1.00000000</price_template> <price_backup>1.00000000</price_backup> </prices> <limit_type>hourly</limit_type> </base_resource> 55 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 Where: label – name of the backup server zone assigned to the billing plan resource_name – the name of the base resource. In this case it is backup server group. created at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format target_id – backup server zone id limits – an array of limits set up for this resource limit_backup_free –the number of backups user gets for free limit_backup – the total number of backups allowed limit_backup_disk_size_free –disk size user gets for free to store their backups limit_backup_disk_size – maximum backup disk size allowed limit_template_disk_size – maximum template disk size allowed limit_template – the total number of templates allowed limit_template_free –the number of templates user gets for free limit_template_disk_size_free – template disk size user gets for free updated at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format billing_plan_id * - the ID of the billing plan id – resource ID unit – a unit per which the price is set price_backup – price per backup over limit price_template – price per template over limit price_template_disk_size – price per GB of template disk size over limit. limit_ type – hourly or monthly limit type set for the resource 56 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 4. Currencies This class allows you to set up the currency for your payments. There are four currencies in a default installation: USD, EUR, GBP and JPY. You can add more currencies at any time. 4.1 Get the list of currencies To get the list of available currencies, use the following request: GET GET /settings/currencies.xml /settings/currencies.json XML Output example <?xml version="1.0" encoding="UTF-8"?> <currencies> <currency> <name>United States dollar</name> <format>%u%n</format> <created_at>2011-03-02T12:09:36+02:00</created_at> <code>USD</code> <updated_at>2011-03-22T16:12:41+02:00</updated_at> <id>1</id> <unit>$</unit> <separator>.</separator> <precision>5</precision> <precision_for_unit>2</precision_for_unit> <delimiter>,</delimiter> </currency> </currencies> Where: name – the currency label format - how the currency is displayed in the control panel. The following parameters are used: %n ( for the digits), %u ( for the currency symbol) created_at – the date when the record in DB was added updated_at – the date when the record in DB was updated code - three-character currency code that is generally used to represent the currency id – the ID of the currency unit – a currency symbol separator - a character used to format decimal numbers, e.g 100.99 precision - the number of digits after the delimiter. This parameter is used when showing the costs total for a certain period, e.g. Outstanding amount, Total Cost, Payments. 57 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 precision_per_unit - the number of digits after the delimiter. The precision per unit parameter is used to display the prices for the resources , e.g. for CPU, Disk size, RAM, IP, Data stores, Edge servers, Disks, Backups, Templates, etc. delimiter - a grouping character used to separate thousands, e.g: 100,000,000. 4.2 Get currency details To get details for a particular currency, use the following request: GET GET /settings/currencies/:id.xml /settings/currencies/:id.json XML Output example <?xml version="1.0" encoding="UTF-8"?> <currency> <name>British pound</name> <format>%u%n</format> <created_at>2011-03-02T12:09:36+02:00</created_at> <code>GBP</code> <updated_at>2011-03-22T15:31:10+02:00</updated_at> <id>2</id> <unit>£</unit> <separator>.</separator> <precision>1</precision> <precision_for_unit>2</precision_for_unit> <delimiter>,</delimiter> </currency> Where: name – the currency label format - how the currency is displayed in the control panel. The following parameters are used: %n ( for the digits), %u ( for the currency symbol) created_at – the date when the record in DB was added updated_at – the date when the record in DB was updated code - three-character currency code that is generally used to represent the currency id – the ID of the currency unit – a currency symbol separator - a character used to format decimal numbers, e.g 100.99 58 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 precision - the number of digits after the delimiter. This parameter is used when showing the costs total for a certain period, e.g. Outstanding amount, Total Cost, Payments. precision_per_unit - the number of digits after the delimiter. The precision per unit parameter is used to display the prices for the resources , e.g. for CPU, Disk size, RAM, IP, Data stores, Edge servers, Disks, Backups, Templates, etc. delimiter - a grouping character used to separate thousands, e.g: 100,000,000. 4.3 Edit currencies To edit details of a currency, use the following request: PUT PUT /settings/currencies/:id.xml /settings/currencies/:id.json XML Request example curl -i -X PUT -u user:userpass -H 'Accept: application/xml' -H 'Content-type: application/xml' -d '<currency><name>British_changed</name><unit>§</unit><format>%n%u</format><separator>. </separator><precision>2</precision><precision_for_unit>4</precision_for_unit><delimit er>,</delimiter></currency>' --url http://onapp.test/settings/currencies/:id.xml JSON Request example curl -i -X PUT -u user:userpass -H 'Accept: application/json' -H 'Content-type: application/json' -d '{"currency":{"name":"British_changed","unit":"§","format":"%n%u","separator":".","pre cision":"4", "precision_for_unit":"4","delimiter":","}}' --url http://onapp.test/settings/currencies/:id.json Parameters: name – the currency label unit – a currency symbol ($, €, £, etc. ) format - how the currency is displayed in the control panel. The following parameters are used: %n ( for the digits), %u ( for the currency symbol) code - three-character currency code that is generally used to represent the currency separator - a character used to format decimal numbers, e.g 100.99 precision - the number of digits after the delimiter to display the costs precision_for_unit – the numberof digits after the delimiter to display the prices for resources delimiter - a grouping character used to separate thousands, e.g: 100,000,000. 59 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 4.4 Add a currency To add a currency, use the following request: POST POST /settings/currencies.xml /settings/currencies.json XML Request example curl -i -X POST -u user:userpass -H 'Accept: application/xml' -H 'Content-type: application/xml' -d '<currency><name>Ukreinian Gruvna</name><unit>§</unit><format>%n%u</format><code>UAH</code><separator>.</separato r><precision>2</precision><precision_for_unit>4</precision_for_unit><delimiter>,</deli miter></currency>' --url http://onapp.test/settings/currencies.xml JSON Request example curl -i -X POST -u user:userpass -H 'Accept: application/json' -H 'Content-type: application/json' -d '{"currency":{"name":"Polski Zloti","unit":"§","format":"%n%u","code":"POZ","separator":".","precision":"4","precis ion_for_unit":"4","delimiter":","}}' --url http://onapp.test/settings/currencies.json Parameters: name *– the currency label unit * – a currency symbol ($, €, £, etc. ) format * - how the currency is displayed in the control panel. The following parameters are used: %n ( for the digits), %u ( for the currency symbol) code * - three-character currency code that is generally used to represent the currency separator * - a character used to format decimal numbers, e.g.: 100.99 precision * - the number of digits after the delimiter to display the costs precision_for_unit – the numberof digits after the delimiter to display the prices for resources delimiter * - a grouping character used to separate thousands, e.g.: 100,000,000. JSON Output example {"currency":{"name":"Polski Zloti","created_at":"2011-0419T17:20:26+03:00","format":"%n%u","code":"POZ","updated_at":"2011-0419T17:20:26+03:00","id":7,"unit":"§","separator":".","precision":4,"delimiter":","}} 60 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 4.5 Delete a currency To delete a currency, use the following request: DELETE DELETE /settings/currencies/:id.xml /settings/currencies/:id.json XML Request example curl -i -X DELETE -u user:userpass --url http://onapp.test/settings/currencies/:id.xml JSON Request example curl -i -X DELETE -u user:userpass --url http://onapp.test/settings/currencies/:id.json 61 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 5. Users This class manages user accounts created in the cloud. It enables you to set up different types of user and allocate their role. Roles define user access to cloud resources and functions, including managing virtual machines and hypervisors, performing actions on templates and backups, and configuring data stores and networks. 5.1 Get the list of users To see all the users registered in the cloud with their detailed information, use the following request: GET GET /users.xml /users.json XML Output example <?xml version="1.0" encoding="UTF-8"?> <users type="array"> <user> <activated_at type="datetime">2011-10-10T12:14:59+03:00</activated_at> <aflexi_key nil="true"></aflexi_key> <aflexi_password>KDMoN9Rfbrp6</aflexi_password> <aflexi_user_id type="integer">233653482</aflexi_user_id> <aflexi_username>onapp-pub-1-4abed1fcf6125d18d8bb36fe61d25de9</aflexi_username> <billing_plan_id type="integer">10</billing_plan_id> <cdn_account_status>ACTIVE</cdn_account_status> <cdn_status>ACTIVE</cdn_status> <created_at type="datetime">2011-10-10T12:14:59+03:00</created_at> <deleted_at nil="true"></deleted_at> <email>[email protected]</email> <first_name>John</first_name> <group_id nil="true"></group_id> <id type="integer">1</id> <image_template_group_id nil="true"></image_template_group_id> <last_name>Smith</last_name> <locale>en</locale> <login>admin</login> <additional_fields type="array"> <additional_field> <value>0</value> <name>test_additional_field</name> </additional_field> <status>active</status> <suspend_at nil="true"></suspend_at> <time_zone>Kyiv</time_zone> <update_billing_stat type="boolean">false</update_billing_stat> <updated_at type="datetime">2011-11-10T16:39:50+03:00</updated_at> <user_group_id nil="true"></user_group_id> <outstanding_amount type="float">253.0799946785</outstanding_amount> <payment_amount type="decimal">0.0</payment_amount> <total_amount type="float">253.0799946785</total_amount> <roles type="array"> <role> <created_at type="datetime">2011-10-10T12:14:57+03:00</created_at> <id type="integer">1</id> 62 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 <identifier>admin</identifier> <label>Administrator</label> <updated_at type="datetime">2011-11-03T16:09:10+03:00</updated_at> <permissions type="array"> <permission> <created_at type="datetime">2011-10-10T12:14:58+03:00</created_at> <id type="integer">267</id> <identifier>autobackup_templates</identifier> <label>Any action on autobackup templates</label> <updated_at type="datetime">2011-10-10T12:14:58+03:00</updated_at> </permission> ... <permission></permission> ... <permissions> </role> </roles> <used_cpus type="integer">0</used_cpus> <used_memory type="integer">0</used_memory> <used_cpu_shares type="integer">0</used_cpu_shares> <used_disk_size type="integer">0</used_disk_size> <used_ip_addresses type="array"/> <memory_available type="integer">15129</memory_available> <disk_space_available type="integer">1375</disk_space_available> </user> ... <user></user> ... </users> Where: activated_at – time when the user was activated additional field – user additional field, where: • • value – the additional field value name – the additional field title aflexi_key — user's Aflexi key, if any aflexi_password — user's password to Aflexi database aflexi_user_id — user's ID in the Aflexi database aflexi_username — username of the user in Aflexi billing_plan_id – ID of the billing plan assigned to this user cdn_account_status — always returns ACTIVE status; but it is actually activated when CDN was enabled for particular user, and aflexi_user_id parameter has a value created_at – time when the user was created, in [YYYY][MM][DD]T[hh][mm][ss]Z 63 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 deleted_at – time when the user was deleted email – user’s email first_name – user’s first name id — the ID of a user in the database image_template_group — the ID of associated template group, if any last_name — the user's last name locale — locale (language) associated with user login — user's login name status – status of the user’s account (active, suspended or deleted) suspend_at – time when the system should suspend a user time_zone — the time zone of the user updated_at — time when user's profile data was updated user_group_id – ID of the user group assigned to this user outstanding_amount – the amount of money the user is due to pay payment_amount – amount of money the user has actually paid total_amount – sum total of outstanding and payment amount roles — an array of user roles to which this account is assigned to, where • • • • label – role title id – role ID identifier – role identifier permissions – an array with permissions assigned to this role o label – permission title o id – permission ID o identifier – permission identifier used_cpus — number of CPU cores allocated to all VMs and edge servers of the user used_disk_size – size of all user disks in GB used_memory – the amount of RAM used by the user (MB) used_cpus – the amount of CPUs used by the user 64 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 used_ip_addresses – an array of IP addresses associated with the user memory_available — the amount of RAM available to this user (MB) disk_space_available – disk space available for the user (GB) 5.2 Get user details To get details for a particular user account: GET GET /users/:id.xml /users/:id.json For details and output example refer to Get the list of users 5.3 Create a user Use the POST method to create a new user account: POST POST /users.xml /users.json XML Request example curl -i -X POST -d '<user><login>111111losj</login><email>[email protected]</email><first_name>Te stApiName</first_name><last_name>TestAPIName</last_name><password>password_test1</pass word><user_group_id>1</user_group_id><billing_plan_id>1</billing_plan_id><role_ids type="array"><role_id>1</role_id></role_ids><additional_fields type="array"><additional_field><name>additional_field_name</name><value>custom_value</ value></additional_field></additional_fields><time_zone>Kyiv</time_zone><locale>en</lo cale></user>' -u user:userpass http://onapp.test/users.xml -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X POST -d '{"user":{"login":"111111losj","email":"[email protected]","first_name":"1111","la st_name":"1311","password":"password_test1","user_group_id":"1","billing_plan_id":"1", "role_ids":["1","2"]}}', "additional_fields ":[{"additional_field":{"name":"additional_field_name","value":"custom_value"}}]}}' -u user:userpass http://onapp.test/users.json -H 'Accept: application/json' -H 'Contenttype: application/json' Returns HTTP 201 on successful creation, or HTTP 422 if a user with such a login/email already exists. Required parameters: email * - user’s email address first_name * - user’s first name 65 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 last_name * - user’s last name login * - login of the user. It can consist of 4-40 characters, letters [A-Za-z], digits [0-9], dash [ - ], lower dash [ _ ], [@]. You can use both lower- and uppercase letters password * - user’s password. (min – 6 characters) Optional parameters: role – assigns a role to a user time_zone - time zone of the user. Set by default locale - local of the user. Set by default status – user’s status (active, suspended, etc) billing_plan_id – set by default, if not selected additional field – an array of custom fields assigned to the user, where: o o name: the name of a particular additional field value:the value which you want to assign to this additional field role_ids – ID of the role, assigned to the user user_group_id – ID of the group, to which the user is attached suspend_after_hours – time in hours, after which the user will be suspended suspend_at – time in [YYYY][MM][DD] T[hh][mm][ss]Z format, when the user will be suspended 5.4 Edit a user To edit a user, use this request: PUT PUT /users/:id.xml /users/:id.json XML Request example curl -i -X PUT -d '<user><email>[email protected]</email><first_name>NewName</first_name><last_name>N ewLastName</last_name><password>qwe123</password><user_group_id>36</user_group_id><bil ling_plan_id>2</billing_plan_id><role_ids type="array"><role_id>1</role_id><additional_fields type="array"><additional_field><name>additional_field_name</name><value>custom_value</ value></additional_field></additional_fields><suspend_at>2011-08-01 12:47:08</suspend_at></user>' -u user:userpass http://onapp.test/users/:id.xml -H 'Accept: application/xml' -H 'Content-type: application/xml' 66 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 JSON Request example curl -i -X PUT -d '{"user":{"email":"[email protected]","first_name":"jsonNewName","last_name":"j sonNewLastName","password":"qwe123","user_group_id":"37","billing_plan_id":"3","role_i ds":["1","2"]}}',"additional_fields type='array'":[{"additional_field":{"name":"additional_field_name","value":"custom_val ue"}}]}}',"suspend_at":"2011-08-01 12:47:10"}}' -u user:userpass http://onapp.test/users/:id.json -H 'Accept: application/json' -H 'Content-type: application/json' Where you can edit: user email; password; first_name and last_name; user_group, associated with the user ; additional field and its value; billing_plan; assigned role (or roles) and auto-suspend (suspend_at) parameters. To disable user auto-suspending, leave the suspend_at field empty. Users with an API key instead of a password are not allowed to see their login and change their password. 5.5 Generate API key Use the following request to generate a new API key: POST POST /users/:id/make_new_api_key.xml /users/:id/make_new_api_key.json XML Request example curl -i -X POST -u user:userpass http://onapp.test/users/:id/make_new_api_key.xml -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X POST -u user:userpass http://onapp.test/users/:id/make_new_api_key.json -H 'Accept: application/json' -H 'Content-type: application/json' XML Output example curl -i -X POST -u admin:dev5dot130 http://109.123.105.130/users/1033/make_new_api_key.xml -H 'Accept: application/xml' -H 'Content-type: application/xml' HTTP/1.1 200 OK Date: Mon, 19 Dec 2011 11:45:25 GMT Server: Apache/2.2.3 (CentOS) X-Powered-By: Phusion Passenger (mod_rails/mod_rack) 3.0.1 ETag: "781538aa145a713491a2a87b7c61e989" X-UA-Compatible: IE=Edge,chrome=1 67 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 X-Runtime: 0.436403 Cache-Control: max-age=0, private, must-revalidate Set-Cookie: _session_id=a0f5aa6334b23a1c012bcde1a06a83a7; path=/; HttpOnly Status: 200 Connection: close Transfer-Encoding: chunked Content-Type: application/xml; charset=utf-8 <?xml version="1.0" encoding="UTF-8"?> <user> <used_cpus type="integer">0</used_cpus> <aflexi_user_id nil="true"></aflexi_user_id> <payment_amount type="decimal">0.0</payment_amount> <created_at type="datetime">2011-12-19T11:41:17Z</created_at> <activated_at type="datetime">2011-12-19T11:41:17Z</activated_at> <used_cpu_shares type="integer">0</used_cpu_shares> <suspend_at nil="true"></suspend_at> <remember_token_expires_at nil="true"></remember_token_expires_at> <cdn_account_status>ACTIVE</cdn_account_status> <aflexi_password nil="true"></aflexi_password> <updated_at type="datetime">2011-12-19T11:45:25Z</updated_at> <deleted_at nil="true"></deleted_at> <cdn_status>INACTIVE</cdn_status> <billing_plan_id type="integer">1</billing_plan_id> <api_key>939751c7b98798df9fc127a69884a5d2ac499b9f</api_key> <update_billing_stat type="boolean">false</update_billing_stat> ... 68 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 5.6 Suspend a user To suspend a user account, use the following method: POST POST /users/:id/suspend.xml /users/:id/suspend.json XML Request example curl -i -X GET -u user:userpass http://onapp.test/users/:id/suspend.xml -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X GET -u user:userpass http://onapp.test/users/:id/suspend.json -H 'Accept: application/json' -H 'Content-type: application/json' 5.7 Activate a user To activate a suspended user account, use the following method: POST POST /users/:id/activate_user.xml /users/:id/activate_user.json XML Request example curl -i -X GET -u user:userpass http://onapp.test/users/:id/activate.xml -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X GET -u user:userpass http://onapp.test/users/:id/activate.json -H 'Accept: application/json' -H 'Content-type: application/json' 5.8 Delete a user Use the DELETE method to remove a user account from the cloud: DELETE DELETE /users/:id.xml /users/:id.json XML Request example curl -i -X DELETE -u user:userpass http://onapp.test/users/:id.xml -H 'Accept: application/xml' -H 'Content-type: application/xml' 69 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 JSON Request example curl -i -X DELETE -u user:userpass http://onapp.test/users/:id.json -H 'Accept: application/json' -H 'Content-type: application/json' Returns HTTP 200 response on successful deletion, or HTTP 404 when a user with the ID specified is not found. When you delete a user their status becomes DELETED, so they cannot perform any actions on their VMs; however, statistics, backups and billing details are still available for Administrator. To completely erase a user from the system, run DELETE /users/:id again. 5.9 View user’s statistics User’s statistics show the summary of the resources used by a particular user and their costs (which are set in the billing plan assigned to the user). To see the statistics, use this API call: GET onapp.test/users/:user_id/user_statistics.xml GET onapp.test/users/:user_id/user_statistics.json XML Output example <?xml version="1.0" encoding="UTF-8"?> <user_stat> <backup_count_cost type="float">0.0</backup_count_cost> <currency_code>USD</currency_code> <total_cost type="float">96500.0004196997</total_cost> <user_resources_cost type="float">96500.0004196997</user_resources_cost> <template_count_cost type="float">0.0</template_count_cost> <storage_disk_size_cost type="float">0.0</storage_disk_size_cost> <edge_group_cost type="float">0.00041969971744038</edge_group_cost> <backup_cost type="float">96500.0</backup_cost> <template_cost type="float">0.0</template_cost> <user_id type="integer">1</user_id> <backup_disk_size_cost type="float">0.0</backup_disk_size_cost> <monit_cost type="float">0.0</monit_cost> <stat_time nil="true"></stat_time> <template_disk_size_cost type="float">0.0</template_disk_size_cost> <vm_cost type="float">0.0</vm_cost> <vm_stats type="array"> <vm_stat> <total_cost type="float">0.0</total_cost> <virtual_machine_id type="integer">0</virtual_machine_id> <usage_cost type="float">0.0</usage_cost> <vm_resources_cost type="float">0.0</vm_resources_cost> </vm_stat> </vm_stats> </user_stat> Where: 70 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 vm_stat – billing statistics on virtual machines, owned by the user virtual_machine _id – ID of the VM, for which this statistics are generated total_cost – sum total of VM costs (usage_cost + vm_resource_cost) usage_cost –costs for actual usage of the VM vm_resource_cost – cost for the resources, which VM is using (cpu, cpu priority, RAM, disk size, IP addresses) backup_count_cost - cost per backup per hour for the backups of a particular Backup server zone. The price is set by the Limits for backup server zone. backup_disk_size_cost - cost per GB per hour for the backups of a particular Backup server zone. The price is set by the Limits for backup server zone. backup_cost – cost per backup per hour currency_code - the currency set for this user template_count_cost - cost per template per hour for the templates of a particular Backup server zone. The price is set by the Limits for backup server zone. template_disk_size_cost - cost per GB per hour for the templates of a particular Backup server zone. template_cost — total template costs (cost per template per hour) edge_group_cost - total edge group costs user_id - the ID of the user for whom the statistics are generated stat_time - a particular point of time for which these statistics are generated storage_disk_size_cost – costs for disk size used for backups/templates storage (cost per GB per hour) user_resources_cost — sum total of all backups/templates/monitis monitors costs (backup_cost+storage_disk_size_cost+template_cost+monit_cost) total_cost — overall sum total of all costs (vm_cost+user_resources_cost) monit_cost – total costs for VMs using monitis monitors (cost for VM per hour) vm_cost – total VMs costs (sum total of all user VMs) 5.10 View user's statistics for a particular period To view the hourly cost and amount of the resources used by a user: 71 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 GET /users/:user_id/user_statistics.xml?hourly_stats GET /users/:user_id/user_statistics.json?hourly_stats XML request example: curl -i -X GET -H 'Accept: application/xml' -H 'Content-type: application/xml' -u user:userpass http://onapp.test/users/:user_id/user_statistics.xml?hourly_stats JSON request example: curl -i -X GET -H 'Accept: application/json' -H 'Content-type: application/json' -u user:userpass http://onapp.test/users/:user_id/user_statistics.json?hourly_stats XML Output example: <?xml version="1.0" encoding="UTF-8"?> <user_stats type="array"> <user_stat> <backup_count_cost type="float">0.0</backup_count_cost> <user_resources_cost type="float">0.0</user_resources_cost> <currency_code>USD</currency_code> <total_cost type="float">0.0</total_cost> <template_count_cost type="float">0.0</template_count_cost> <storage_disk_size_cost type="float">0.0</storage_disk_size_cost> <edge_group_cost type="float">0.0</edge_group_cost> <backup_cost type="float">0.0</backup_cost> <template_cost type="float">0.0</template_cost> <user_id type="integer">4</user_id> <backup_disk_size_cost type="float">0.0</backup_disk_size_cost> <monit_cost type="float">0.0</monit_cost> <stat_time type="datetime">2012-03-13T11:43:36Z</stat_time> <template_disk_size_cost type="float">0.0</template_disk_size_cost> <vm_cost type="integer">0</vm_cost> <vm_stats type="array"/> </user_stat> <user_stat> <backup_count_cost type="float">0.0</backup_count_cost> <user_resources_cost type="float">0.0</user_resources_cost> <currency_code>USD</currency_code> <total_cost type="float">0.0</total_cost> <template_count_cost type="float">0.0</template_count_cost> <storage_disk_size_cost type="float">0.0</storage_disk_size_cost> <edge_group_cost type="float">0.0</edge_group_cost> <backup_cost type="float">0.0</backup_cost> <template_cost type="float">0.0</template_cost> <user_id type="integer">4</user_id> <backup_disk_size_cost type="float">0.0</backup_disk_size_cost> <monit_cost type="float">0.0</monit_cost> <stat_time type="datetime">2012-03-13T12:43:37Z</stat_time> <template_disk_size_cost type="float">0.0</template_disk_size_cost> <vm_cost type="integer">0</vm_cost> <vm_stats type="array"/> </user_stat> ... </user_stats> 72 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 For parameters description, refer to View user's statistics section. To view the cost and amount of the resources used for a particular period: GET /users/:user_id/user_statistics.xml?hourly_stats&period[startdate]=YYYYMM-DD+hh%3Amm%3Ass&period[enddate]=YYYY-MM-DD+hh%3Amm%3Ass GET /users/:user_id/user_statistics.json?hourly_stats&period[startdate]=YYYYMM-DD+hh%3Amm%3Ass&period[enddate]=YYYY-MM-DD+hh%3Amm%3Ass XML request example: curl -i -X GET -H 'Accept: application/xml' -H 'Content-type: application/xml' -u user:userpass "http://onapp.test/users/:user_id/user_statistics.xml?hourly_stats&period[startdate]=2 012-03-15+06:58:16&period[enddate]=2012-03-15+08:58:16" JSON request example: curl -i -X GET -H 'Accept: application/json' -H 'Content-type: application/json' -u user:userpass "http://onapp.test/users/:user_id/user_statistics.json?hourly_stats&period[startdate]= 2012-03-15+06:58:16&period[enddate]=2012-03-15+08:58:16" XML Output example: <?xml version="1.0" encoding="UTF-8"?> <user_stats type="array"> <user_stat> <backup_count_cost type="float">0.0</backup_count_cost> <user_resources_cost type="float">0.0</user_resources_cost> <currency_code>USD</currency_code> <total_cost type="float">0.0</total_cost> <template_count_cost type="float">0.0</template_count_cost> <storage_disk_size_cost type="float">0.0</storage_disk_size_cost> <edge_group_cost type="float">0.0</edge_group_cost> <backup_cost type="float">0.0</backup_cost> <template_cost type="float">0.0</template_cost> <user_id type="integer">4</user_id> <backup_disk_size_cost type="float">0.0</backup_disk_size_cost> <monit_cost type="float">0.0</monit_cost> <stat_time type="datetime">2012-03-15T06:58:16Z</stat_time> <template_disk_size_cost type="float">0.0</template_disk_size_cost> <vm_cost type="integer">0</vm_cost> <vm_stats type="array"/> </user_stat> <user_stat> <backup_count_cost type="float">0.0</backup_count_cost> <user_resources_cost type="float">0.0</user_resources_cost> <currency_code>USD</currency_code> <total_cost type="float">0.0</total_cost> <template_count_cost type="float">0.0</template_count_cost> <storage_disk_size_cost type="float">0.0</storage_disk_size_cost> <edge_group_cost type="float">0.0</edge_group_cost> <backup_cost type="float">0.0</backup_cost> <template_cost type="float">0.0</template_cost> <user_id type="integer">4</user_id> 73 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 <backup_disk_size_cost type="float">0.0</backup_disk_size_cost> <monit_cost type="float">0.0</monit_cost> <stat_time type="datetime">2012-03-15T07:58:17Z</stat_time> <template_disk_size_cost type="float">0.0</template_disk_size_cost> <vm_cost type="integer">0</vm_cost> <vm_stats type="array"/> </user_stat> </user_stats> For parameters description, refer to View user's statistics section. 5.11 View billing statistics for a user To view billing statistics for a particular user, use the following method: GET /users/:user_id/vm_stats.xml GET /users/:user_id/vm_stats.json If the account was created less than three months ago, the statistics are generated for the entire period of operation of the account. You can also define a shorter period by setting Start and End time in the API call: GET /users/:user_id/vm_stats.xml?period[startdate]=YYYY-MMDD+hh%3Amm%3Ass&period[enddate]=YYYY-MM-DD+hh%3Amm%3Ass GET /users/:user_id/vm_stats.json?period[startdate]=YYYY-MMDD+hh%3Amm%3Ass&period[enddate]=YYYY-MM-DD+hh%3Amm%3Ass The generated billing statistics will show the billing details for all virtual machines, load balancers and edge servers owned by this particular user. For the output examples and the explanation of the fields returned, refer to corresponding sections: • • • Billing statistics for a VM View load balancer billing statistics Billing statistics for CDN edge servers 5.12 See user’s monthly bills To get data on user’s monthly bills for a year, use this request GET onapp.com/users/:user_id/monthly_bills.xml GET onapp.com/users/:user_id/monthly_bills.json XML output example <?xml version="1.0" encoding="UTF-8"?> <vm_stats type="array"> <vm_stat> 74 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 <month type="integer">5</month> <cost type="float">167.371330738068</cost> </vm_stat> </vm_stats> Where: month — number of a month cost — total user costs, charged for that month (monthly price+costs for resources and usage. See section View user’s statistics) 5.13 See user’s payments To get the list of user payments: GET onapp.com/users/:user_id/payments.xml GET onapp.com/users/:user_id/payments.json XML output example <?xml version="1.0" encoding="UTF-8"?> <payments type="array"> <payment> <created_at type="datetime">2011-03-15T20:00:41+07:00</created_at> <updated_at type="datetime">2011-03-15T20:00:41+07:00</updated_at> <amount type="decimal">2000.0</amount> <invoice_number>001</invoice_number> <id type="integer">2</id> <user_id type="integer">1</user_id> </payment> </payments> Where: amount — money amount in the currency set in the billing plan invoice_number — optional number of invoice id — payment ID user_id — ID of the user 5.14 Add a payment To add a payment record to your DB, use this request: POST /users/:user_id/payments.xml POST /users/:user_id/payments.json XML Request example 75 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 curl –i –X POST –d ’<payment><amount>12</amount><invoice_number>123</invoice_number></payment>’ –H ‘Accept: application/xml’ –H ‘Content-type: application/xml’-u user:userpass –url http://onapp.test/users/:user_id/payments.xml JSON Request example curl –i –X POST –d ‘{“payment”:{“amount”:”12”,”invoice_number”:”123”}}’ –H ‘Accept: application/json’ –H ‘Content-type: application/json’-u user:userpass -–url http://onapp.test/users/:user_id/payments.json Where you have to send: amount * - amount of the payment (should be higher than zero) invoice_number - optional number of the invoice 5.15 Edit a payment You can change the invoice number or the payment amount with the following request: PUT /users/:user_id/payments/:id.xml PUT /users/:user_id/payments/:id.json XML Request example curl –i –X PUT –d ’<payment><amount>99</amount><invoice_number>66</invoice_number></payment>’ –H ‘Accept: application/xml’ –H ‘Content-type: application/xml’-u user:userpass –url http://onapp.test/users/:user_id/payments/:id.xml JSON Request example curl –i –X PUT –d ‘{“payment”:{“amount”:”99”,”invoice_number”:”66”}}’ –H ‘Accept: application/json’ –H ‘Content-type: application/json’-u user:userpass -–url http://onapp.test/users/:user_id/payments/:id.json 5.16 Delete a payment DELETE /users/:user_id/payments/payment_id.xml DELETE /users/:user_id/payments/payment_id.json XML Request example curl –i –X DELETE –u user:userpass --url http://onapp.test//users/:user_id/payments/payment_id.xml JSON Request example 76 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 curl –i –X DELETE –u user:userpass --url http://onapp.test//users/:user_id/payments/payment_id.json 5.17 See VMs of a particular user To see the virtual machines owned by a particular user: GET GET /users/:user_id/virtual_machines.xml /users/:user_id/virtual_machines.json An array of virtual machines will be returned. For details and definitions refer to Get the list of VMs section in Virtual Machines chapter 5.18 See user limits Limits display available resources for creating a VM, but not all the available resources of the user. XML Request example <?xml version="1.0" encoding="UTF-8"?> <hash> <best_data_store_group_primary_id type="integer">1</best_data_store_group_primary_id> <best_data_store_group_swap_id type="integer">1</best_data_store_group_swap_id> <limits> <cpus type="integer">3</cpus> <cpu_shares type="integer">99</cpu_shares> <hypervisor_groups type="array"> <hypervisor_group> <label>Default Hypervisor Group</label> <id type="integer">3</id> </hypervisor_group> </hypervisor_groups> <rate type="integer">1000</rate> <hypervisors type="array"> <hypervisor> <label>HV1_xen</label> <id type="integer">1</id> </hypervisor> <hypervisor> <label>HV2_xen</label> <id type="integer">2</id> </hypervisor> <hypervisor> <label>HV3_kvm</label> <id type="integer">3</id> </hypervisor> <hypervisor> <label>HV4_kvm</label> <id type="integer">4</id> </hypervisor> </hypervisors> <primary_disk_size type="integer">13</primary_disk_size> <network_groups type="array"> 77 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 <network_group> <label>Default Network Group</label> <id type="integer">2</id> </network_group> </network_groups> <data_store_groups type="array"> <data_store_group> <label>Default DataStore Group</label> <id type="integer">1</id> </data_store_group> </data_store_groups> <swap_disk_size type="integer">13</swap_disk_size> <memory type="integer">5879</memory> </limits> <best_network_group_id type="integer">2</best_network_group_id> </hash> Where: cpu – amount of CPU cores, available for the user to create a VM cpu_shares - CPU priority available for creation a VM swap_disk_size/primary_disk_size – available disk space in GB at best_data_store_group_primary_id (best_data_store_group_swap_id) memory – available RAM rate – maximum port speed limit data_store_groups – an array of available data store groups, with group label and ID hypervisor_groups – an array of available hypervisors zones, with zone label and ID hypervisors – an array of available hypervisors, with hypervisor label and ID best_data_store_group_primary_id(best_data_store_group_swap_id) – the ID of a data store zone with higher available disk capacity. best_network_group_id – the ID of a priority network 5.19 Hypervisors used by a users’ VMs GET onapp.com/users/:user_id/hypervisors.xml GET onapp.com/users/:user_id/hypervisors.json An array of hypervisors used by VMs of the user will be returned. For details and definitions refer to Get the list of hypervisors section in Hypervisors chapter 78 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 5.20 User’s data store zones To see data store zones assigned to user’s VMs, use this request GET onapp.com/users/:user_id/data_store_zones.xml GET onapp.com/users/:user_id/data_store_zones.json For details and definitions refer to Get the list of data store zones section in Data store zones chapter 5.21 User’s network zones To get the list of network zones associated with a user: GET onapp.com/users/:user_id/network_zones.xml GET onapp.com/users/:user_id/network_zones.json For details and definitions refer to Get the list of network zones section in Network zones chapter 79 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 6. User additional fields User Additional Fields allow administrators to create custom fields and use them to create/edit additional information in a user’s profile. 6.1 Get the list of additional fields GET GET /user_additional_fields.xml /user_additional_fields.json XML Request example curl -u user:userpass http://onapp_test/user_additional_fields.xml JSON Request example curl -u user:userpass http://onapp_test/user_additional_fields.json XML Output example <?xml version="1.0" encoding="UTF-8"?> <user_additional_fields type="array"> <user_additional_field> <name>test_edited_by_api</name> <default_value>0</default_value> <data_type>integer</data_type> <id type="integer">1</id> </user_additional_field> Where: name – the additional field name. default value – information which will be displayed if the user hasn't specified information for this field, or if they enter information that doesn't match the preset data type. data type - integer/string additional field data type. id – the additional field id. 6.2 See an additional field details To get details of a particular additional field, use the following request: GET GET /settings/user_additional_fields/:id.xml /settings/user_additional_fields/:id.json 80 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 XML Output example <?xml version="1.0" encoding="UTF-8"?> <user_additional_fields type="array"> <user_additional_field> <name>test_edited_by_api</name> <default_value>0</default_value> <data_type>integer</data_type> <id type="integer">1</id> </user_additional_field> For details refer to Get the list of additional fields section. 6.3 Create new additional field To create a user additional field – use this request: POST POST /user_additional_fields.xml /user_additional_fields.json XML Request example curl -i -X POST -d '<user_additional_field><name>TestField</name><data_type>string</data_type><default_va lue>testvalue</default_value></user_additional_field>' -u user:userpass http://onapp_test/user_additional_fields.xml -H 'Accept: application/xml' -H 'Contenttype: application/xml' JSON Request example curl -i -X POST -d '{"user_additional_field":{"name":"TestField","data_type":"string","default_value":"Te stName"}}' -u user:userpass http://onapp_test/user_additional_fields.json -H 'Accept: application/json' -H 'Content-type: application/json' Where: name* - the unique Additional Field name. (maximum length 256 characters.) data_type* - integer/string additional field data type. default_value* - information which will be displayed if the user hasn't specified information for this field, or if they enter information that doesn't match the preset data type.(maximum length 256 symbols.) 81 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 6.4 Edit additional field PUT PUT /user_additional_fields.xml /user_additional_fields.json XML Request example curl -i -X PUT -d '<user_additional_field><name>TestField</name><data_type>string</data_type><default_va lue>CHANGEDvalue</default_value></user_additional_field>' -u user:userpass http://onapp_test/user_additional_fields/<field_id>.xml -H 'Accept: application/xml' H 'Content-type: application/xml' JSON Request example curl -i -X PUT -d '{"user_additional_field":{"name":"TestField","data_type":"string","default_value":"Te stName"}}' -u user:userpass http://onapp_test/user_additional_fields/:field_id.json -H 'Accept: application/json' -H 'Content-type: application/json' You can edit the following parameters: name, data type and default value. 6.5 DELETE DELETE Delete additional field /user_additional_fields.xml /user_additional_fields.json XML Request example curl -i -X DELETE -u user:userpass http://onapp_test/user_additional_fields/:id.xml -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X DELETE -u user:userpass http://onapp_test/user_additional_fields/:id.json H 'Accept: application/json' -H 'Content-type: application/json' 6.6 Search a user by additional field parameter To find a user who is assigned a particular additional field, use the following request: GET /users/field_name=field_value.xml GET /users/field_name=field_value.json XML Request example: 82 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 curl -i -X GET -u user:userpass http://onapp.test/users/field_name=field_value.xml JSON Request example: curl -i -X GET -u user:userpass http://onapp.test/users/field_name=field_value.json Where: field_name – the name of the additional field which is assigned to the user in search field_value – the value set for the specified additional field for this particular user The result of the search request will be the list of users with their details who are assigned the additional field field_name with the values starting with field_value. 83 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 7. User groups User groups enable you to associate users into groups. So far user groups are used to apply a particular theme to a group of users. 7.1 Get the list of user groups To get the list of user groups: GET GET /user_groups.xml /user_groups.json XML Output request <?xml version="1.0" encoding="UTF-8"?> <user_groups type="array"> <user_group> <label>hyper</label> <created_at type="datetime">2011-07-19T13:29:54Z</created_at> <updated_at type="datetime">2011-07-19T13:29:54Z</updated_at> <id type="integer">4</id> </user_group> <user_group> <label>test-whmcs</label> <created_at type="datetime">2011-07-20T10:14:42Z</created_at> <updated_at type="datetime">2011-07-20T10:14:42Z</updated_at> <id type="integer">5</id> </user_group> </user_groups> Where: label – the group name created_at – the date when this record was created in database updated_at – the date when this record was updated in database ID – the group ID 7.2 Get the user group details GET GET /user_groups.xml /user_groups.json For details refer to Get the list of user groups section. 7.3 Create a user group To create a user group – use this request: 84 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 POST POST /user_groups.xml /user_groups.json XML Request example curl -i -X POST http://onapp.test/user_groups.xml -d '<?xml version="1.0" encoding="UTF-8"?><pack><label>TEST_XML</label></pack>' -u user:userpass -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X POST http://onapp.test/user_groups.json -d '{"pack":{"label":"TEST_JSON"}}' -u user:userpass -H 'Accept: application/json' -H 'Content-type: application/json' 7.4 Edit a user group To edit a user group (change the name of the user group) - use this request: PUT PUT /user_groups/:id.xml /user_groups/:id.json XML Request example curl -i -X PUT http://onapp.test/user_groups/:id.xml -d '<user_group><label>NEW LABEL</label></user_group>' -u user:userpass -H 'Accept: application/xml' -H 'Contenttype: application/xml' JSON Request example curl -i -X PUT http://onapp.test/user_groups/:id.json -d '{"user_group":{"label":"NEW LABEL"}}' -u user:userpass -H 'Accept: application/json' -H 'Content-type: application/json' 7.5 Delete a user group To delete a user group: DELETE DELETE /user_groups/:user_group_id.xml /user_groups/:user_group_id.json XML Request example curl -i -X DELETE http://onapp.test/user_groups/:id.xml -u user:userpass -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example 85 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 curl -i -X DELETE http://onapp.test/user_groups/:id.json -u admin:dev5dot130 -H 'Accept: application/json' -H 'Content-type: application/json' Returns 200 response on successful deletion, or 404 response if no user group with such ID exists in the DB 86 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 8. Whitelist IPs A white List is a list of IPs from which a particular user may access the control panel. Once an IP has been added to the white list, a user will not be able to access the control panel from any other IP. All methods are available to Whitelist IPs class. 8.1 Get the list of whitelist IPs To get the list of IPs entered to the list: GET GET /users/:user_id/user_white_lists.xml /users/:user_id/user_white_lists.json Output example <?xml version="1.0" encoding="UTF-8"?> <user_white_lists> <user_white_list> <created_at>2011-04-21T15:38:14+03:00</created_at> <updated_at>2011-04-21T15:38:14+03:00</updated_at> <id>2</id> <user_id>8</user_id> <ip>192.168.112.1</ip> <description>My IP</description> </user_white_list> ... <user_white_list></user_white_list> ... </user_white_lists> Where: created_at –the date when this record in DB was created updated_at – the date when this record in DB was updated id – the record ID user_id – the ID of a user for whom this whitelist was created ip – the IP from which this user can log in to CP description – an optional description 8.2 Get whitelist IPs details To get details for a particular whitelist, use the following request: GET GET /users/:user_id/user_white_lists/:id.xml /users/:user_id/user_white_lists/:id.json 87 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 XML Output example <?xml version="1.0" encoding="UTF-8"?> <user_white_list> <created_at>2011-04-21T15:38:14+03:00</created_at> <updated_at>2011-04-21T15:38:14+03:00</updated_at> <id>2</id> <user_id>8</user_id> <ip>192.168.112.1</ip> <description>My IP</description> </user_white_list> Where: created_at – the date when this record in DB was created updated_at – the date when this record in DB was updated id – the record ID user_id – the ID of a user for whom this whitelist was created ip – the IP from which this user can log in to CP description – an optional description 8.3 Edit a whitelisted IP To edit a whitelisted IP, use the following request: PUT PUT /users/:user_id/user_white_lists/:id.xml /users/:user_id/user_white_lists/:id.json XML Request example curl -i -X PUT -H 'Accept: application/xml' -H 'Content-type: application/xml' -u user:userpass -d '<user_white_list><ip>127.0.0.123</ip></user_white_list>' http://onapp.test/users/:user_id/user_white_lists/:id.xml JSON Request example curl -i -X PUT -H 'Accept: application/json' -H 'Content-type: application/json' -d '{"user_white_list":{"ip":"109.123.105.129","description":"udr"}}' -u user:userpass http://onapp.test/users/:user_id/user_white_lists/:id.json 8.4 Add a whitelisted IP To add an IP to the list of whitelisted IPs: POST POST /users/:user_id/user_white_lists.xml /users/:user_id/user_white_lists.json XML Request example 88 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 curl -i -X POST -H 'Accept: application/xml' -H 'Content-type: application/xml' -u user:userpass -d '<user_white_list><ip>127.0.0.111</ip></user_white_list>'http://onapp.test/users/9/use r_white_lists.xml JSON Request example curl -i -X POST -H 'Accept: application/json' -H 'Content-type: application/json' -d '{"user_white_list":{"ip":"109.123.105.178","description":"qsas"}}' -u user:userpass http://onapp.test/users/:user_id/user_white_lists.json Where: ip * - IP address, from which a user can login to the Control panel 8.5 Delete a whitelisted IP To delete a whitelisted IP, use the following request: DELETE DELETE /users/:user_id/user_white_lists/:id.xml /users/:user_id/user_white_lists/:id.json XML Request example curl -X DELETE -H 'Accept: application/xml' -H 'Content-type: application/xml' -u user:userpass http://onapp.test/users/:user_id/user_white_lists/:id.xml JSON Request example curl -X DELETE -H 'Accept: application/json' -H 'Content-type: application/json' -u user:userpass http://onapp.test/users/:user_id/user_white_lists/:id.json 89 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 9. Firewall Rules for VMs Firewall rules are applied to the VMs of your cloud to prevent unauthorized or unwanted requests to their network interfaces. You can configure your firewall to Accept/Drop specific request types. All methods are available for this class. 9.1 Get the list of firewall rules To get the list of firewall rules assigned to a VM, use the following request: GET GET /virtual_machines/:virtual_machine_id/firewall_rules.xml /virtual_machines/:virtual_machine_id/firewall_rules.json <?xml version="1.0" encoding="UTF-8"?> <firewall_rules> <firewall_rule> <position>1</position> <address> </address> <created_at>2011-04-20T12:52:10+03:00</created_at> <command>ACCEPT</command> <updated_at>2011-04-20T12:52:10+03:00</updated_at> <port>21</port> <protocol>TCP</protocol> <id>1</id> <network_interface_id>5</network_interface_id> </firewall_rule> </firewall_rules> Where: position – the rule priority address* – the IP address for which this rule is active. If none is specified, all IPs will be subject to this rule. created_at – the date when the record in DB was created command – the action which will be performed with the IP specified by the address parameter updated_at – the date when the record was updated in DB port – the port for which this rule is active. If the field is empty, the rule will apply to all ports protocol – the IP protocol (TCP or UDP)for which this rule is active id – the ID of this record network_interface_id – the ID of a network interface for which this rule is active 90 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 9.2 Edit a firewall rule To edit a firewall rule, use the following request: PUT PUT /virtual_machines/:virtual_machine_id/firewall_rules/:id.xml /virtual_machines/:virtual_machine_id/firewall_rules/:id.json XML Request example curl -i -X PUT -H 'Accept: application/xml' -H 'Content-type: application/xml' -u user:userpass -d '<firewall_rule><address>192.168.128.133</address><command>ACCEPT</command><port>70</p ort><protocol>TCP</protocol><network_interface_id>105</network_interface_id></firewall _rule>' http://onapp.test/virtual_machines/:virtual_machine_id/firewall_rules/:id.xml JSON Request example curl -i -X PUT -H 'Accept: application/json' -H 'Content-type: application/json' -u user:userpass -d '{"firewall_rule":{"address":"192.168.128.133","command":"ACCEPT","port":"70","protoco l":"TCP","network_interface_id":"105"}}' –url http://onapp.test/virtual_machines/:virtual_machine_id/firewall_rules/:id.json You can edit the following parameters: address* - Set the IP address for which this rule is active. • • • Leave the empty field to apply this rule to all IPs Enter hyphen-separated IPs to apply the rule to an IP range (e.g. 192.168.1.1-192.168.1.10) Enter the IPs with slash to apply the rule to CIDR (e.g. 192.168.1.1/24) command - sets the command to ACCEPT or DROP the abovementioned IPs port - • • • sets the port addresses Leave the empty field to apply the rule to all ports Enter colon-separated ports to apply the rule to a port range (e.g. 1024:1028) Enter comma-separated ports to apply the rule to the list of ports (e.g. 80,443,21) protocol - protocol type (TCP or UDP) network_interface_id - interface of the network 9.3 Add a firewall rule To add a firewall rule, use the request listed below. After you add a rule, you have to apply it to initiate a transaction responsible for running firewall rules. See the Apply a firewall rule section for details: 91 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 To add a firewall rule, use the following request: POST POST /virtual_machines/:virtual_machine_id/firewall_rules.xml /virtual_machines/:virtual_machine_id/firewall_rules.json XML Request example curl -i -X POST -H 'Accept: application/xml' -H 'Content-type: application/xml' -u user:userpass -d '<?xml version="1.0" encoding="UTF8"?><firewall_rule><address></address><command>DROP</command><port></port><protocol>TC P</protocol><network_interface_id>105</network_interface_id></firewall_rule>' –url http://onapp.test/virtual_machines/:virtual_machine_id/firewall_rules.xml JSON Request example curl -i -X POST -H 'Accept: application/json' -H 'Content-type: application/json' -u user:userpass -d '{"firewall_rule":{"command":"DROP","protocol":"TCP","network_interface_id":"105"}}' – url http://onapp.test/virtual_machines/:virtual_machine_id/firewall_rules.json Send the following parameters: address* - Set the IP address for which this rule is active. • • • Leave the empty field to apply this rule to all IPs Enter hyphen-separated IPs to apply the rule to an IP range (e.g. 192.168.1.1-192.168.1.10) Enter the IPs with slash to apply the rule to CIDR (e.g. 192.168.1.1/24) command * - sets the command to ACCEPT or DROP the abovementioned IPs port - • • • sets the port addresses Leave the empty field to apply the rule to all ports Enter colon-separated ports to apply the rule to a port range (e.g. 1024:1028) Enter comma-separated ports to apply the rule to the list of ports (e.g. 80,443,21) protocol * - protocol type (TCP or UDP) network_interface_id * - interface of the network 9.4 Apply a firewall rule To apply firewall rules for a VM: POST /virtual_machines/:virtual_machine_id/update_firewall_rules.xml POST /virtual_machines/:virtual_machine_id/update_firewall_rules.json 92 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 XML request example: curl -i -X POST -u user:userpass -H 'Accept: application/xml' --url http://onapp.test/virtual_machines/28/update_firewall_rules.xml JSON request example: curl -i -X POST -u user:userpass -H 'Accept: application/xml' --url http://onapp.test/virtual_machines/28/update_firewall_rules.json 9.5 Delete a firewall rule To delete a firewall rule, use the flowing request: DELETE DELETE /virtual_machines/:virtual_machine_id/firewall_rules/:id.xml /virtual_machines/:virtual_machine_id/firewall_rules/:id.json XML Request example curl -i -X DELETE -H 'Accept: application/xml' -H 'Content-type: application/xml' -u user:userpass --url http://onapp.test/virtual_machines/:virtual_machine_id/firewall_rules/:id.xml JSON Request example curl -i -X DELETE -H 'Accept: application/json' -H 'Content-type: application/json' -u user:userpass --url http://onapp.test/virtual_machines/:virtual_machine_id/firewall_rules/:id.json 9.6 Set default firewall rules To set default firewall rules for a VM (either DROP or ACCEPT), you need to set the rule for each network interface the VM is using. To do so, check the network interface ID and run the following request: POST POST /virtual_machines/:virtual_machine_id/network_interfaces/:id.xml /virtual_machines/:virtual_machine_id/network_interfaces/:id.json XML Request example curl -i -X PUT -u user:userpass -H 'Accept: application/xml' -H 'Content-type: application/xml' -d '<network_interface><default_firewall_rule>ACCEPT</default_firewall_rule></network_int erface>' --url http://onapp.test/virtual_machines/:virtual_machine_id/network_interfaces/:network_int erface_id.xml JSON Request example 93 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 curl -i -X PUT -u user:userpass -H 'Accept: application/json' -H 'Content-type: application/json' -d '{"network_interface":{"default_firewall_rule":"DROP"}}' --url http://onapp.test/virtual_machines/:virtual_machine_id/network_interfaces/:network_int erface_id.json Where: default_firewall_rule * - set default firewall rule for the particular VM network interface – either DROP or ACCEPT 94 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 10. Data store zones This class manages all the Data store zones created in the cloud. A data store zone consists of several data stores sharing the same permissions and assigned to the same billing plan. By setting up different zones, you can create different tiers of storage with different pricing and performance. 10.1 Get the list of data store zones To get the list of available data store zones, use the following method: GET GET /data_store_zones.xml /data_store_zones.json You will get an array of data store zones set up within your cloud. XML Output example <?xml version="1.0" encoding="UTF-8"?> <data-store-groups type="array"> <data-store-group> <label>DSZ_1</label> <created_at type="datetime">2011-01-11T11:11:15Z</created_at> <updated_at type="datetime">2011-01-17T12:56:41Z</updated_at> <id type="integer">5</id> </data-store-group> Where: label The data store zone title created_at the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format updated_at the date when the Data store zone was updated in the [YYYY][MM][DD]T[hh][mm][ss]Z format id The data store zone ID 10.2 Add a data store zone Use the following methods to create a new Data store zone: POST POST /data_store_zones.xml /data_store_zones.json XML Request example curl -i -X POST http://onapp.test/data_store_zones.xml -d '<?xml version="1.0" encoding="UTF-8"?><pack><label>TEST_XML</label></pack>' -u user:userpass -H 'Accept: application/xml' -H 'Content-type: application/xml' 95 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 JSON Request example curl -i -X POST http://onapp.test/data_store_zones.json -d '{"pack":{"label":"TEST_JSON"}}' -u user:userpass -H 'Accept: application/json' -H 'Content-type: application/json' Where: label * - is new data_store_zone title 10.3 Get data store zone details GET GET /data_store_zones/:id.xml /data_store_zones/:id.json This method returns details of a particular Data store zone. XML Output example <?xml version="1.0" encoding="UTF-8"?> <data-store-groups> <data-store-group> <label>DSZ_2</label> <created_at type="datetime">2011-01-11T11:55:00Z</created_at> <updated_at type="datetime">2011-01-17T12:56:27Z</updated_at> <id type="integer">8</id> </data-store-group> </data-store-groups> Where: Label Created_at Updated_at Id The data store zone title the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format the date when the Data store zone was updated in the [YYYY][MM][DD]T[hh][mm][ss]Z format The data store zone ID 10.4 Edit a data store zone To edit a label of a particular data store zone: PUT PUT /data_store_zones/:id.xml /data_store_zones/:id.json XML Request example 96 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 curl -X PUT http://onapp.test/data_store_zones/:id.xml -d ’<data_store_group><label>Data_Store_Name</label></data_store_group>’ -u user:userpass -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -X PUT http://onapp.test/data_store_zones.json -d ‘{data_store_group: {label:”Data_Store_name”}}’ -u user:userpass -H 'Accept: application/json' -H 'Content-type: application/json' 10.5 Delete a data store zone To delete a particular data store zone: DELETE DELETE /data_store_zones/:id.xml /data_store_zones/:id.json XML Request example curl -X DELETE http://onapp.test/data_store_zones/:id.xml -u user:userpass -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -X DELETE http://onapp.test/data_store_zones/:id.json -u user:userpass -H 'Accept: application/json' -H 'Content-type: application/json' You will get a 200 status response on success, and 404 if there is no such a data store zone with a requested ID or you entered incorrect URL. 10.6 Get the list of data stores attached to a data store zone GET GET /data_store_zones/:data_store_group_id/data_stores.xml /data_store_zones/:data_store_group_id/data_stores.json On success, an array of data stores is returned. XML Output example 97 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 <?xml version="1.0" encoding="UTF-8"?> <data-stores type="array"> <data-store> <label>ds1</label> <created_at type="datetime">2011-01-06T10:54:30Z</created_at> <updated_at type="datetime">2011-02-07T12:27:32Z</updated_at> <data_store_group_id type="integer">5</data_store_group_id> <enabled type="boolean">false</enabled> <id type="integer">1</id> <zombie_disks_size type="integer">110</zombie_disks_size> <ip></ip> <local_hypervisor_id type="integer" nil="true"></local_hypervisor_id> <data_store_size type="integer">465</data_store_size> <identifier>onapp-ojgg2jk75zfzmw</identifier> </data-store> Explanation of the data returned: Label The name of the data store attached to this data store zone created_at Timestamp the DB record was created updated_at Timestamp the DB record was updated data_store_group_id The ID of a data store zone to which this data store is attached Enabled True if the data store is enabled and you can create VMs on it. Otherwise, false Id The data store ID zombie_disks_size The disk space in GB allocated to zombie disks Ip The data store IP address local_hypervisor_id The ID of the hypervisor to which this data store is assigned data_store_size The data store disk capacity in GB Identifier The data store identifier in DB 98 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 10.7 Attach a data store to a data store zone POST POST /data_store_zones/:data_store_zone_id/data_stores/:id/attach.xml /data_store_zones/:data_store_zone_id/data_stores/:id/attach.json XML Request example curl -X POST http://onapp.test/data_store_zones/:data_store_zone_id/data_stores/:data_store_id/atta ch.xml -u user:userpass -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -X POST http://onapp.test/data_store_zones/:data_store_zone_id/data_stores/:data_store_id/atta ch.json -u user:userpass -H 'Accept: application/json' -H 'Content-type: application/json' Using this request you attach an unassigned data store (:data_store_id *) to a data store zone (:data_store_zone_id *) 10.8 Detach a data store from a data store zone POST POST /data_store_zones/:data_store_group_id/data_stores/:id/detach.xml /data_store_zones/:data_store_group_id/data_stores/:id/detach.json XML Request example curl -X POST http://onapp.test/data_store_zones/:data_store_zone_id/data_stores/:data_store_id/deta ch.xml -u user:userpass -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -X POST http://onapp.test/data_store_zones/:data_store_zone_id/data_stores/:data_store_id/deta ch.json -u user:userpass -H 'Accept: application/json' -H 'Content-type: application/json' 99 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 11. Network zones A network zone consists of several networks sharing the same permissions and assigned to the same billing plan. Network zones can be attached to hypervisor zones, enabling you to create different tiers of service within your cloud. All API calls are available to this class. 11.1 Get the list of network zones This method lists an array of all the network zones available in your cloud. GET GET /network_zones.xml /network_zones.json XML Output example <?xml version="1.0" encoding="UTF-8"?> <network-groups type="array"> <network-group> <label>net_p</label> <created_at type="datetime">2011-01-06T11:18:45Z</created_at> <updated_at type="datetime">2011-01-06T11:18:45Z</updated_at> <id type="integer">3</id> </network-group> Where: Label created_at updated_at Id The Network zone title the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format the date when the Network zone was updated in the [YYYY][MM][DD]T[hh][mm][ss]Z format The Network zone ID 11.2 Add a network zone You can add a new network zone using the following method: POST POST /network_zones.xml /network_zones.json XML Request example curl -i -X POST http://onapp.test/network_zones.xml -d '<?xml version="1.0" encoding="UTF-8"?><pack><label>TEST_XML</label></pack>' -u user:userpass -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example 100 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 curl -i -X POST http://onapp.test/network_zones.json -d '{"pack":{"label":"TEST_JSON"}}' -u user:userpass -H 'Accept: application/json' -H 'Content-type: application/json' Where the only required parameter is label * - new network zone title 11.3 Get network zone details To get a particular network zone details: GET GET /network_zones/:id.xml /network_zones/:id.json XML Output example <?xml version="1.0" encoding="UTF-8"?> <network-groups type="array"> <network-group> <label>network_zone</label> <created_at type="datetime">2011-01-06T11:18:45Z</created_at> <updated_at type="datetime">2011-01-06T11:18:45Z</updated_at> <id type="integer">8</id> </network-group> Where: label created_at updated_at id The Network zone title the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format the date when the Network zone was updated in the [YYYY][MM][DD]T[hh][mm][ss]Z format The Network zone ID 11.4 Edit a network zone You can edit a label and an ID of a particular network zone using the PUT method: PUT PUT /network_zones/:id.xml /network_zones/:id.json XML Request example curl -X POST http://onapp.test/network_zones/:id.xml -d ’<network_group><label>Network_Name</label></network_group>’ -u user:userpass -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example 101 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 curl -X POST http://onapp.test/network_zones/:id.json -d ‘{network_group: {label:”Network_name”}}’ -u user:userpass -H 'Accept: application/json' -H 'Contenttype: application/json' 11.5 Delete a network zone To delete a network zone, use the following API call: DELETE DELETE /network_zones/:id.xml /network_zones/:id.json XML Request example curl -X DELETE http://onapp.test/network_zones/:id.xml -u user:userpass -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -X DELETE http://onapp.test/network_zones/:id.json -u user:userpass -H 'Accept: application/json' -H 'Content-type: application/json' You will get a 200 status response on success, and 404 if there is no such a network zone with a requested ID or you entered incorrect URL. 11.6 Attach a network to a network zone POST POST /network_zones/:network_zone_id/networks/:id/attach.xml /network_zones/:network_zone_id/networks/:id/attach.json XML Request example curl -X POST http://onapp.test/network_zones/:network_zone_id/networks/:network_id/attach.xml -u user:userpass -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -X POST http://onapp.test/network_zones/:network_zone_id/networks/:network_id/attach.json -u user:userpass -H 'Accept: application/json' -H 'Content-type: application/json' This request attaches network (:network_id *) to a network zone (:network_zone_id *) 11.7 Remove a network from a network zone POST POST /network_zones/:network_zone_id/networks/:id/detach.xml /network_zones/:network_zone_id/networks/:id/detach.json 102 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 XML Request example curl -X POST http://onapp.test/network_zones/:network_zone_id/networks/:network_id/detach.xml -u user:userpass -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -X POST http://onapp.test/network_zones/:network_zone_id/networks/:network_id/detach.json -u user:userpass -H 'Accept: application/json' -H 'Content-type: application/json' 103 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 12. Hypervisor zones A hypervisor zone consists of several hypervisors sharing the same permissions and assigned to the same billing plan. This class manages all the hypervisor zones created in the cloud. Hypervisor zones can have data stores and networks attached to them. The combination of hypervisor, data store and network zones can be used to create private clouds and tiered services for customers. All API calls are available to this class. 12.1 Get the list of hypervisor zones To get an array of hypervisor zones set up within your cloud, use the following request: GET GET /settings/hypervisor_zones.xml /settings/hypervisor_zones.json XML Output example <hypervisor-groups type="array"> <hypervisor-group> <label>HV_1</label> <created_at type="datetime">2011-01-11T11:11:15Z</created_at> <updated_at type="datetime">2011-01-17T12:56:41Z</updated_at> <id type="integer">5</id> </hypervisor-group> Where: Label The hypervisor zone title created_at The date in the [YYYY][MM][DD]T[hh][mm][ss]Z format updated_at The date when the hypervisor zone was updated in the [YYYY][MM][DD]T[hh][mm][ss]Z format Id The hypervisor zone ID 12.2 Add a hypervisor zone To add a new hypervisor zone, send the following request: POST POST /settings/hypervisor_zones.xml /settings/hypervisor_zones.json XML Request example 104 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 curl -i -X POST http://onapp.test/settings/hypervisor_zones.xml -d '<?xml version="1.0" encoding="UTF-8"?><pack><label>TEST_XML</label></pack>' -u user:userpass -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X POST http://onapp.test/settings/hypervisor_zones.json -d '{"pack":{"label":"TEST_JSON"}}' -u user:userpass -H 'Accept: application/json' -H 'Content-type: application/json' Where: label * - title of a new hypervisor zone 12.3 Get hypervisor zone details The following method returns details for a particular hypervisor zone: GET GET /settings/hypervisor_zones/:id.xml /settings/hypervisor_zones/:id.json XML Output example <?xml version="1.0" encoding="UTF-8"?> <hypervisor_groups type="array"> <hypervisor_group> <label>HV_1</label> <created_at type="datetime">2011-01-17T14:11:15Z</created_at> <updated_at type="datetime">2011-01-27T16:56:41Z</updated_at> <id type="integer">6</id> </hypervisor_group> Where: Label created_at updated_at Id The hypervisor zone title The date in the [YYYY][MM][DD]T[hh][mm][ss]Z format The date when the hypervisor zone was updated in the [YYYY][MM][DD]T[hh][mm][ss]Z format The hypervisor zone ID 12.4 Edit a hypervisor zone Use the following method to edit an existing hypervisor zone: PUT PUT /settings/hypervisor_zones/:id.xml /settings/hypervisor_zones/:id.json XML Request example 105 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 curl -X PUT http://onapp.test/settings/hypervisor_zones/:id.xml -d ’<hypervisor_group><label>hypervisor_zone_Name</label><disable_failover>true/false</di sable_failover></hypervisor_group>’ -u user:userpass -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -X PUT http://onapp.test/settings/hypervisor_zones/:id.json -d ‘{hypervisor_group: {label:”hypervisor_zone_name”,disable_failover:”true/false”}}’ -u user:userpass -H 'Accept: application/json' -H 'Content-type: application/json' You can edit: label - a particular hypervisor zone’s name. disable_failover – set true to disable hypervisor zone failover. Otherwise false. 12.5 Delete a hypervisor zone To delete a hypervisor zone, use the following API call: DELETE DELETE /settings/hypervisor_zones/:id.xml /settings/hypervisor_zones/:id.json XML Request example curl -X DELETE http://onapp.test/settings/hypervisor_zones/:id.xml -u user:userpass -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -X DELETE http://onapp.test/settings/hypervisor_zones/:id.json -u user:userpass H 'Accept: application/json' -H 'Content-type: application/json' You will get a 200 status response on success, and 404 if there is no such a hypervisor zone with a requested ID or you entered incorrect URL. 12.6 Get the list of hypervisors attached to hypervisor zone GET GET /settings/hypervisor_zones/:hypervisor_zone_id/hypervisors.xml /settings/hypervisor_zones/:hypervisor_zone_id/hypervisors.json Returns the array of all hypervisors attached to a particular hypervisor zone. 106 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 12.7 Attach/remove a hypervisor from a hypervisor zone You can attach an unassigned hypervisor to a HVZ, change the zone it is assigned to or remove it from the zone by editing a hypervisor. 12.8 Get the list of data store joins attached to a hypervisor zone GET GET /settings/hypervisor_zones/:hypervisor_zone_id/data_store_joins.xml /settings/hypervisor_zones/:hypervisor_zone_id/data_store_joins.json XML Output example <?xml version="1.0" encoding="UTF-8"?> <data_store_joins type="array"> <data_store_join> <created_at type="datetime">2011-01-17T13:16:31Z</created_at> <target_join_type>HypervisorGroup</target_join_type> <updated_at type="datetime">2011-01-17T13:16:31Z</updated_at> <data_store_id type="integer">2</data_store_id> <hypervisor_id type="integer" nil="true"></hypervisor_id> <id type="integer">7</id> <target_join_id type="integer">9</target_join_id> </data_store_join> </data_store_joins> Where: created_at Timestamp in DB when the record was created target_join_type HypervisorGroup for data store joins updated_at Timestamp in DB when the record was updated data_store_id The ID of a data store attached to a hypervisor zone hypervisor_id The ID of a hypervisor to which a data store is attached id The data store join ID target_join_id The ID of a hypervisor zone for which a join is created 12.9 Add a data store join to a hypervisor zone POST POST /settings/hypervisor_zones/:hypervisor_zone_id/data_store_joins.xml /settings/hypervisor_zones/:hypervisor_zone_id/data_store_joins.json 107 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 XML Request example curl -i -X POST http://onapp.test/settings/hypervisor_zones/:hypervisor_zone_id/data_store_joins.xml d '<data_store_id>:data_store_id</data_store_id>' -u admin:passwod -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X POST http://onapp.test/settings/hypervisor_zones/:hypervisor_zone_id/data_store_joins.json -d '{data_store_id:”:data_store_id”}' -u admin:passwod -H 'Accept: application/json' H 'Content-type: application/json' This request attaches a particular data store join (:data_store_id *) to a specific hypervisor zone (:hypervisor_zone_id ) 12.10 Remove a data store join from a hypervisor zone DELETE /settings/hypervisor_zones/:hypervisor_zone_id/data_store_joins/:id.xml DELETE /settings/hypervisor_zones/:hypervisor_zone_id/data_store_joins/:id.json XML Request example curl -i -X DELETE http://onapp.test/settings/hypervisor_zones/:hypervisor_zone_id/data_store_joins/:data _store_join_id.xml -u admin:passwod -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X DELETE http://onapp.test/settings/hypervisor_zones/:hypervisor_zone_id/data_store_joins/:data _store_join_id.json -u admin:passwod -H 'Accept: application/json' -H 'Content-type: application/json' Where: :id * – is an ID of data store join Returns HTTP 200 response on successful deletion, or HTTP 404 when a data store join with the ID specified is not found, or the URL requested is incorrect. 108 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 12.11 GET GET Get the list of network joins attached to this hypervisor zone /settings/hypervisor_zones/:hypervisor_zone_id/network_joins.xml /settings/hypervisor_zones/:hypervisor_zone_id/network_joins.json An array of network joins is returned on successful request. XML Output example <?xml version="1.0" encoding="UTF-8"?> <network_joins type="array"> <network_join> <created_at type="datetime">2011-02-01T12:27:52Z</created_at> <network_id type="integer">1</network_id> <target_join_type>HypervisorGroup</target_join_type> <updated_at type="datetime">2011-02-01T12:27:52Z</updated_at> <hypervisor_id type="integer" nil="true"></hypervisor_id> <id type="integer">6</id> <interface>eth2</interface> <target_join_id type="integer">1</target_join_id> </network_join> </network_joins> Where: created_at The timestamp when the record was created network_id The ID of a network attached to this zone target_join_type HypervisorGroup for a network join updated_at The timestamp when the record was updated hypervisor_id The ID of a hypervisor to which this network is assigned id The network join ID Interface The network join interface target_join_id The ID of a HV zone to which this network join is attached 12.12 POST POST Attach a new network join to a hypervisor zone /settings/hypervisor_zones/:hypervisor_zone_id/network_joins.xml /settings/hypervisor_zones/:hypervisor_zone_id/network_joins.json XML Request example 109 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 curl -i -X POST http://onapp.test/settings/hypervisor_zones/:hypervisor_zone_id/network_joins.xml -d '<network_join><network_id>4</network_id><interface>interface_test</interface></networ k_join>' -u admin:passwod -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X POST http://onapp.test/settings/hypervisor_zones/:hypervisor_zone_id/network_joins.json -d '{"network_join":{"network_id":"5","interface":"interface_test2"}}' -u admin:passwod H 'Accept: application/json' -H 'Content-type: application/json' Send the following parameters: network_id *- ID of the network you wish to attach interface *- the name of the appropriate network interface 12.13 Remove a network join from a hypervisor zone DELETE /settings/hypervisor_zones/:hypervisor_zone_id/network_joins/:id.xml DELETE /settings/hypervisor_zones/:hypervisor_zone_id/network_joins/:id.json XML Request example curl -i -X DELETE http://onapp.test/settings/hypervisor_zones/:hypervisor_zone_id/network_joins/:network _join_id.xml -u admin:passwod -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X DELETE http://onapp.test/settings/hypervisor_zones/:hypervisor_zone_id/network_joins/:network _join_id.json -u admin:passwod -H 'Accept: application/json' -H 'Content-type: application/json' Returns HTTP 200 response on successful deletion, or HTTP 404 when a resolver with the ID specified is not found, or the URL requested is incorrect. 110 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 13. Backup server zones Backup server zone consists of several backup servers that share the same user permissions and are assigned to one billling plan. Backup server zones can be used for organizing and managing backup servers and creating different tiers of servers for customers. 13.1 Get the list of backup server zones To get the list of backup server zones: GET GET /settings/backup_server_zones.xml /settings/backup_server_zones.json XML Response example <?xml version="1.0" encoding="UTF-8"?> <backup_server_groups type="array"> <backup_server_group> <label>bsz</label> <created_at type="datetime">2012-01-04T11:50:40Z</created_at> <updated_at type="datetime">2012-01-04T11:50:40Z</updated_at> <id type="integer">28</id> </backup_server_group> </backup_server_groups> Where: label – backup server zone title id – backup server zone ID 13.2 Get backup server zone details To get the backup server zone details: GET GET /settings/backup_server_zones/:id.xml /settings/backup_server_zones/:id.json XML Response example <backup_server_group> <label>bsz</label> <created_at type="datetime">2012-01-04T11:50:40Z</created_at> <updated_at type="datetime">2012-01-04T11:50:40Z</updated_at> <id type="integer">28</id> </backup_server_group> 111 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 Where: label – backup server zone title id – backup server zone ID 13.3 Create a backup server zone To create a backup server zone, use the following request: POST POST /settings/backup_server_zones.xml /settings/backup_server_zones.json XML Request example curl -i -X POST -u user:userpass http://onapp.test/backup_server_zones.xml -d '<backup_server_group><label>az_val_xml</label></backup_server_group>' -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X POST -u user:userpass http://onapp.test/backup_server_zones.json -d '{"backup_server_group":{"label":"az_val_json"}}' -H 'Accept: application/json' -H 'Content-type: application/json' Where: label *– title of a new backup server zone 13.4 Edit a backup server zone PUT PUT /settings/backup_server_zones/:id.xml /settings/backup_server_zones/:id.json XML Request example curl -i -X PUT -u user:userpass http://onapp.test/backup_server_zones/:id.xml -d '<backup_server_group><label>az_val_change</label></backup_server_group>' -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X PUT -u user:userpass http://onapp.test/backup_server_zones/:id.json -d '{"backup_server_group":{"label":"az_val_change"}}' -H 'Accept: application/json' -H 'Content-type: application/json' 112 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 Where: label *– specify a new label of the backup server zone 13.5 Delete a backup server zone To delete a backup server zone, use the following API call: DELETE DELETE /settings/backup_server_zones/:id.xml /settings/backup_server_zones/:id.json XML Request example curl -i -X DELETE -u user:userpass http://onapp.test/backup_server_zones/:id.xml -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X DELETE -u user:userpass http://onapp.test/backup_server_zones/:id.json -H 'Accept: application/json' -H 'Content-type: application/json' 13.6 Get the list of servers assigned to backup server zone To get the list of servers assigned to the backup server zone, use the following request: GET /settings/backup_server_zones/:backup_server_zone_id/backup_servers.xml GET /settings/backup_server_zones/:backup_server_zone_id/backup_servers.json JSON Request example curl -i -X GET -u user:userpass http://onapp.test/backup_server_zones/:backup_server_zone_id/backup_servers.json -H 'Accept: application/json' -H 'Content-type: application/json' XML Request example curl -i -X GET -u user:userpass http://onapp.test/backup_server_zones/:backup_server_zone_id/backup_servers.xml -H 'Accept: application/xml' -H 'Content-type: application/xml' XML Output example <?xml version="1.0" encoding="UTF-8"?> <backup_servers type="array"> <backup_server> <label>az_val_ue_xml</label> 113 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 <created_at type="datetime">2012-02-10T15:14:53Z</created_at> <updated_at type="datetime">2012-02-10T15:31:13Z</updated_at> <backup_server_group_id type="integer">55</backup_server_group_id> <id type="integer">25</id> <enabled type="boolean">true</enabled> <backups type="array"/> <capacity type="integer">40</capacity> <ip_address>172.0.0.2</ip_address> </backup_server> </backup_servers> Where: backup_servers –the array of backup servers assigned to this zone with the following details: label – backup server label created at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format updated at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format backup_server_group_id – the ID of the backup server zone the backup server belongs to id – the backup server ID enabled – backup server parameter; if “enabled” = true, the backup server is enabled; if enabled=false, the backup server is disabled. backups – the list of backups stored at the backup server capacity – the backup server capacity ip_address – the backup server IP 13.7 Assign backup server to backup server zone POST /settings/backup_server_zones/:backup_server_zone_id/backup_servers/:backup_s erver_id/attach.xml POST /settings/backup_server_zones/:backup_server_zone_id/backup_servers/:backup_s erver_id/attach.json Using this request you attach an unassigned backup server (:backup_server_id *) to a backup server zone (:backup_server_zone_id *) XML Request example 114 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 curl -i -X POST -u user:userpass http://onapp.test/backup_server_zones/:backup_server_zone_id/backup_servers/:backup_se rver_id/attach.xml -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X POST -u user:userpass http://onapp.test/backup_server_zones/:backup_server_zone_id/backup_servers/:backup_se rver_id/attach.json -H 'Accept: application/json' -H 'Content-type: application/json' 13.8 Unasign backup server from backup server zone POST /settings/backup_server_zones/backup_server_zone_id/backup_server/:backup_ser ver_id/detach.xml POST /settings/backup_server_zones/backup_server_zone_id/backup_server/:backup_ser ver_id/detach.json Using this request you detach an assigned backup server (:backup_server_id *) from a backup server zone (:backup_server_zone_id *) XML Request example curl -i -X POST -u user:userpass http://onapp.test/backup_server_zones/:backup_server_zone_id/backup_servers/:backup_se rver_id/detach.xml -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X POST -u user:userpass http://onapp.test/backup_server_zones/:backupserver_zone_id/backup_servers/:backup_server_id/detach.json -H 'Accept: application/json' -H 'Content-type: application/json' 115 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 14. Hypervisors Hypervisors provide hardware resources for virtual machines. A specific physical hypervisor server supplies the CPU, RAM and storage capacity from the Data Stores attached to that hypervisor. All API calls are available to this class. 14.1 Get the list of hypervisors GET GET /settings/hypervisors.xml /settings/hypervisors.json Returns the array of available hypervisors. XML Output example <?xml version="1.0" encoding="UTF-8"?> <hypervisors type="array"> <hypervisor> <label>hv2</label> <called_in_at type="datetime">2011-08-30T13:30:31+03:00</called_in_at> <used_cpu_resources type="integer">135</used_cpu_resources> <free_memory type="integer">1670</free_memory> <spare type="boolean">false</spare> <created_at type="datetime">2011-08-10T12:33:45+03:00</created_at> <total_cpus type="integer">2</total_cpus> <hypervisor_type>xen</hypervisor_type> <updated_at type="datetime">2011-08-30T13:30:31+03:00</updated_at> <xen_info nil="true"></xen_info> <id type="integer">2</id> <hypervisor_group_id type="integer">1</hypervisor_group_id> <enabled type="boolean">true</enabled> <total_memory type="integer">6135</total_memory> <cpu_cores type="integer">2</cpu_cores> <health>HEALTH</health> <failure_count type="integer">0</failure_count> <memory_overhead type="integer">465</memory_overhead> <online type="boolean">true</online> <locked type="boolean">false</locked> <ip_address>109.123.105.165</ip_address> <disable_failover type="boolean">true</disable_failover> <memory_allocated_by_running_vms type="integer">3404</memory_allocated_by_running_vms> <total_memory_allocated_by_vms type="integer">5580</total_memory_allocated_by_vms> <free_disk_space type="integer">273</free_disk_space> </hypervisor> ... <hypervisor></hypervisor> ... </hypervisors> Where: 116 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 hypervisor – an array of all hypervisors in the cloud and their details label – the hypervisor title called_in_at – the date when the hypervisor was called in the [YYYY][MM][DD]T[hh][mm][ss]Z format spare – true if no VMs are assigned, otherwise false created_at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format hypervisor_type – the type of hypervisor (currently XEN or KVM) updated_at – the date when the record was made in the DB in the [YYYY][MM][DD]T[hh][mm][ss]Z format total_cpus – the total number of hypervisor CPU cores cpu_cores –the number of cores per CPU total_memory – total RAM (MB) of hypervisor free_memory – free RAM (MB) of hypervisor used_cpu_resources –the percentage of used CPU resources xen_info – the info on the Xen. This attribute is deprecated and will be removed in OnApp 2.4 id – the hypervisor ID hypervisor_group_id – the ID of a hypervisor zone to which this hypervisor is attached enabled – true if hypervisor is enabled and you can run VMs on it, otherwise false health – the array of the xm_info, disk, log_output. This attribute is deprecated and will be removed in OnApp 2.4 failure_count – the number of failures memory_overhead – shows the total memory overhead online – true if online, otherwise false locked – true if hypervisor is locked, otherwise false ip_address – the hypervisor IP address disable_failover – true if hypervisor failover is disabled. Otherwise false. memory_allocated_by_running_vms - the hypervisor RAM in MB allocated to the VMs, which are currently running on this HV total_memory_allocated_by_vms – the hypervisor RAM in MB allocated to all VMs of this HV free_disk_space – free GBs of hypervisor 14.2 Get the list of unassigned hypervisors GET GET /hypervisors/not_grouped.xml /hypervisors/not_grouped.json XML Output example <?xml version="1.0" encoding="UTF-8"?> <hypervisors type="array"> <hypervisor> <label>Test_HV</label> <called_in_at type="datetime">2011-07-14T22:01:25+07:00</called_in_at> <spare type="boolean">false</spare> 117 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 <created_at type="datetime">2011-03-17T19:26:38+07:00</created_at> <hypervisor_type>xen</hypervisor_type> <updated_at type="datetime">2011-07-19T18:49:35+07:00</updated_at> <xen_info nil="true"></xen_info> <id type="integer">7</id> <hypervisor_group_id nil="true"></hypervisor_group_id> <enabled type="boolean">true</enabled> <health nil="true">HEALTH</health> <failure_count type="integer">83086</failure_count> <memory_overhead type="integer">464</memory_overhead> <online type="boolean">false</online> <locked type="boolean">false</locked> <ip_address>123.123.123.123</ip_address> <disable_failover type="boolean">true</disable_failover> </hypervisor> </hypervisors> Where: hypervisor – an array of all unassigned hypervisors and their details label – the hypervisor title called_in_at – the date when the hypervisor was called in the [YYYY][MM][DD]T[hh][mm][ss]Z format spare – true if no VMs are assigned, otherwise false created_at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format hypervisor_type – the type of hypervisor (currently XEN or KVM) updated_at – the date when the record was made in the DB in the [YYYY][MM][DD]T[hh][mm][ss]Z format xen_info – the info on the Xen id – the hypervisor ID hypervisor_group_id – the ID of a hypervisor zone to which this hypervisor is attached enabled – true if hypervisor is enabled and you can run VMs on it, otherwise false health – the array of the xm_info, disk, log_output failure_count – the number of failures memory_overhead – shows the total memory overhead online – true if online, otherwise false locked – true if hypervisor is locked, otherwise false ip_address – the hypervisor IP address disable_failover – true if hypervisor failover is disabled. Otherwise false. 14.3 Get hypervisor details GET GET /settings/hypervisors/:id.xml /settings/hypervisors/:id.json XML Output example 118 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 <?xml version="1.0" encoding="UTF-8"?> <hypervisor> <called_in_at type="datetime">2010-08-09T12:55:01Z</called_in_at> <label>HV1</label> <created_at type="datetime">2010-04-27T15:34:11Z</created_at> <hypervisor_type>xen</hypervisor_type> <spare type="boolean">false</spare> <disable_failover type="boolean">true</disable_failover> <enabled type="boolean">true</enabled> <updated_at type="datetime">2010-08-09T12:55:04Z</updated_at> <id type="integer">1</id> <xen-info type="yaml" nil="true"></xen_info> <failure-count type="integer">0</failure_count> <health> <xm_info>{XM Info}</xm_info> <xm_list>{XM List}</xm_list> <vgdisplay>{VG Display}</vgdisplay> <uptime>13:54:55 up 32 days, 23:56, 1 user, load average: 0.01, 0.45, 0.58</uptime> </health> <memory-overhead type="integer">800</memory_overhead> <ip_address>{IP_Address}</ip_address> <locked type="boolean">false</locked> <online type="boolean">true</online> <memory_allocated_by_running_vms type="integer">3404</memory_allocated_by_running_vms> <total_memory_allocated_by_vms type="integer">5580</total_memory_allocated_by_vms> <free_disk_space type="integer">273</free_disk_space> </hypervisor> Where: called_in_at created_at failure_count health Id ip_address label locked memory_overhead online spare updated_at xen_info enabled the date when the hypervisor was called in the [YYYY][MM][DD]T[hh][mm][ss]Z format the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format the number of failures the array of the xm_info, disk, memory, and xm_list variables the Hypervisor ID the Hypervisor IP address the Hypervisor Label true if the Hypervisor is locked, otherwise false shows the total memory overhead true if online, otherwise false true if spare, otherwise false the date when the Group was updated in the [YYYY][MM][DD]T[hh][mm][ss]Z format the info on the Xen true if hypervisor is enabled and you can run VMs on it, otherwise false 119 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 hypervisor_type hypervisor_group_id the type of hypervisor (currently XEN or KVM) the ID of a hypervisor zone to which this hypervisor is attached disable_failover true if hypervisor failover is disabled. Otherwise false. memory_allocated_by_running_vms the hypervisor RAM in MB allocated to the VMs, which are currently running on this HV total_memory_allocated_by_vms the hypervisor RAM in MB allocated to all VMs of this HV free_disk_space GBs of hypervisor 14.4 Add a new hypervisor POST POST /settings/hypervisors.xml /settings/hypervisors.json XML Request example curl -X POST http://onapp.test/settings/hypervisors.xml -d '<hypervisor> <label>HV_LABEL</label><ip_address>HV_IP</ip_address><memory_overhead>HV_Memory</memor y_overhead><hypervisor_type>kvm/xen</hypervisor_type><enabled>true/false</enabled> <disable_failover>true/false</disable_failover><hypervisor_group_id>HV_Group_id</hyper visor_group_id></hypervisor>’ -u user:userpass -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -X POST http://onapp.test/settings/hypervisors.json -d '{hypervisor: {label:"HV_LABEL",ip_address:"HV_IP", memory_overhead:”HV_Memory”, hypervisor_type:"kvm/xen", enabled:"true/false", disable_failover:”true/false”, hypervisor_group_id:”HV_Group_id”}}' -u user:userpass -H 'Accept: application/json' -H 'Content-type: application/json' To add a new hypervisor, send the following parameters: ip_address * the Hypervisor IP address label * the name of the Hypervisor hypervisor_type * specify if this is Xen or KVM hypervisor memory_overhead Optional parameter which sets memory overhead dedicated for functional need of a hypervisor enabled Optional parameter, set True to enable a hypervisor. hypervisor_group_id * The ID of the group to which this hypervisor is 120 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 assigned. disable_failover Optional parameter. Set true to disable hypervisor failover. Otherwise false. 14.5 Edit a hypervisor PUT PUT /settings/hypervisors/:id.xml /settings/hypervisors/:id.json XML Request example curl -X PUT http://onapp.test/settings/hypervisors/:id.xml -d '<hypervisor> <label>HV_LABEL</label><ip_address>HV_IP</ip_address><memory_overhead>HV_Memory</memor y_overhead><hypervisor_type>kvm/xen</hypervisor_type><enabled>true/false</enabled><dis able_failover>true/false</disable_failover><hypervisor_group_id>HV_Group_id</hyperviso r_group_id></hypervisor>’ -u user:userpass -H 'Accept: application/xml' -H 'Contenttype: application/xml' JSON Request example curl -X PUT http://onapp.test/settings/hypervisors/:id.json -d '{hypervisor: {label:"HV_LABEL",ip_address:"HV_IP", memory_overhead:”HV_Memory”, hypervisor_type:"kvm/xen", enabled:"true/false", disable_failover:”true/false”, hypervisor_group_id:”HV_Group_id”}}' -u user:userpass -H 'Accept: application/json' -H 'Content-type: application/json' You can edit the following parameters: ip_address - the Hypervisor IP address label - the name of the Hypervisor hypervisor_type - specify if this is Xen or KVM hypervisor memory_overhead - Optional parameter which sets memory overhead dedicated for functional need of a hypervisor enabled - Optional parameter, set True to enable a hypervisor. hypervisor_group_id - set ID of the hypervisor zone to attach this hypervisor to it, or send the empty value to remove the hypervisor from the hypervisor zone. disable_failover – set true to disable hypervisor failover. Otherwise false. 14.6 Reboot a hypervisor POST POST /settings/hypervisors/:hypervisor_id/reboot.xml /settings/hypervisors/:hypervisor_id/reboot.json XML Request example 121 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 curl -X POST http://onapp.test/settings/hypervisors/:hypervisor_id/reboot.xml -d '<hypervisor><confirm>1</confirm><force_reboot>1</force_reboot></hypervisor>’ -u user:userpass -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -X POST http://onapp.test/settings/hypervisors/:hypervisor_id/reboot.json -d '{confirm:"1",force_reboot:"1"}' -u user:userpass -H 'Accept: application/json' -H 'Content-type: application/json' An HTTP 201 response is returned on a successful reboot. Unsuccessful reboot responses include HTTP 404 (resource not found – e.g. if the Hypervisor isn’t online) and HTTP 422 (request cannot be processed – e.g. if parameters were incorrect). 14.7 Get the list of VMs running on the hypervisor GET GET /hypervisors/:hypervisor_id/virtual_machines.xml /hypervisors/:hypervisor_id/virtual_machines.json Returns the list of virtual machines deployed on the hypervisor. For details, see Get the list of VMs section. 14.8 Get the list of data store joins attached to the hypervisor To get the list of hypervisor data store joins (data stores which are attached to the hypervisor), use the following request: GET GET /settings/hypervisors/:hypervisor_id/data_store_joins.xml /settings/hypervisors/:hypervisor_id/data_store_joins.json XML Output example <?xml version="1.0" encoding="UTF-8"?> <data_store_joins type="array"> <data_store_join> <created_at type="datetime">2011-10-11T12:50:02+03:00</created_at> <data_store_id type="integer">2</data_store_id> <hypervisor_id nil="true"></hypervisor_id> <id type="integer">7</id> <target_join_id type="integer">2</target_join_id> <target_join_type>Hypervisor</target_join_type> <updated_at type="datetime">2011-10-11T12:50:02+03:00</updated_at> </data_store_join> ... <data_store_join></data_store_join> ... </data_store_joins> 122 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 Where: data_store_id - the ID of the data store, which is attached to the hypervisor hypervisor_id - reserved parameter id - the join ID target_join_id - the ID of the join target; in this case it is the hypervisor ID target_join_type - type of join target; in this case it is Hypervisor 14.9 Add a data store join to the hypervisor To add a data store to the hypervisor, use the following request to create a data store join: POST /settings/hypervisors/:hypervisor_id/data_store_joins.xml POST /settings/hypervisors/:hypervisor_id/data_store_joins.json XML Request example curl -i -X POST http://onapp.test/settings/hypervisors/:hypervisor_id/data_store_joins.xml -d '<data_store_id>5</data_store_id>' -u admin:passwod -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X POST http://onapp.test/settings/hypervisors/:hypervisor_id/data_store_joins.json -d '{"data_store_id":"5"}' -u admin:passwod -H 'Accept: application/json' -H 'Contenttype: application/json' This request creates a data store join, attaching a data store (data_store_id *) to a specified hypervisor. 14.10 Remove a data store join from the hypervisor DELETE /settings/hypervisors/:hypervisor_id/data_store_joins/:id.xml DELETE /settings/hypervisors/:hypervisor_id/data_store_joins/:id.json XML Request example curl -i -X DELETE http://onapp.test/settings/hypervisors/:hypervisor_id/data_store_joins/:data_store_joi n_id.xml -u admin:passwod -H 'Accept: application/xml' -H 'Content-type: application/xml' 123 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 JSON Request example curl -i -X DELETE http://onapp.test/settings/hypervisors/:hypervisor_id/data_store_joins/:data_store_joi n_id.json -u admin:passwod -H 'Accept: application/json' -H 'Content-type: application/json' 14.11 Get the list of network joins of the hypervisor To see the network joins of the hypervisor, use the following request: GET /settings/hypervisors/:hypervisor_id/network_joins.xml GET /settings/hypervisors/:hypervisor_id/network_joins.json XML Output example <?xml version="1.0" encoding="UTF-8"?> <network_joins type="array"> <network_join> <created_at type="datetime">2011-11-15T13:27:38+03:00</created_at> <hypervisor_id nil="true"></hypervisor_id> <id type="integer">5</id> <interface>eth0</interface> <network_id type="integer">1</network_id> <target_join_id type="integer">2</target_join_id> <target_join_type>Hypervisor</target_join_type> <updated_at type="datetime">2011-11-15T13:27:38+03:00</updated_at> </network_join> </network_joins> Where: hypervisor_id – reserved parameter id - the network join ID interface - label of the network interface used to create a network join target_join_id - the ID of the join target; in this case it is the hypervisor ID target_join_type - type of join target; in this case it is Hypervisor 14.12 Add a network join to the hypervisor To create a network join (assign the network to the hypervisor), use the following request: POST /settings/hypervisors/:hypervisor_id/network_joins.xml POST /settings/hypervisors/:hypervisor_id/network_joins.json XML Request example 124 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 curl -i -X POST http://onapp.test/settings/hypervisors/:hypervisor_id/network_joins.xml -d '<network_join><network_id>4</network_id><interface>interface_test</interface></networ k_join>' -u user:userpass -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON request example curl -i -X POST http://onapp.test/settings/hypervisors/:hypervisor_id/network_joins.json -d '{"network_join":{"network_id":"4", "interface":"interface_test"}}' -u user:userpass H 'Accept: application/json' -H 'Content-type: application/json' Send the following parameters: network_id * - ID of the network you wish to attach interface * - the name of the appropriate network interface 14.13 Remove a network join from the hypervisor DELETE /settings/hypervisors/:hypervisor_id/network_joins/:id.xml DELETE /settings/hypervisors/:hypervisor_id/network_joins/:id.json XML Request example curl -i -X DELETE http://onapp.test/settings/hypervisors/:hypervisor_id/network_joins/:network_join_id.x ml -u admin:passwod -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X DELETE http://onapp.test/settings/hypervisors/:hypervisor_id/network_joins/:network_join_id.j son -u admin:passwod -H 'Accept: application/json' -H 'Content-type: application/json' Returns HTTP 200 response on successful deletion or HTTP 404 when a resolver with the ID specified is not found, or the URL requested is incorrect. 14.14 DELETE DELETE Delete a hypervisor /settings/hypervisors/:id.xml /settings/hypervisors/:id.json XML Request example 125 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 curl -i -X DELETE http://onapp.test/settings/hypervisors/:hypervisor_id.xml -u user:userpass -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X DELETE http://onapp.test/settings/hypervisors/:hypervisor_id.json -u user:userpass -H 'Accept: application/json' -H 'Content-type: application/json' Returns HTTP 200 response on successful deletion, or HTTP 404 when a hypervisor with the ID specified is not found, or the URL requested is incorrect. 126 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 15. Networks The class enables you to modify network configurations. The network resources available to the entire cloud can be configured in the system Control Panel or via API. Specific network resources can be set up manually, and automatically on VM creation. 15.1 Get the list of networks GET GET /settings/networks.xml /settings/networks.json XML Output example <?xml version="1.0" encoding="UTF-8"?> <networks type="array"> <network> <label>Public Network</label> <created_at type="datetime">2011-02-11T12:46:09+02:00</created_at> <network_group_id type="integer">3</network_group_id> <updated_at type="datetime">2011-02-11T13:20:09+02:00</updated_at> <id type="integer">1</id> <vlan type="integer" nil="true"/> <identifier>4ikgi2ges03kma</identifier> </network> </networks> Where: created_at Id Label updated_at the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format the network ID the optional Network label the date when the Network was updated in the [YYYY][MM][DD]T[hh][mm][ss]Z format Vlan the VLAN this network belongs to network_group_id the ID of the network zone to which this network is attached 15.2 Get network details GET GET /settings/networks/:id.xml /settings.networks/:id.json XML Output example <?xml version="1.0" encoding="UTF-8"?> <network> <label>public</label> <created_at type="datetime">2010-10-28T19:55:40+07:00</created_at> <updated_at type="datetime">2010-12-29T22:31:15+07:00</updated_at> 127 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 <network_group_id type="integer">2</network_group_id> <vlan type="integer">391</vlan> <id type="integer">1</id> <identifier>hc9fut4iogxt7p</identifier> </network> Where: label — the optional Network label created_at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format updated_at — the date when the record was updated in the [YYYY][MM][DD]T[hh][mm][ss]Z format network_group_id — the ID of the network zone to which this network is attached id — the network ID vlan — the VLAN this network belongs to identifier — network identifier 15.3 Edit a network PUT PUT /settings/networks/:id.xml /settings/networks/:id.json XML Request Example curl -i -X PUT -u user:userpass -H 'Accept: application/xml' -H 'Content-type: application/xml' -d '<network><label>Network API test</label><network_group_id>3</network_group_id><vlan>1</vlan></network>' --url http://onapp.test/settings/networks/:id.xml JSON Request Example curl -i -X PUT -u user:userpass -H 'Accept: application/json' -H 'Content-type: application/json' -d '{"network":{"label":"Network API TEST","network_group_id":15,"vlan":2}}' --url http://onapp.test/settings/networks/:id.json Parameters: id – the network ID label - the network name vlan – the VLAN this network belongs to network_group_id – the ID of the network zone to which this network is attached 128 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 15.4 Rebuild VM network To rebuild the network for a particular VM, use the following request: POST POST /virtual_machines/:virtual_machine_id/rebuild_network.xml /virtual_machines/:virtual_machine_id/rebuild_network.json XML Request example curl -X POST -u user:userpass http://onapp.test/virtual_machines/:virtual_machine_id/rebuild_network.xml -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -X POST -u user:userpass http://onapp.test/virtual_machines/:virtual_machine_id/rebuild_network.json -H 'Accept: application/json' -H 'Content-type: application/json' 15.5 Add a network POST POST /settings/networks.xml /settings/networks.json XML Request example curl -i -X POST -u user:userpass -H 'Accept: application/xml' -H 'Content-type: application/xml' -d '<network><label>Network API test 34</label><network_group_id>15</network_group_id><vlan>34</vlan></network>' --url http://onapp.test/settings/networks.xml JSON Request example curl -i -X POST -u user:userpass -H 'Accept: application/json' -H 'Content-type: application/json' -d '{"network":{"label":"Network API TEST 2","network_group_id":3,"vlan":true}}' --url http://onapp.test/settings/networks.json Parameters: label * - the network name vlan – the VLAN this network belongs to network_group_id – the ID of the network zone to which this network is attached 129 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 15.6 Delete a network DELETE DELETE /settings/networks/:id.xml /settings/networks/:id.json XML Request example curl -i -X DELETE -u user:userpass --url http://onapp.test/settings/networks/:id.xml JSON Request example curl -i -X DELETE -u user:userpass --url http://onapp.test/settings/networks/:id.json 130 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 16. Network Interfaces This class represents the methods required to manage Network Interfaces. Network interfaces connect VMs with the network. You can allocate several network interfaces to a VM. 16.1 Get the list of VM network interfaces To get the list of network interfaces allocated to this particular VM: GET GET /virtual_machines/:virtual_machine_id/network_interfaces.xml /virtual_machines/:virtual_machine_id/network_interfaces.json XML Output example <?xml version="1.0" encoding="UTF-8"?> <network_interfaces type="array"> <network_interface> <label>eth0</label> <usage nil="true"></usage> <created_at type="datetime">2011-03-18T17:45:07+07:00</created_at> <updated_at type="datetime">2011-04-08T18:57:20+07:00</updated_at> <primary type="boolean">true</primary> <usage_month_rolled_at nil="true"></usage_month_rolled_at> <id type="integer">502</id> <mac_address>00:16:3e:50:35:52</mac_address> <usage_last_reset_at nil="true"></usage_last_reset_at> <default_firewall_rule>DROP</default_firewall_rule> <rate_limit type="integer">0</rate_limit> <virtual_machine_id type="integer">518</virtual_machine_id> <network_join_id type="integer">4</network_join_id> <identifier>pdfjrtpkday9e1</identifier> </network_interface> ... <network_interface></network_interface> ... </network_interfaces> Where: label - network interface name created_at - the timestamp in the database when this network interface was created updated_at - the timestamp in the database when this network interface was updated primary - True if this network interface is primary, otherwise false id - the ID of this network interface mac_address – network interface mac address 131 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 rate_limit - port speed in Mbps identifier - the identifier in the database of this network interface network_join_id - the ID of the network join to which this network interface belongs virtual_machine_id - the ID of a virtual machine to which this network interface is attached 16.2 Get network interface details To get a particular network interface details: GET /virtual_machines/:virtual_machine_id/network_interfaces/:id.xml GET /virtual_machines/:virtual_machine_id/network_interfaces/:id.json This request will output details for a network interface. The explanation of the fields is the same as for Get the list of VM network interfaces method. 16.3 Edit a network interface To edit network interface details: PUT PUT /virtual_machines/:virtual_machine_id/network_interfaces/:id.xml /virtual_machines/:virtual_machine_id/network_interfaces/:id.json XML Request example curl -i -X PUT -u user:userpass -H 'Accept: application/xml' -H 'Content-type: application/xml' -d '<network_interface><label>eth0(test)</label><rate_limit>64</rate_limit><primary>true< /primary></network_interface>' --url http://onapp.test/virtual_machines/:virtual_machine_id/network_interfaces/:id.xml JSON Request example curl -i -X PUT -u user:userpass -H 'Accept: application/json' -H 'Content-type: application/json' -d '{"network_interface":{"label":"eth0(test 2)","rate_limit":"32","primary":"false"}}' --url http://onapp.test/virtual_machines/:virtual_machine_id/network_interfaces/:id.json You can change rate_limit and label parameters. 16.4 Add a network interface to a VM To add a new network interface: 132 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 POST POST /virtual_machines/:virtual_machine_id/network_interfaces.xml /virtual_machines/:virtual_machine_id/network_interfaces.json XML Request example curl -i -X POST -u user:userpass -H 'Accept: application/xml' -H 'Content-type: application/xml' -d '<network_interface><label>qwert</label><rate_limit>64</rate_limit><network_join_id>3< /network_join_id></network_interface>' --url http://onapp.test/virtual_machines/:virtual_machine_id/network_interfaces.xml JSON Request example curl -i -X POST -u user:userpass -H 'Accept: application/json' -H 'Content-type: application/json' -d '{"network_interface":{"label":"qwert","rate_limit":"64","network_join_id":"3"}}' -url http://onapp.test/virtual_machines/:virtual_machine_id/network_interfaces.json Where: label * - give the label of a network interface you wish to attach rate_limit* - set the port speed of a network interface you wish to attach network_join_id * - set the ID of a physical network used to attach this network interface primary * – set 1 if the interface is primary. Otherwise false. 16.5 Delete a network interface To delete a network interface from a virtual machine: DELETE DELETE /virtual_machines/:virtual_machine_id/network_interfaces/:id.xml /virtual_machines/:virtual_machine_id/network_interfaces/:id.json XML Request example curl -i -X DELETE -u user:userpass --url http://onapp.test/virtual_machines/:virtual_machine_id/network_interfaces/:id.xml JSON Request example curl -i -X DELETE -u user:userpass --url http://onapp.test/virtual_machines/:virtual_machine_id/network_interfaces/:id.json 133 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 This returns an HTTP 200 response if the network interface is deleted, or HTTP 404 if the network interface with the specified ID isn’t found or the requested URL is incorrect. 134 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 17. IP Addresses This class represents all the IP addresses in your installation. Use the following methods to edit, create new and delete an existing IP addresses in your cloud. 17.1 Get the list of network IP addresses GET GET /settings/networks/:network_id/ip_addresses.xml /settings/networks/:network_id/ip_addresses.json XML Output example <?xml version="1.0" encoding="UTF-8"?> <ip_addresses type="array"> <ip_address> <netmask>255.255.255.240</netmask> <disallowed_primary type="boolean">true</disallowed_primary> <address>83.170.81.179</address> <created_at type="datetime">2010-10-28T19:56:50+07:00</created_at> <updated_at type="datetime">2011-05-17T17:53:23+07:00</updated_at> <network_id type="integer">1</network_id> <network_address>83.170.81.176</network_address> <broadcast>83.170.81.191</broadcast> <id type="integer">2</id> <gateway>83.170.81.177</gateway> <free type="boolean">false</free> </ip_address> ... <ip_address></ip_address> ... </ip_addresses> Where: ip_addresses – an array with all IP addresses in the selected network netmask — netmask for the IP address disallowed_primary – true if not allowed to be used as primary (for VM build), otherwise false address – IP address created_at — the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format updated_at — the date when the Network was updated in the [YYYY][MM][DD]T[hh][mm][ss]Z format network_id –the ID of the network network_address – the address of the network broadcast – broadcast address id –the ID of the IP address gateway – gateway address free – true if free, otherwise false 135 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 17.2 Edit an IP address PUT PUT /settings/networks/:network_id/ip_addresses/:id.xml /settings/networks/:network_id/ip_addresses/:id.json XML Request example curl -i -X PUT -H 'Accept: application/xml' -H 'Content-type: application/xml' -u user:userpass -d '<ip_address><address>109.123.105.192</address><netmask>255.255.255.240</netmask><broa dcast>109.123.105.191</broadcast><network_address>109.123.105.176</network_address><di sallowed_primary>true</disallowed_primary><gateway>109.123.105.177</gateway></ip_addre ss>' --url http://onapp.test/settings/networks/:network_id/ip_addresses/:id.xml JSON Request example curl -i -X PUT -H 'Accept: application/json' -H 'Content-type: application/json' -u user:userpass -d '{"ip_address":{"address":"109.123.105.186","netmask":"255.255.255.240","broadcast":"1 09.123.105.191",“disallowed_primary”:”true”,"network_address":"109.123.105.176","gatew ay":"109.123.105.177"}}' --url http://onapp.test/settings/networks/:network_id/ip_addresses/:id.json The following parameters can be passed to be changed: address, netmask, broadcast, network_address, gateway, disallowed_primary option (all strings) Returns HTTP 201 on success. You can get the list of IPs assigned to a VM with GET /virtual_machines/:id request. 17.3 Create an IP address record POST POST /settings/networks/:network_id/ip_addresses.xml /settings/networks/:network_id/ip_addresses.json XML Request example curl -i -X POST -H 'Accept: application/xml' -H 'Content-type: application/xml' -u user:userpass -d '<ip_address><address>109.123.105.192</address><netmask>255.255.255.240</netmask><broa dcast>109.123.105.191</broadcast><disallowed_primary>true</disallowed_primary><network _address>109.123.105.176</network_address><gateway>109.123.105.177</gateway></ip_addre ss>' --url http://onapp.test/settings/networks/:network_id/ip_addresses.xml JSON Request example 136 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 curl -i -X POST -H 'Accept: application/json' -H 'Content-type: application/json' -u user:userpass -d '{"ip_address":{"address":"109.123.105.192","netmask":"255.255.255.240","broadcast":"1 09.123.105.191",“disallowed_primary”:”true”,"network_address":"109.123.105.176","gatew ay":"109.123.105.177"}}' --url http://onapp.test/settings/networks/:network_id/ip_addresses.json Parameters: address* - IP address netmask* - network mask broadcast* - a logical address at which all devices connected to a multiple-access communications network are enabled to receive datagrams. network_address* - IP address of the network gateway* - gateway address disallowed_primary – set true, not to use this address as primary (for VM build). Otherwise, set false XML Output example <?xml version="1.0" encoding="UTF-8"?> <ip-addresses type="array"> <ip_address> <address>109.123.105.192</address> <netmask>255.255.255.240</netmask> <created_at type="datetime">2010-04-27T16:58:01Z</created_at> <broadcast>109.123.105.191</broadcast> <network_address>109.123.105.176</network_address> <network-id type="integer">1</network_id> <updated_at type="datetime">2010-04-27T16:58:01Z</updated_at> <id type="integer">1</id> <gateway>109.123.105.177</gateway> </ip_address> </ip_addresses> 17.4 Delete an IP address DELETE DELETE /settings/networks/:network_id/ip_addresses/:id.xml /settings/networks/:network_id/ip_addresses/:id.json XML Request example curl -i -X DELETE -u user:userpass --url http://onapp.test/settings/networks/:network_id/ip_addresses/:id.xml JSON Request example 137 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 curl -i -X DELETE -u user:userpass --url http://onapp.test/settings/networks/:network_id/ip_addresses/:id.json 138 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 18. IP address joins An IP address allocated to a VM is an IP address join. , use the following methods to view, assign and delete an existing IP address joins in your cloud. 18.1 Get the list of IP address joins To get the list of IP address assignments for a particular VM: GET GET /virtual_machines/:virtual_machine_id/ip_addresses.xml /virtual_machines/:virtual_machine_id/ip_addresses.json An array of IP addresses is returned: <?xml version="1.0" encoding="UTF-8"?> <ip_address_joins type="array"> <ip_address_join> <ip_address_id type="integer">5</ip_address_id> <created_at type="datetime">2011-07-19T12:29:10Z</created_at> <updated_at type="datetime">2011-07-19T12:29:10Z</updated_at> <ip_address> <netmask>255.255.255.240</netmask> <disallowed_primary type="boolean">false</disallowed_primary> <address>109.123.105.182</address> <created_at type="datetime">2011-07-14T15:43:09Z</created_at> <updated_at type="datetime">2011-07-14T15:43:09Z</updated_at> <network_id type="integer">1</network_id> <network_address>109.123.105.176</network_address> <broadcast>109.123.105.191</broadcast> <id type="integer">5</id> <free type="boolean">false</free> <gateway>109.123.105.177</gateway> </ip_address> <id type="integer">46</id> <network_interface_id type="integer">34</network_interface_id> </ip_address_join> </ip_address_joins> Where: ip_address_joins – an array of all IP addresses, assigned to VM ip_address _id – ID of IP address created_at - the timestamp in DB when this record was created updated_at - the timestamp in DB when this record was updated ip_address – an array of IP address, assigned to the VM (for details see section Get the list of network IP addresses) id – ID of the IP address join 139 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 network_interface_id - the ID of the network interface to which this IP address should be assigned 18.2 Assign an IP address join to a VM Use the following class to assign an IP Address to a virtual machine: POST POST /virtual_machines/:virtual_machine_id/ip_addresses.xml /virtual_machines/:virtual_machine_id/ip_addresses.json XML Request example curl -i -X POST -H 'Accept: application/xml' -H 'Content-type: application/xml' -u user:userpass -d '<ip_address_join><ip_address_id>13</ip_address_id><network_interface_id>84</network_i nterface_id></ip_address_join>' --url http://onapp.test/virtual_machines/:virtual_machine_id/ip_addresses.xml JSON Request example curl -i -X POST -H 'Accept: application/json' -H 'Content-type: application/json' -u user:userpass -d '{"ip_address_join":{"ip_address_id":"13","network_interface_id":"84"}}' --url http://onapp.test/virtual_machines/:virtual_machine_id/ip_addresses.json Where: ip_address_id * network_interface_id * enter the ID of the IP you wish to attach to this VM specify the ID of network interface this IP address should be assigned to 18.3 Delete an IP address join To delete an IP address assignment from a particular VM, you have to remove the IP and rebuild the network. There are two API calls for IP deletion: one unassigns an address, but actually leaves it on a VM, and the second removes the address, rebuilds the network and thus reboots a VM. To delete an IP address without rebuilding a network: DELETE DELETE /virtual_machines/:virtual_machine_id/ip_addresses/:id.xml /virtual_machines/:virtual_machine_id/ip_addresses/:id.json XML Request example curl -i -X DELETE -u user:userpass —url http://onapp.test/virtual_machines/:virtual_machine_id/ip_addresses/:id.xml 140 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 JSON Request example curl -i -X DELETE -u user:userpass —url http://onapp.test/virtual_machines/:virtual_machine_id/ip_addresses/:id.json To delete an IP address and rebuild a network: DELETE /virtual_machines/:virtual_machine_id/ip_addresses/:id.xml?rebuild_network=1 DELETE /virtual_machines/:virtual_machine_id/ip_addresses/:id.json?rebuild_network=1 XML Request example curl -i -X DELETE -u user:userpass —url http://onapp.test/virtual_machines/:virtual_machine_id/ip_addresses/:id.xml?rebuild_ne twork=1 JSON Request example curl -i -X DELETE -u user:userpass —url http://onapp.test/virtual_machines/:virtual_machine_id/ip_addresses/:id.json?rebuild_n etwork=1 141 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 19. Data stores Data stores provide disk space for your virtual machines and operating systems. Data stores are attached to hypervisors, and may also form part of a data store zone. All CRUD operations are available to data stores. 19.1 Get the list of data stores GET GET /settings/data_stores.xml /settings/data_stores.json XML Output example <?xml version="1.0" encoding="UTF-8"?> <data-stores type="array"> <data_store> <label>SAN1</label> <created_at type="datetime">2010-04-27T15:55:08Z</created_at> <updated_at type="datetime">2010-08-04T09:02:15Z</updated_at> <id type="integer">1</id> <local_hypervisor_id type="integer" nil="true"></local_hypervisor_id> <data_store_size type="integer">890</data_store_size> <identifier>radar-san1</identifier> </data_store> </data_stores> Where: created_at data_store_size Id Label local_hypervisor_id updated_at data_store_group_id zombie_disk_size Enabled the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format the size of your data store shown in GB the data store ID the data store label the ID of the Hypervisors using this Data Store the date when the Data Store was updated in the [YYYY][MM][DD]T[hh][mm][ss]Z format the ID of a data store zone to which a particular data store is attached the size of zombie disks attached to this data store in GB. True if a data store is enabled and you can attach disks to it. Otherwise, false. 19.2 Get data store details To get details of a particular data store, use this request: GET GET /settings/data_stores/:id.xml /settings/data_stores/:id.json 142 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 XML Output example <?xml version="1.0" encoding="UTF-8"?> <data_store> <label>SAN1</label> <created_at type="datetime">2010-10-28T03:18:51+07:00</created_at> <updated_at type="datetime">2011-07-19T21:21:42+07:00</updated_at> <zombie_disks_size type="integer">93</zombie_disks_size> <id type="integer">1</id> <enabled type="boolean">true</enabled> <data_store_group_id type="integer">1</data_store_group_id> <ip nil="true"></ip> <local_hypervisor_id nil="true"></local_hypervisor_id> <identifier>onapp-9yblt1m70pdtdp</identifier> <data_store_size type="integer">500</data_store_size> <raw_stats type="array"/> </data_store> Where: created_at — the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format data_store_size — the size of your data store shown in GB id — the data store ID label — the data store label local_hypervisor_id — the ID of the Hypervisors using this Data Store updated_at — the date when the Data Store was updated in the [YYYY][MM][DD]T[hh][mm][ss]Z format data_store_group_id — the ID of a data store zone to which a particular data store is attached zombie_disk_size — the size of zombie disks attached to this data store in GB. enabled — true if a data store is enabled and you can attach disks to it. Otherwise, false. 19.3 Add a new data store POST POST /settings/data_stores.xml /settings/data_stores.json XML Output example curl -i -X POST http://onapp.test/settings/data_stores.xml -d ‘<data_store><label>:DS_label</label><data_store_group>DS_zone_id</data_store_group><i p>:DS_ip</ip><enabled>true/false</enabled><data_store_size>DS_size</data_store_size></ data_store>’ -u user:userpass -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example 143 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 curl -i -X POST http://onapp.test/settings/data_stores.json -d ‘{data_store:{label:"DS_label",data_store_group:"DS_zone_id",ip"DS_ip",enabled:"true/f alse",data_store_size:"DS_size"}}’ -u user:userpass -H 'Accept: application/json' -H 'Content-type: application/json' Parameters: label * - the data store name data_store_group * - the group to which this DS is assigned ip * - the data store IP enabled * - set 1 if data store is enabled, otherwise set 0 data_store_size * - set size in GB 19.4 Edit a data store PUT PUT /settings/data_stores/:id.xml /settings/data_stores/:id.json You can edit the data store disk capacity and label. XML Request example curl -i -X PUT http://onapp.test/settings/data_stores/:data_store_id.xml -d ‘<data_store><label>:DS_label</label><data_store_group>DS_zone_id</data_store_group><i p>:DS_ip</ip><enabled>true/false</enabled><data_store_size>DS_size</data_store_size></ data_store>’ -u user:userpass -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X PUT http://onapp.test/settings/data_stores/:data_store_id.json -d ‘{data_store:{label:"DS_label",data_store_group:"DS_zone_id",ip"DS_ip",enabled:"true/f alse",data_store_size:"DS_size"}}’ -u user:userpass -H 'Accept: application/json' -H 'Content-type: application/json' XML Output example <?xml version="1.0" encoding="UTF-8"?> <data_store> <data_store_size>{SIZE}</data_store_size> <label>{LABEL}</label> </data_store> 144 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 19.5 Delete a data store DELETE DELETE /settings/data_stores/:id.xml /settings/data_stores/:id.json XML Request example curl -i -X DELETE http://onapp.test/settings/data_stores/:data_store_id.xml -u user:userpass -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X DELETE http://onapp.test/settings/data_stores/:data_store_id.json -u user:userpass -H 'Accept: application/json' -H 'Content-type: application/json' 145 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 20. Backup servers The backup servers feature allows users to store their backups and templates on the backup servers set up in the cloud. Backup servers can be organized into backup server zones. All API calls are available to this class. 20.1 Get the list of backup servers GET GET /settings/backup_servers.xml /settings/backup_servers.json Returns the array of backup servers. XML Output example <?xml version="1.0" encoding="UTF-8"?> <backup_servers type="array"> <backup_server> <label>bk1</label> <created_at type="datetime">2012-01-04T10:18:59Z</created_at> <updated_at type="datetime">2012-01-16T14:11:30Z</updated_at> <backup_server_group_id type="integer">28</backup_server_group_id> <id type="integer">1</id> <enabled type="boolean">true</enabled> <backups type="array"> <backup> <marked_for_delete type="boolean">false</marked_for_delete> <disk_id type="integer">3908</disk_id> <built_at type="datetime">2012-02-09T16:05:21Z</built_at> <operating_system_distro>rhel</operating_system_distro> <created_at type="datetime">2012-02-09T16:03:45Z</created_at> <template_id type="integer">233</template_id> <operating_system>linux</operating_system> <updated_at type="datetime">2012-02-09T16:05:21Z</updated_at> <backup_type>normal</backup_type> <allowed_swap type="boolean">true</allowed_swap> <allow_resize_without_reboot type="boolean">false</allow_resize_without_reboot> <id type="integer">1508</id> <backup_server_id type="integer">1</backup_server_id> <allowed_hot_migrate type="boolean">false</allowed_hot_migrate> <backup_size>175264</backup_size> <min_disk_size type="integer">5</min_disk_size> <identifier>pkg0v4k4n34ym8</identifier> <locked type="boolean">false</locked> <built type="boolean">true</built> </backup> </backup_server> </backup_servers> Where: • Backup server: 146 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 • label – the backup server label created_at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format updated_at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format backup_server_group_id – the ID of a backup server group the backup server belongs to id – the backup server ID enabled – backup server parameter; if “enabled” = true, the backup server is enabled; if enabled = false, the backup server is disabled. Backups: marked_for_delete – the backup is marked for deletion (for autobackups) disk_id – the ID of a disk backed up built_at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format operating_system_distro – the OS distribution of the VM from which the backup was created created_at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format template_id – the ID of the template the VM is based on updated_at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format backup_type – disk backup type (normal, Days-autobackup, Weeks-autobackup, Months-autobackup, Years-autobackup) allowed_swap – true if the template to which the backup can be restored will allow swap, otherwise false. allow_resize_without_reboot – true if the template to which the backup can be restored will support resize without reboot option, otherwise false id – the backup ID backup_server_id – the ID of the backup server on which the backup is stored. allowed_hot_migrate – true if the template to which the backup can be restored will support hot migration, otherwise false. backup_size – the size of the backup min_disk_size – minimum disk size required for restoring a backup identifier – the backup identifier locked – true if the backup is being built, otherwise false built – true if the backup is already built, otherwise false 20.2 Get backup server details This method outputs the details for a particular backup server: GET GET /settings/backup_servers/:id.xml /settings/backup_servers/:id.json XML Output example <backup_server> <label>bk1</label> 147 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 <created_at type="datetime">2012-01-04T1204T10:18:59+02:0059Z</created_at> <backups type="array"> <backup> <marked_for_delete type="boolean">false</marked_for_delete> <disk_id type="integer">4097</disk_id> <built_at nil="true"/> <operating_system_distro>rhel</operating_system_distro> <created_at type="datetime">2012-02-11T00:36:17Z</created_at> <template_id type="integer">211</template_id> <operating_system>linux</operating_system> <updated_at type="datetime">2012-03-05T13:42:15+02:0002-11T00:36:17Z</updated_at> <backup_type>months-autobackup</backup_type> <allowed_swap type="boolean">true</allowed_swap> <allow_resize_without_reboot type="boolean">true</allow_resize_without_reboot> <id type="integer">1526</id> <backup_server_id type="integer">1</backup_server_id> <allowed_hot_migrate type="boolean">true</allowed_hot_migrate> <backup_size nil="true"/> <min_disk_size nil="true"/> <identifier>gmkrf5k0s4hsnj</identifier> <locked type="boolean">true</locked> <built type="boolean">false</built> </backup> </backups> <updated_at type="datetime">2012-02-14T14:01:20Z</updated_at> <backup_server_group_id nil="true"/>type="integer">28</backup_server_group_id> <id type="integer">1</id> <enabled type="boolean">true</enabled> <capacity type="integer">460</capacity> <ip_address>109.123.105.162</ip_address> </backup_server> Where: label – backup server label created at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format updated at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format id –backups – a list of backups stored on this backup server IDwith the following details: template_id – the ID of the template the VM from which the backup was created was based on operating_system – the operating system of the VM from which the backup was created backup_server_group_id – the ID of the backup server zone the backup server belongs to id – the backup server ID enabled – backup server parameter; if “enabled” = true, the backup server will be enabled; if enabled=false, the backup server iswill be disabled. capacity – the backup server capacity 148 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 ip_address – the backup server IP To view the list of backups with their details, please refer to the Search backups section. 20.3 Add new backup server To create a backup server where users will be able to store backups and templats, send the following request: POST POST /settings/backup_servers.xml /settings/backup_servers.json XML Request example curl -i -X POST -u user:userpass http://onapp.test/settings/backup_servers.xml -d '<backup_server><label>az_val</label><enabled>1</enabled><capacity>40</capacity><ip_ad dress>172.0.0.1</ip_address></backup_server>' -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X POST -u user:userpass http://onapp.test/settings/backup_servers.json -d '{"backup_server":{"label":"az_val", "enabled":"1", "capacity":"40", "ip_address":"172.0.0.1"}}' -H 'Accept: application/json' -H 'Content-type: application/json' Where: label* – backup server label ip_address* – valid Ipv4 address capacity* – set the backup server capacity enabled – set the “enabled” as 1 if you want the backup server to be enabled, or 0 if you want it to be disabled. If you skip the enabled parameter, the backup server will be disabled by default. XML Output example <?xml version="1.0" encoding="UTF-8"?> <backup_server> <label>az_val_1</label> <created_at type="datetime">2012-02-10T15:14:53Z</created_at> <updated_at type="datetime">2012-02-10T15:14:53Z</updated_at> <backup_server_group_id nil="true"></backup_server_group_id> 149 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 <id type="integer">25</id> <enabled type="boolean">true</enabled> <backups type="array"/> <capacity type="integer">40</capacity> <ip_address>172.0.0.2</ip_address> </backup_server> 20.4 Edit a backup server Use the following method to edit a backup server: PUT PUT /settings/backup_server/:id.xml /settings/backup_server/:id.json XML Request example curl -i -X PUT -u user:userpass http://onapp.test/settings/backup_servers/:id.xml -d '<backup_server><label>az_val_ue_xml</label><enabled>1</enabled><capacity>40</capacity ><ip_address>172.0.0.2</ip_address></backup_server>' -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X PUT -u user:userpass http://onapp.test/settings/backup_servers/:id.json -d '{"backup_server":{"label":"az_val_ue_json", "enabled":"1", "capacity":"40", "ip_address":"172.0.0.1"}}' -H 'Accept: application/json' -H 'Content-type: application/json' Where: label – backup server label enabled – set the “enabled” as 1 if you want the backup server to be enabled, or 0 if you it to be disabled. If you skip the enabled parameter, the backup server will be disabled by default. capacity* – set the backup server capacity ip_address* – valid Ipv4 address You will get a 200 status response on success, and 404 if there is no such a backup server with a requested ID or you entered incorrect URL. 20.5 Delete a backup server DELETE DELETE /settings/backup_servers/:id.xml /settings/backup_servers/:id.json 150 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 XML Request example curl -i -X DELETE -u user:userpass http://onapp.test/settings/backup_servers/:id.xml H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X DELETE -u user:userpass http://onapp.test/settings/backup_servers/:id.json -H 'Accept: application/json' -H 'Content-type: application/json' You will get a 200 status response on success, and 404 if there is no such a backup server with a requested ID or you entered incorrect URL. 20.6 Search backups To find a backup stored at a particular backup server, use the following request: GET GET /settings/backup_servers/:id/backups_search.xml /settings/backup_servers/:id/backups_search.json You can set the following search parameters: size – set the size [from] and [to] backup search parameters to search backups by their size date – set the date [startdate] and [enddate]backup search parameters to search for backups created between two dates. The following request returns the array of backups created between 02/01/12 and 02/24/2012 dates and having the size from 10 to 300 GB. XML Request example curl -i -X GET -u user:userpass 'http://onapp.test/settings/backup_servers/1/backups_search.xml?size[from]=10&size[to] =300&period[startdate]=02/01/12&period[enddate]=02/24/2012&searching=az' -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X GET -u user:userpass 'http://onapp.test/settings/backup_servers/1/backups_search.json?size[from]=10&size[to ]=300&period[startdate]=02/01/12&period[enddate]=02/24/2012&searching=az' -H 'Accept: application/json' -H 'Content-type: application/json' 151 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 Please be aware that some Unix command shells can output an error because of square brackets. To prevent the error, use the back slash escape symbol. The example curl with back slashes is as follows: XML Request example curl -i -X GET -u user:userpass 'http://onapp.test/settings/backup_servers/1/backups_search.xml?size\[from\]=10&size\[ to\]=300&period\[startdate\]=02/01/12&period\[enddate\]=02/24/2012&searching=az' -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X GET -u user:userpass 'http://onapp.test/settings/backup_servers/1/backups_search.json?size\[from\]=10&size\ [to\]=300&period\[startdate\]=02/01/12&period\[enddate\]=02/24/2012&searching=az' -H 'Accept: application/json' -H 'Content-type: application/json' XML Output example <?xml version="1.0" encoding="UTF-8"?> <backups type="array"> <backup> <marked_for_delete type="boolean">false</marked_for_delete> <disk_id type="integer">3908</disk_id> <built_at type="datetime">2012-02-09T16:05:21Z</built_at> <operating_system_distro>rhel</operating_system_distro> <created_at type="datetime">2012-02-09T16:03:45Z</created_at> <template_id type="integer">233</template_id> <operating_system>linux</operating_system> <updated_at type="datetime">2012-02-09T16:05:21Z</updated_at> <backup_type>normal</backup_type> <allowed_swap type="boolean">true</allowed_swap> <allow_resize_without_reboot type="boolean">false</allow_resize_without_reboot> <id type="integer">1508</id> <backup_server_id type="integer">1</backup_server_id> <allowed_hot_migrate type="boolean">false</allowed_hot_migrate> <backup_size>175264</backup_size> <min_disk_size type="integer">5</min_disk_size> <identifier>pkg0v4k4n34ym8</identifier> <locked type="boolean">false</locked> <built type="boolean">true</built> </backup> </backups> Where: • backups – an array of backups stored on the backup server: For details refer to Get The List Of Backup Servers section. • • • marked_for_delete – the backup is marked for deletion (for autobackups) disk_id – the ID of a disk backed up built_at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format 152 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 • • • • • • • • • • • • • • • operating_system_distro – the OS distribution of the VM from which the backup was created created_at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format template_id – the ID of the template the VM is based on updated_at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format backup_type – disk backup type (normal, Days-autobackup, Weeks-autobackup, Monthsautobackup, Years-autobackup) allowed_swap – true if the template to which the backup can be restored will allow swap, otherwise false. allow_resize_without_reboot – true if the template to which the backup can be restored will support resize without reboot option, otherwise false id – the backup ID backup_server_id – the ID of the backup server on which the backup is stored. allowed_hot_migrate – true if the template to which the backup can be restored will support hot migration, otherwise false. backup_size – the size of the backup min_disk_size – minimum disk size required for restoring a backup identifier – the backup identifier locked – true if the backup is being built, otherwise false built – true if the backup is already built, otherwise false Note that the backup search returns only the list of backups, stored on a specified backup server, which a user has permission to see ( own backups or all backups). For instructions on how to see the list of all backup servers, refer to Get the list of all backup servers section. 153 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 21. Disks Disks provide space for virtual machine data. A disk is a partition of a data store that is allocated to a specific virtual machine. All CRUD operations are available for Disks. 21.1 Get the list of disks GET GET /settings/disks.xml /settings/disks.json XML Output example <?xml version="1.0" encoding="UTF-8"?> <disks type="array"> <disk> <has_autobackups type="boolean">false</has_autobackups> <created_at type="datetime">2011-07-19T12:29:10Z</created_at> <updated_at type="datetime">2011-07-19T12:34:46Z</updated_at> <disk_size type="integer">5</disk_size> <add_to_linux_fstab nil="true"></add_to_linux_fstab> <primary type="boolean">true</primary> <id type="integer">64</id> <data_store_id type="integer">1</data_store_id> <mount_point nil="true"></mount_point> <is_swap type="boolean">false</is_swap> <disk_vm_number type="integer">1</disk_vm_number> <virtual_machine_id type="integer">34</virtual_machine_id> <identifier>c719u80sv5mwdi</identifier> <locked type="boolean">false</locked> <built type="boolean">true</built> </disk> ... <disk></disk> ... </disks> Where: created_at primary the date when the disk was created in the [YYYY][MM][DD]T[hh][mm][ss]Z format the size of a disk the date when the disk was updated in the [YYYY][MM][DD]T[hh][mm][ss]Z format true if the disk is primary. Otherwise false. data_store_id Id disk_vm_number the ID of the data store this disk is located the disk ID the number of virtual machines using this disk disk-size updated_at 154 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 is_swap virtual_machine_id built locked has_autobackups true if this is a swap disk. Otherwise false. the ID of the virtual machine using this disk. true if the disk is built. Otherwise false. true if the disk is locked. Otherwise false. true if the disk has automatic backups set up. Otherwise false. 21.2 Get the list of VM disks To get the list of disks available for a particular VM, use the following request: GET GET /virtual_machines/:virtual_machine_id/disks.xml /virtual_machines/:virtual_machine_id/disks.json XML Output example <?xml version="1.0" encoding="UTF-8"?> <disks type="array"> <disk> <created_at type="datetime">2011-07-19T12:29:10Z</created_at> <updated_at type="datetime">2011-07-19T12:34:46Z</updated_at> <disk_size type="integer">5</disk_size> <add_to_linux_fstab nil="true"></add_to_linux_fstab> <primary type="boolean">true</primary> <id type="integer">64</id> <data_store_id type="integer">1</data_store_id> <has_autobackups type="boolean">false</has_autobackups> <mount_point nil="true"></mount_point> <is_swap type="boolean">false</is_swap> <disk_vm_number type="integer">1</disk_vm_number> <virtual_machine_id type="integer">34</virtual_machine_id> <identifier>c719u80sv5mwdi</identifier> <locked type="boolean">false</locked> <built type="boolean">true</built> </disk> ... <disk></disk> ... </disks> For description of the data returned refer to Get the list of disks section 21.3 Add a new disk POST POST /virtual_machines/:virtual_machine_id/disks.xml /virtual_machines/:virtual_machine_id/disks.json XML Request example 155 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 curl -i -X POST http://onapp.test/virtual_machines/:virtual_machine_id/disks.xml -d ‘<disk><disk_size>disk_size</disk_size><data_store_id>store_id</data_store_id><mount_p oint></mount_point><is_swap></is_swap><add_to_linux_fstab></add_to_linux_fstab></disk> ’ -u user:userpass -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X POST http://onapp.test/virtual_machines/:virtual_machine_id/disks.json -d ’{disk:{disk_size:”disk_size”,data_store_id:”data_store_id”, mount_point:”mount_point”,is_swap:””,add_to_linux_fstab:””}}’ -u user:userpass -H 'Accept: application/json' -H 'Content-type: application/json' To add a new disk, send the following required parameters: data_store_id * - The ID of a data store where this disk is located disk-size * - The disk space in GB is_swap - Set true if this is a swap disk mount_point - a physical location in the partition used as a root filesystem add_to_linux_fstab - Set true to add require_format_disk – set true to format disk 21.4 Edit a disk PUT PUT /settings/disks/:id.xml /settings/disks/:id.json XML Request example curl -i -X PUT http://onapp.test/virtual_machines/:VM_id/disks/:disk_id.xml -d ‘<disk><disk_size>new_disk_size</disk_size></disk>’ -u user:userpass -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X PUT http://onapp.test/virtual_machines/:VM_id/disks/disk_id.json -d ’{disk:{disk_size:”new_disk_size”}}’ -u user:userpass -H 'Accept: application/json' -H 'Content-type: application/json' Currently you can edit the size parameter. You also can edit a disk through another URL: onapp.test/virtual_machines/:virtual_machines_id/disks/:id 21.5 Migrate a disk To migrate a VM disk to another data store, use the following request: 156 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 POST POST /virtual_machines/:virtual_machine_id/disks/:disk_id/migrate.xml /virtual_machines/:virtual_machine_id/disks/:disk_id/migrate.json XML Request example curl -i -X POST -u user:userpass http://onapp.test/virtual_machines/:virtual_machine_id/disks/:disk_id/migrate.xml -d '<disk><data_store_id>6</data_store_id></disk>' -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X POST -u user:userpass http://onapp.test/virtual_machines/:virtual_machine_id/disks/:disk_id/migrate.json -d {"disk":{"data_store_id":"6"}} -H 'Accept: application/json' -H 'Content-type: application/json' Where: data_store_id * - the ID of a data store you migrate the disk to. Note, that you can move disks only between data stores which are attached to the same hypervisor or hypervisor group. 21.6 Delete a disk DELETE DELETE /settings/disks/:id.xml /settings/disks/:id.json XML Request example curl -i -X DELETE http://onapp.test/virtual_machines/:virtual_machine_id/disks/:disk_id.xml -u user:userpass -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X DELETE http://onapp.test/virtual_machines/:virtual_machine_id/disks/:disk_id.json -u user:userpass -H 'Accept: application/json' -H 'Content-type: application/json' Returns HTTP 200 response on successful deletion, or HTTP 404 when a disk with the ID specified is not found, or the URL requested is incorrect. 157 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 21.7 View disk IOPS To view Input/Output statistics for your disks, use the following method: GET GET /settings/disks/:id/usage.xml /settings/disks/:id/usage.json XML Output example <?xml version="1.0" encoding="UTF-8"?> <disk_hourly_stats type="array"> <disk_hourly_stat> <disk_id type="integer">64</disk_id> <created_at type="datetime">2011-07-19T13:00:10Z</created_at> <updated_at type="datetime">2011-07-19T13:00:10Z</updated_at> <writes_completed type="integer">345685</writes_completed> <stat_time type="datetime">2011-07-19T13:00:00Z</stat_time> <data_written type="integer">11061920</data_written> <data_read type="integer">53840</data_read> <id type="integer">1028</id> <user_id type="integer">13</user_id> <virtual_machine_id type="integer">34</virtual_machine_id> <reads_completed type="integer">1684</reads_completed> </disk_hourly_stat> ... <disk_hourly_stat></disk_hourly_stat> ... </disk_hourly_stats> Where: disk_id - the ID of a disk created_at - the timestamp in DB when the record was created updated_at - the timestamp in DB when the record was updated data_read – the amount of data read from this disk data_written - the amount of data written to the disk stat_time - the time when statistics were generated writes_completed - the number of completed write operations reads_completed - the number of completed read operations user_id – ID of the user whose VM is using this disk virtual_machine_id – ID of the VM using this disk 21.8 Build a disk To build a disk, use the following methods: POST POST /settings/disks/:id/build.xml /settings/disks/:id/build.json 158 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 XML Request example curl -i -X POST http://onapp.test/settings/disks/:disk_id/build.xml -u user:userpass H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X GET http://onapp.test/settings/disks/:disk_id/build.json -u user:userpass H 'Accept: application/json' -H 'Content-type: application/json' Where: disk_id * - the ID of the disk you want to build 21.9 Unlock a disk To unlock a disk, use the following methods: POST POST /settings/disks/:disk_id/unlock.xml /settings/disks/:disk_id/unlock.json XML Request example curl -i -X POST http://onapp.test/settings/disks/:disk_id/unlock.xml -u user:userpass -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X POST http://onapp.test/settings/disks/:disk_id/unlock.json -u user:userpass -H 'Accept: application/json' -H 'Content-type: application/json' 21.10 Enable autobackups for a disk You can enable autobackups for a disk using the following methods: POST POST /settings/disks/:disk_id/autobackup_enable.xml /settings/disks/:disk_id/autobackup_enable.json XML Request example curl -i -X POST http://onapp.test/settings/disks/:disk_id/autobackup_enable.xml -u user:userpass -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X POST http://onapp.test/settings/disks/:disk_id/autobackup_enable.json -u user:userpass -H 'Accept: application/json' -H 'Content-type: application/json' Where: disk_id * - is the ID of the disk, for wich you want to enable autobackup 159 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 21.11 Disable autobackups for a disk To disable autobackups for a disk, use the following method: POST POST /settings/disks/:id/autobackup_disable.xml /settings/disks/:id/autobackup_disable.json XML Request example curl -i -X POST http://onapp.test/settings/disks/:disk_id/autobackup_disable.xml -u user:userpass -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X POST http://onapp.test/settings/disks/:disk_id/autobackup_disable.json -u user:userpass -H 'Accept: application/json' -H 'Content-type: application/json' Where: disk_id * - the ID of the disk for which you want to disable autobackup 21.12 Get the list of schedules for a disk To get a list of schedules for a particular disk, use the following methods: GET GET /settings/disks/:disk_id/schedules.xml /settings/disks/:disk_id/schedules.json XML Output example <?xml version="1.0" encoding="UTF-8"?> <schedules> <schedule> <duration>1</duration> <created_at>2011-07-20T15:16:16Z</created_at> <target_id>112</target_id> <updated_at>2011-07-27T15:16:18Z</updated_at> <period>days</period> <action>autobackup</action> <start_at>2011-07-28T15:16:16Z</start_at> <id>33</id> <user_id>1</user_id> <schedule_logs> <schedule_log> <created_at>2011-07-27T15:16:18Z</created_at> <updated_at>2011-07-27T15:16:18Z</updated_at> <schedule_id>33</schedule_id> <id>10</id> <log_output></log_output> <status>complete</status> </schedule_log> ... <schedule_log></Schedule_log> ... <params nil="true"></params> <failure_count>0</failure_count> <status>enabled</status> <target_type>Disk</target_type> 160 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 </schedule> ... <schedule></schedule> </schedules> Where: duration - the number specifying how often a backup should be taken target_id – ID of the action target period - the time period (days, weeks, months, or years) action – the action performed start_at – time, when the action starts id – schedule id user_id – ID of the disk (action target) user schedule_logs – an array with schedule log details, where • • • • schedule_id – ID of a schedule id – ID of the schedule log log_output – an array with log details status – status of the action (complete, failed, etc.) failure_count – number of failures during the action status – schedule status (enabled or disabled) target_type – type of the target 21.13 Add a schedule to a disk You can add a schedule to a disk using the following method: POST POST /settings/disks/:disk_id/schedules.xml /settings/disks/:disk_id/schedules.json XML Request example curl -i -X POST http://onapp.test/settings/disks/:disk_id/schedules.xml -d ‘<schedule><action>autobackup</action><duration>1</duration><period>days</period></sch edule>’ -u user:userpass -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X POST http://onapp.test/settings/disks/:disk_id/schedules.json -d ‘{schedule:{action:”autobackup”,duration:”1”,period:”days”}}’ -u user:userpass -H 'Accept: application/json' -H 'Content-type: application/json' Where: 161 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 action * set Autobackup to add a backup schedule duration* specify duration period * set the period (days/weeks/months) 21.14 Get the list of backups available for a disk To get the list of backups available to a particular disk, use the following method: GET GET /settings/disks/:disk_id/backups.xml /settings/disks/:disk_id/backups.json An array of backups with their details is returned on success. XML Output example <?xml version="1.0" encoding="UTF-8"?> <backups type="array"> <backup> <disk_id type="integer">112</disk_id> <built_at type="datetime">2011-07-27T15:19:47Z</built_at> <operating_system_distro>rhel</operating_system_distro> <created_at type="datetime">2011-07-27T15:16:18Z</created_at> <template_id type="integer">1</template_id> <operating_system>linux</operating_system> <updated_at type="datetime">2011-07-27T15:19:47Z</updated_at> <backup_type>days-autobackup</backup_type> <allowed_swap type="boolean">true</allowed_swap> <allow_resize_without_reboot type="boolean">true</allow_resize_without_reboot> <id type="integer">12</id> <backup_server_id type="integer">1</backup_server_id> <allowed_hot_migrate type="boolean">true</allowed_hot_migrate> <backup_size>315552</backup_size> <min_disk_size type="integer">5</min_disk_size> <identifier>ytfgbj2drbs2d7</identifier> <locked type="boolean">false</locked> <built type="boolean">true</built> </backup> ... <backup></backup> ... </backups> Where: backup – an array of backup details disk_id – ID of the disk built_at – time, when the disk was built operating_system_distro – distribution of the operating system template_id – ID of the template, used for assigned VM operating_system – OS of the virtual machine, which is allocated at this disk backup_type – type of the backup (type of period: days/weeks/months/years) 162 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 allowed_swap – true, if this is a swap disk; otherwise false allow_resize_without_reboot – true, if VM’s CPU and RAM can be resized without reboot id – ID of the backup backup_server_id – the ID of the backup server where the backup is stored allowed_hot_migrate – true, if hot migration is allowed backup_size - size of the backup in Kilobytes min_disk_size – minimum disk size required in GB identifier – identifier in the DB locked – true, if the disk is locked built - true, if the disk is built 163 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 22. Templates A template is a pre-configured operating system image that contains the root directory of an operating system. There are two different kinds of template: system templates and custom templates. System templates are downloaded from the online library. Custom templates are created by backing up an existing virtual machine, and converting that backup to a template. 22.1 Get the list of system templates GET GET /templates.xml /templates.json An array of system templates is returned. If there are no templates, an empty array is returned. XML Output example <?xml version="1.0" encoding="UTF-8"?> <image_templates type="array"> <image_template> <parent_template_id nil="true"></parent_template_id> <label>Ubuntu 10.04.1 LTS</label> <operating_system_distro>ubuntu</operating_system_distro> <operating_system_arch>x64</operating_system_arch> <created_at type="datetime">2010-08-25T22:41:29+07:00</created_at> <operating_system_tail nil="true"></operating_system_tail> <operating_system>linux</operating_system> <min_memory_size nil="true"></min_memory_size> <updated_at type="datetime">2011-05-16T15:47:48+07:00</updated_at> <operating_system_edition nil="true"></operating_system_edition> <allowed_swap type="boolean">true</allowed_swap> <allow_resize_without_reboot nil="true"></allow_resize_without_reboot> <virtualization>xen,kvm</virtualization> <id type="integer">7</id> <file_name>ubuntu-10.04-x64-1.1.tar.gz</file_name> <checksum>dc406603695a5c98dfc7fb00b531c930</checksum> <version>1.0</version> <user_id nil="true"></user_id> <template_size nil="true"></template_size> <backup_server_id type="integer">1</backup_server_id> <allowed_hot_migrate type="boolean">true</allowed_hot_migrate> <min_disk_size type="integer">5</min_disk_size> <state>active</state> <cdn type="boolean">false</cdn> <disk_target_device>--xen: sda kvm: hd </disk_target_device> </image_template> ... <image_template></image_templates> ... </image_templates> Where: 164 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 image_templates – an array of all system templates and their details parent_template_id – true if this is a system template label – the template title operating_system_distro – operating system distribution operating_system_arch – architecture of the operating system created_at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format operating_system_tail – tail of the OS operating_system – operating system name min_memory_size – true if minimum memory size is required updated_at — the date when the Network was updated in the [YYYY][MM][DD]T[hh][mm][ss]Z format operating_system_edition – edition of the OS allowed_swap – true if swap is allowed, otherwise false allowed_resize_without_reboot – true if resize without reboot is allowed, otherwise false virtualization – type of virtualization (xen or kvm) which is compatible with this template id – ID of template file_name – the name of the template file checksum – file checksum version – version of the file backup_server_id – the ID of the backup server where the template is stored allowed_hot_migrate – true if hot migration is allowed, otherwise false min_disk_size – minimum disk size required to build a VM on this template (GB) state – state of the template (active, inactive) cdn – true if this template can be used for building edge servers. Otherwise false. disk_target_device – the prefix indicating the method of translating the disk to a VM by hypervisor 22.2 Get the list of custom templates (user templates) GET GET /templates/user.xml /templates/user.json The request returns the array of custom templates. An empty array is returned if there are no Custom templates. Contrary to the System templates, the Custom templates parent_template_id parameter indicates the ID of a system template, which has been converted into custom one. 22.3 Get the template details GET GET /templates/:id.xml /templates/:id.json XML output example 165 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 <?xml version="1.0" encoding="UTF-8"?> <image_template> <parent_template_id nil="true"></parent_template_id> <label>Debian 5.0 (Lenny) x64</label> <operating_system_distro>ubuntu</operating_system_distro> <operating_system_arch></operating_system_arch> <created_at type="datetime">2010-08-25T22:41:29+07:00</created_at> <operating_system_tail nil="true"></operating_system_tail> <operating_system>linux</operating_system> <min_memory_size nil="true"></min_memory_size> <updated_at type="datetime">2011-05-16T15:47:48+07:00</updated_at> <operating_system_edition nil="true"></operating_system_edition> <allowed_swap type="boolean">true</allowed_swap> <allow_resize_without_reboot nil="true"></allow_resize_without_reboot> <virtualization>xen,kvm</virtualization> <id type="integer">8</id> <file_name>debian-501-2.0.tar.gz</file_name> <checksum>5081c49c6fce9547ef1ae3e50a9dad3c</checksum> <version>2.0</version> <user_id nil="true"></user_id> <template_size nil="true"></template_size> <backup_server_id type="integer">1</backup_server_id> <allowed_hot_migrate nil="true"></allowed_hot_migrate> <min_disk_size type="integer">5</min_disk_size> <state>active</state> <cdn type="boolean">false</cdn> <disk_target_device>--xen: sda kvm: hd </disk_target_device> </image_template> Where: parent_template_id – true if this is a system template label – the template title operating_system_distro – operating system distribution operating_system_arch – architecture of the operating system created_at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format operating_system_tail – tail of the OS operating_system – operating system name min_memory_size – minimum RAM required for the template. If no minimum RAM is required – remains empty updated_at — the date when the Network was updated in the [YYYY][MM][DD]T[hh][mm][ss]Z format operating_system_edition – edition of the OS allowed_swap – true if swap is allowed, otherwise false allowed_resize_without_reboot – true if resize without reboot is allowed, otherwise false virtualization – type of virtualization (xen, kvm) id – ID of template file_name – name of the template file checksum – file checksum version – version of the file 166 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 backup_server_id – the ID of the backup server where the template is stored allowed_hot_migrate – true if hot migration is allowed, otherwise false min_disk_size – minimum disk size in GB state – state of the template (active or inactive) cdn – true if this template can be used for building edge servers. Otherwise false. disk_target_device – the prefix indicating the method of translating the disk to a VM by hypervisor 22.4 Make a template public POST POST /templates/:id/make_public.xml /templates/:id/make_public.json XML Request example curl -i -X POST -H 'Accept: application/xml' -H 'Content-type: applicaton/xml' -u user:userpass --url http://onapp.test/templates/:id/make_public.xml JSON Request example curl -i -X POST -H 'Accept: application/json' -H 'Content-type: applicaton/json' -u user:userpass --url http://onapp.test/templates/:id/make_public.json If a template is queued to be moved to a public list successfully, an HTTP 201 response is returned. Only Custom templates can be made public. 22.5 Delete a template To delete a template from the system: DELETE DELETE /templates/:id.xml /templates/:id.json XML Request example curl -i -x DELETE -u user:userpass htttp://onapp.test/templates/:id.xml -H'Contenttype: application/xml' -H'Accept: application/xml' JSON Request example curl -i -x DELETE -u user:userpass htttp://onapp.test/templates/:id.xml -H'Contenttype: application/json' -H'Accept: application/json' The system won't delete the template if it is used by any VMs. 167 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 23. Template groups Template Groups is the class that organizes all VM templates into separate groups. Each template group can be associated with a billing plan, in order to control which templates are available to different users. 23.1 See the list of template groups To get the list of all template groups created on the system: GET GET /settings/image_template_groups.xml /settings/image_template_groups.json Output example <?xml version="1.0" encoding="UTF-8"?> <image_template_groups type="array"> <image_template_group> <label>Test</label> <created_at type="datetime">2011-04-20T15:56:00+03:00</created_at> <updated_at type="datetime">2011-04-20T15:56:00+03:00</updated_at> <id type="integer">4</id> </image_template_group> </image_template_groups> Where: label – the group name created_at – the date when this record was created in database updated_at – the date when this record was updated in database ID – the group ID 23.2 Get template group details To get details of a particular template group, use the following request: GET GET /settings/image_template_groups/:id.xml /settings/image_template_groups/:id.json Output example <?xml version="1.0" encoding="UTF-8"?> <image_template_groups type="array"> <image_template_group> <label>Test</label> <created_at type="datetime">2011-04-20T15:56:00+03:00</created_at> <updated_at type="datetime">2011-04-20T15:56:00+03:00</updated_at> <id type="integer">4</id> </image_template_group> </image_template_groups> 168 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 Where: label – the group name created_at – the date when this record was created in database updated_at – the date when this record was updated in database ID – the group ID 23.3 Edit a template group To edit details of a template group: PUT PUT /settings/image_template_groups/:id.xml /settings/image_template_groups/:id.json XML Request example curl -i -X PUT -H 'Accept: application/xml' -H 'Content-type: application/xml' -u user:userpass -d '<image_template_group><label>zaza</label><options_attributes><mak>1</mak><kms_host>ed edde.fe</kms_host><kms_port>5453</kms_port><kms>1</kms><own>1</own><kms_server_label>w qqdwwqw</kms_server_labelown>1</own></options_attributes></image_template_group>' -url http://onapp.test/settings/image_template_groups/:image_template_group_id.xml JSON Request example curl -i -X PUT -H 'Accept: application/json' -H 'Content-type: application/json' -u user:userpass -d '{"image_template_group":{"label":"zaza", "options_attributes":{"mak":"1","kms_host":"ededde.fe", "kms_port":"5453", "kms":"1", "own":"1", "kms_server_label":"wqwqw", "own":"1"}}}' --url http://onapp.test/settings/image_template_groups/:image_template_group_id.json Possible parameters: label – template group name options attributes – template group configuration attributes: kms_host – KMS server host name kms_port – KMS server port mak – MAK windows licensing type kms – KVM windows type own – users’own license 169 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 kms_server_label – KMS server name XML Response example HTTP/1.1 200 OK Date: Tue, 28 Feb 2012 11:55:53 GMT Server: Apache/2.2.3 (CentOS) X-Powered-By: Phusion Passenger (mod_rails/mod_rack) 3.0.1 X-UA-Compatible: IE=Edge,chrome=1 X-Runtime: 0.122994 Cache-Control: no-cache Set-Cookie: _session_id=6596bf326a9a8569ba51d7e8048b28be; path=/; HttpOnly Status: 200 Connection: close Transfer-Encoding: chunked Content-Type: application/xml; charset=utf-8 Delete Template Group 23.4 Add a template group To add a template group, use the following request: POST POST /settings/image_template_groups.xml /settings/image_template_groups.json XML Request example curl -i -X POST -H 'Accept: application/xml' -H 'Content-type: application/xml' -u user:userpass -d '<image_template_group><label>asasasa</label><options_attributes><mak>1</mak><kms_host >ededde.fe</kms_host><kms_port>5453</kms_port><kms>1</kms><own>1</own><kms_server_labe l>wqqdwwqw</kms_server_label></options_attributes></image_template_group>' --url http://onapp.test/settings/image_template_groups.xml JSON Request example curl -i -X POST -H 'Accept: application/json' -H 'Content-type: application/json' -u user:userpass -d '{"image_template_group":{"label":"azaza", "options_attributes":{"mak":"1","", "kms_host":"ededde.fe", "kms_port":"5453", "kms":"1", "own":"1", "kms_server_label":"wqwqw"}}}' --url http://onapp.test/settings/image_template_groups.json Where: label – template group name options attributes – template group configuration attributes: kms_host – KMS server host name kms_port – KMS server port mak – MAK windows licensing type 170 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 kms – KVM windows type own – users’own license kms_server_-label – KMS server name If label is the only parameter set, the MAK window licensing type will be set on default 23.5 Delete a template group DELETE DELETE /settings/image_template_groups/:id.xml /settings/image_template_groups/:id.json XML Request example curl -i -X DELETE -u user:userpass --url http://onapp.test/settings/image_template_groups/:image_template_group_id.xml JSON Request example curl -i -X DELETE -u user:userpass --url http://onapp.test/settings/image_template_groups/:image_template_group_id.xml 23.6 Get the list of templates attached to a group To get the list of templates attached to a template group, use the following request: GET /settings/image_template_groups/:image_template_group_id/relation_group_templ ates.xml GET /settings/image_template_groups/:image_template_group_id/relation_group_templ ates.json Output example <?xml version="1.0" encoding="UTF-8"?> <relation_group_templates type="array"> <relation_group_template> <price type="decimal">10.0</price> <created_at type="datetime">2011-04-21T15:06:08+03:00</created_at> <template_id type="integer">1</template_id> <updated_at type="datetime">2011-04-21T15:06:08+03:00</updated_at> <id type="integer">2</id> <image_template_group_id type="integer">4</image_template_group_id> </relation_group_template> </relation_group_templates> Where: price – the price for the template attached to this template group 171 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 created_at – the date when this record was created in DB template_id – the ID of a template attached to this template group updated_at – the date when this record was updated in DB id – the ID of this relation image_template_group – the ID of template group to which this template is attached 23.7 Attach a template to a group To attach a template to a group, use the following request: POST /settings/image_template_groups/:image_template_group_id/relation_group_templ ates.xml POST /settings/image_template_groups/:image_template_group_id/relation_group_templ ates.json XML Request example curl -i -X POST -H 'Accept: application/xml' -H 'Content-type: application/xml' -u user:userpass -d '<relation_group_templates><template_id>12</template_id><image_template_group_id>29</i mage_template_group_id></relation_group_templates>' --url http://onapp.test/settings/image_template_groups/:image_template_groups_id/relation_gr oup_templates.xml JSON Request example curl -i -X POST -H 'Accept: application/json' -H 'Content-type: application/json' -u user:userpass -d '{“relation_group_templates”:{"template_id":"12","image_template_group_id":"29"}}' -url http://onapp.test/settings/image_template_groups/:image_template_groups_id/relation_gr oup_templates.json Returns HTTP 201 response on success. 23.8 Detach a template from a group To detach a template attached to a template group: DELETE /settings/image_template_groups/:image_template_group_id/relation_group_templ ates/:id.xml DELETE /settings/image_template_groups/:image_template_group_id/relation_group_templ 172 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 ates/:id.json XML Request example curl -i -X DELETE -u user:userpass http://onapp.test/settings/image_template_groups/:image_template_group_id/relation_gro up_templates/:id.xml JSON Request example curl -i -X DELETE -u user:userpass http://onapp.test/settings/image_template_groups/:image_template_group_id/relation_gro up_templates/:id.json 23.9 Change price for a template in the group You can change the price for a template in a particular template group using the following request: PUT /settings/image_template_groups/:image_template_group_id/relation_group_templ ates/:id.xml PUT /settings/image_template_groups/:image_template_group_id/relation_group_templ ates/:id.json XML Request example curl -i -X PUT -H 'Accept: application/xml' -H 'Content-Type: application/xml' -u user:userpass -d '<relation_group_template><price>2</price></relation_group_template>' --url http://onapp.test/settings/image_template_groups/:image_template_group_id/relation_gro up_templates/:id.xml JSON Request example curl -i -X PUT -H 'Accept: application/json' -H 'Content-Type: application/json' -u user:userpass -d '{"relation_group_template":{"price":"2"}}' --url http://onapp.test/settings/image_template_groups/:image_template_group_id/relation_gro up_templates/:id.json 173 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 24. Software Licenses When you create a virtual machine from a template based on a licensed Operating System, or other licensed software, you need to add a valid license to the system. Use the software_licenses API class to manage licenses. All methods are available to this class. 24.1 Get the list of software licenses To get the list of available software licenses, use the following requests: GET GET /software_licenses.xml /software_licenses.json Output example <?xml version="1.0" encoding="UTF-8"?> <software_licenses type="array"> <software_license> <created_at type="datetime">2011-02-18T01:34:33+02:00</created_at> <updated_at type="datetime">2011-03-16T00:31:08+02:00</updated_at> <license>TZXTC-R4GGG-9TT3V-DYDY4-T628B</license> <total type="integer">20</total> <arch>x64</arch> <id type="integer">3</id> <distro>2008</distro> <count type="integer">7</count> <tail> </tail> <edition>ENT</edition> </software_license> Where: created_at – the date when the record in DB was created updated_at - the date when the record in DB was updated license – the license for the software on which the template will be based total – the total number of machines allowed by the license arch – Windows OS architecture (x64 or x86) id – the ID of the record distro – Windows OS distribution (2003, 2008, Windows 7) count – the number of licenses used of a total allowed tail – parameter specifies the updated release of Windows OS distribution. If updated, than parameter is R2, otherwise – empty. 174 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 edition – Windows OS edition or an array of editions if allowed by the license (STD – Standard, ENT –Enterprise, WEB – web and DC – Data center) 24.2 Get software license details To get details for a particular software license, use the following method: GET GET /software_licenses/:id.xml /software_licenses/:id.json XML Output example <?xml version="1.0" encoding="UTF-8"?> <software_license> <created_at type="datetime">2011-03-01T12:42:03+02:00</created_at> <updated_at type="datetime">2011-03-08T13:54:17+02:00</updated_at> <license>TTXTC-R6FFF-9FF3V-DYDY4-T628B</license> <total type="integer">100</total> <arch>x86</arch> <id type="integer">11</id> <distro>2003</distro> <count type="integer">2</count> <tail></tail> <edition type="array"> <string>STD</string> </edition> </software_license> Where: created_at – the date when the record in DB was created updated_at - the date when the record in DB was updated license – the license for the software on which the template will be based total – the total number of machines allowed by the license arch – Windows OS architecture (x64 or x86) id – the ID of the record distro – Windows OS distribution (2003, 2008, Windows 7) count – the number of licenses used of a total allowed tail – parameter specifies the updated release of Windows OS distribution. If updated, than parameter is R2, otherwise – empty. edition – Windows OS edition or an array of editions if allowed by the license (STD – Standard, ENT –Enterprise, WEB – web and DC – Data center) 175 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 24.3 Edit a software license To edit a software license details: PUT PUT /software_licenses/:id.xml /software_licenses/:id.json XML Request example curl -i -X PUT -H 'Accept: application/xml' -H 'Content-type: application/xml' -u user:userpass -d '<software_license><arch>x64</arch><total>1</total><distro>2003</distro><count>1</coun t><tail>R2</tail><edition type="array"><edition>WEB</edition></edition><license>RRRRRIIIII-JJJJJ-KKKKK-WWWWW</license></software_license>' --url http://onapp.test/software_licenses/:id.xml You can edit the following parameters: arch - Windows OS architecture (x64 or x86) total - the total number of machines allowed by the license distro - Windows OS distribution (2003, 2008, Windows 7) count - the number of licenses used of a total allowed tail - parameter specifies the updated release of Windows OS distribution. If updated, than parameter is R2, otherwise – empty edition - Windows OS edition or an array of editions if allowed by the license (STD – Standard, ENT –Enterprise, WEB – web and DC – Data center) license - the license for the software on which the template will be based 24.4 Add a software license You can add a software license using the following request: POST POST /software_licenses.xml /software_licenses.json XML Request example curl -i -X POST -H 'Accept: application/xml' -H 'Content-type: application/xml' -u user:userpass -d '<software_license><arch>x64</arch><total>1</total><distro>2003</distro><count>1</coun t><tail>R2</tail><edition type="array"><edition>WEB</edition></edition><license>RRRRRIIIII-JJJJJ-KKKKK-EEEEE</license></software_license>' --url http://onapp.test/software_licenses.xml 176 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 To add a software license send the following parameters: arch * - Windows OS architecture (x64 or x86) total * - the total number of machines allowed by the license distro * - Windows OS distribution (2003, 2008, Windows 7) count *- the number of licenses used of a total allowed tail * - parameter specifies the updated release of Windows OS distribution. If updated, than parameter is R2, otherwise – empty edition * - Windows OS edition or an array of editions if allowed by the license (STD – Standard, ENT –Enterprise, WEB – web and DC – Data center) license * - the license for the software on which the template will be based 24.5 Delete a software license To delete a software license, use the following request: DELETE DELETE /software_licenses/:id.xml /software_licenses/:id.json XML Request example curl -i -X DELETE -u user:userpass --url http://onapp.test/software_licenses/:id.xml JSON Request example curl -i -X DELETE -u user:userpass --url http://onapp.test/software_licenses/:id.json 177 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 25. Resolvers Resolvers translate hostnames to IP addresses. At least two resolvers should be specified for each network in the system. View, edit and delete commands are available for existing resolvers. Resolvers are known as name servers in the API. 25.1 Get the list of resolvers Use the following method to get the list of all available resolvers in your cloud: GET GET /settings/nameservers.xml /settings/nameservers.json XML Output example <?xml version="1.0" encoding="UTF-8"?> <nameservers type="array"> <nameserver> <address>8.8.8.8</address> <created_at type="datetime">2011-02-14T15:55:44+02:00</created_at> <network_id type="integer">1</network_id> <updated_at type="datetime">2011-02-14T15:55:44+02:00</updated_at> <id type="integer">1</id> </nameserver> ... <nameserver></nameserver> ... </nameservers> Where: address - the resolver IP address created_at - the timestamp in database when this record was created network_id - the ID of the network to which this resolver belongs updated_at - the timestamp in database to which this resolver belongs id - the ID of this resolver 25.2 Get resolver details To get details for a particular resolver: GET GET /settings/nameservers/:id.xml /settings/nameservers/:id.json 178 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 XML Output example <?xml version="1.0" encoding="UTF-8"?> <nameserver> <address>8.8.8.8</address> <created_at type="datetime">2011-02-14T15:55:44+02:00</created_at> <network_id type="integer">1</network_id> <updated_at type="datetime">2011-02-14T15:55:44+02:00</updated_at> <id type="integer">1</id> </nameserver> The parameters are the same as for Get the list of resolvers section. 25.3 Edit a resolver Use the following method to edit a resolver: PUT PUT /settings/nameservers/:id.xml /settings/nameservers/:id.json XML Request example curl -i -X PUT -H 'Accept: application/xml' -H 'Content-type: application/xml' -u user:userpass -d '<nameserver><adress>128.123.123.123</address><network_id>3</network_id></nameserver>' --url http://onapp.test/settings/nameservers/:id.xml JSON Request example curl -i -X PUT -H 'Accept: application/json' -H 'Content-type: application/json' -u user:userpass -d '{"nameserver":{"address":"129.123.123.123","network_id":"6"}}' --url http://onapp.test/settings/nameservers/:id.json You can edit the address and network_id parameters. 25.4 Add a resolver To add a new resolver, use the following method: POST POST /settings/nameservers.xml /settings/nameservers.json XML Request Example 179 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 curl -i -X POST -H 'Accept: application/xml' -H 'Content-type: application/xml' -u user:userpass -d '<nameserver><address>124.123.123.123</address><network_id>1</network_id></nameserver> ' --url http://onapp.test/settings/nameservers.xml JSON Request example curl -i -X POST -H 'Accept: application/json' -H 'Content-type: application/json' -u user:userpass -d '{"nameserver":{"address":"126.123.123.123","network_id":"1"}}' --url http://onapp.test/settings/nameservers.json Set the following parameters: address * - the resolver IP address network_id * - the ID of the network to which this resolver should belong 25.5 Delete a resolver To delete a resolver: DELETE DELETE /settings/nameservers/:id.xml /settings/nameservers/:id.json XML Request example curl -i -X DELETE -u user:userpass --url http://onapp.test/settings/nameservers/:id.xml JSON Request example curl -i -X DELETE -u user:userpass --url http://onapp.test/settings/nameservers/:id.json Returns HTTP 200 response on successful deletion, or HTTP 404 when a resolver with the ID specified is not found, or the URL requested is incorrect. 180 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 26. Virtual Machines Virtual machines in OnApp are based on templates and deployed on hypervisors. VMs have their own root accounts, so that VM owners can fully control, configure and manage their machines. All CRUD operations are possible for the Virtual Machines class. 26.1 Get the list of VMs To get the list of VM, use the following request: GET GET /virtual_machines.xml /virtual_machines.json XML Output example <?xml version="1.0" encoding="UTF-8"?> <virtual_machines> <virtual_machine> <add_to_marketplace nil="true"></add_to_marketplace> <aflexi_id nil="true"></aflexi_id> <admin_note nil="true"></admin_note> <allow_resize_without_reboot type="boolean">true</allow_resize_without_reboot> <allowed_hot_migrate type="boolean">true</allowed_hot_migrate> <allowed_swap type="boolean">true</allowed_swap> <booted type="boolean">true</booted> <built type="boolean">true</built> <cpu_shares type="integer">1</cpu_shares> <cpus type="integer">1</cpus> <created_at type="datetime">2011-11-01T17:11:58+03:00</created_at> <enable_autoscale type="boolean">true</enable_autoscale> <enable_monitis type="boolean">true</enable_monitis> <hostname>autobackup</hostname> <hypervisor_id type="integer">2</hypervisor_id> <id type="integer">373</id> <identifier>iskngs9dve0hdg</identifier> <initial_root_password>791791</initial_root_password> <label>YR_autobackup</label> <local_remote_access_port type="integer">5903</local_remote_access_port> <locked type="boolean">false</locked> <max_memory type="integer">2048</max_memory> <memory type="integer">128</memory> <min_disk_size type="integer">5</min_disk_size> <note nil="true"></note> <operating_system>linux</operating_system> <operating_system_distro>rhel</operating_system_distro> <recovery_mode type="boolean">false</recovery_mode> <remote_access_password>os3ajolb1buj</remote_access_password> <state>new</state> <strict_virtual_machine_id nil="true"></strict_virtual_machine_id> <suspended type="boolean">false</suspended> <template_id type="integer">8</template_id> <template_label>CentOS 5.6 x86</template_label> <update_billing_stat type="boolean">false</update_billing_stat> <updated_at type="datetime">2011-11-04T13:22:25+03:00</updated_at> <user_id type="integer">5</user_id> <vip nil="true"></vip> 181 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 <xen_id type="integer">12</xen_id> <ip_addresses type="array"> <ip_address> <created_at type="datetime">2011-10-10T12:31:12+03:00</created_at> <disallowed_primary type="boolean">false</disallowed_primary> <id type="integer">2</id> <network_id type="integer">1</network_id> <updated_at type="datetime">2011-11-01T17:39:13+03:00</updated_at> <user_id nil="true"></user_id> <free type="boolean">false</free> <address>109.123.105.180</address> <gateway>109.123.105.177</gateway> <network_address>109.123.105.176</network_address> <broadcast>109.123.105.191</broadcast> <netmask>255.255.255.240</netmask> </ip_address> </ip_addresses> <monthly_bandwidth_used type="integer">2613</monthly_bandwidth_used> <total_disk_size type="integer">6</total_disk_size> </virtual_machine> ... <virtual_machine></virtual_machine> ... </virtual_machine> Where: add_to_marketplace — empty for VMs; used for edge servers only aflexi_id — empty for VMs; used for edge servers only admin_note — an optional note of the administrator allow_resize_without_reboot — true if resize without reboot is possible; otherwise false allowed_hot_migrate — true if the template, on which the VM is based, supports hot migration; otherwise false allowed_swap — true if swap disk is allowed (depends on the template the VM is based on); otherwise false booted — true if the VM is running; otherwise false built — true if the VM is built; otherwise false cpus — the number of allocated CPU cores cpu_shares — CPU priority in percent’s created_at — the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format enable_autoscale — true if autoscaling is allowed for this VM hostname — the name of your host 182 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 hypervisor_id — the ID of the hypervisor used by this VM id — the VM ID identifier — the VM identifier initial_root_password — the VM root password ip_addresses — an array of ip addresses with their details assigned to this VM label — the VM label local_remote_access_port — the port ID used for console access locked — true if the VM is locked; otherwise false max_memory — maximum amount of RAM which can be allocated to the VM by the hypervisor memory — the RAM size allocated to this VM min_disk_size — the minimum disk size required to build a VM from a specified template monthly_bandwidth_used — the bandwidth used this month note — an optional reminder for this VM made by a user account operating_system — operating system used by the VM operating_system_distro — the distribution of the OS from which this VM is built recovery_mode — true if recovery mode allowed. Otherwise false remote_access_password — the password for the remote access state – parameter reserved for future use strict_virtual_machine_id — the ID of a virtual machine that will never reside on the same HV with this VM suspended — true if VM is suspended, otherwise false template_id — the ID of the template the VM is based on template_label — the name of the template from which this VM is built total_disk_size — the total disk size in GB of all disks assigned to VM updated_at — the date when the VM was updated in the [YYYY][MM][DD]T[hh][mm][ss]Z format user_id — the ID of a user assigned to this VM 183 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 vip — true if the VM has VIP status (gives migration priority) xen_id — the VM ID set by the virtualization engine 26.2 Get VM details GET GET /virtual_machines/:id.xml /virtual_machines/:id.json Shows the same attributes of the VM described in Get the list of VMs request. 26.3 Create a VM POST POST /virtual_machines.xml /virtual_machines.json XML Request example curl -i -X POST -H 'Accept: application/xml' -H 'Content-type: application/xml' -u user:userpass -d '<?xml version="1.0" encoding="UTF8"?><virtual_machine><cpu_shares>10</cpu_shares><cpus>1</cpus><hostname>aptest2</hostn ame><hypervisor_id>1</hypervisor_id><initial_root_password>qwe123</initial_root_passwo rd><memory>256</memory><template_id>1</template_id><licensing_server_id>38</licensing_ server_id><licensing_type>kms</licensing_type><licensing_key>keyexample</licensing_key ><data_store_group_primary_id>2</data_store_group_primary_id><primary_disk_size>5</pri mary_disk_size><label>aptest2</label><data_store_group_swap_id>7</data_store_group_swa p_id><swap_disk_size>1</swap_disk_size><primary_network_id>1</primary_network_id><prim ary_network_group_id>1</primary_network_group_id><required_automatic_backup>1</require d_automatic_backup><rate_limit>none</rate_limit><required_ip_address_assignment>1</req uired_ip_address_assignment><selected_ip_address_id>1</selected_ip_address_id><require d_virtual_machine_build>0</required_virtual_machine_build><admin_note>Admin comment</admin_note><note>Note</note><hypervisor_group_id>2</hypervisor_group_id></vir tual_machine>' --url http://onapp.test/virtual_machines.xml JSON Request example curl -i -X POST -H 'Accept: application/json' -H 'Content-type: application/json' -u user:userpass -d '{"virtual_machine":{"cpu_shares":"10","cpus":"1","hostname":"aptest2","hypervisor_id" :"1","initial_root_password":"qwe123","memory":"256","template_id":"1","licensing_serv er_id":"38","licensing_type":"kms","licensing_key":"keyexample","primary_disk_size":"5 ", "data_store_group_primary_id":"2","label":"aptest5","swap_disk_size":"1", "data_store_group_swap_id":"7","primary_network_id":"1","primary_network_group_id":"1" ,"selected_ip_address_id":"1","required_automatic_backup":"1","rate_limit":"none","req uired_ip_address_assignment":"1","required_virtual_machine_build":"0","admin_note":"Ad min comment","note":"Note","allowed_hot_migrate":"true","hypervisor_group_id":"2"}}' -url http://onapp.test/virtual_machines.json The following parameters should be sent: 184 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 memory * Amount of RAM assigned to the VM. cpus * Number of CPUs assigned to the VM. cpu_shares Optional parameter. For KVM hypervisor the CPU priority value is always 100. For XEN, set a custom value. The default value for XEN is 1.. Hostname * Set the host name for this VM. label * User-friendly VM description. primary_disk_size * Set the disk space for this VM. swap_disk_size * Set swap space. There is no swap disk for Windows-based VMs. data_store_group_primary_id Set the ID of the data store zone to which this primary disk is allocated. data_store_group_swap_id Set the ID of the data store zone to which this swap disk is allocated. primary_network_id The ID of the primary network. Optional parameter that can be used only if it is assigned to the network zone. primary_network_group_id The ID of the primary network group. Optional parameter. required_automatic_backup Set 1 if you need automatic backups. rate_limit Set max port speed. Optional parameter: if none set, the system sets port speed to unlimited. required_ip_address_assignment * Set 1 if you wish the system to assign an IP automatically selected_ip_address_id Assign the IP address. required_virtual_machine_build * Set 1 to build VM automatically admin_note Enter a brief comment for the VM. Optional parameter. Note A brief comment a user can add to a VM. template_id * The ID of a template from which a VM should be built licensing_server_id The ID of a licensing server/template group – this parameter is for Windows XP/7 virtual machines only 185 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 licensing_type The type of a licence: MAK, KMS or user own license. This parameter is for Windows XP/7 virtual machines only licensing_key The key of a license. This parameter is for Windows XP/7 virtual machines only hypervisor_group_id The ID of the hypervisor zone in which the VM will be created. Optional: if no hypervisor zone is set, the VM will be built in any available hypervisor zone. hypervisor_id The ID of a hypervisor where the VM will be built. Optional: if no hypervisor ID is specified, the VM will be built on the hypervisor with the least available RAM (but sufficient RAM for the VM.) The root password for a VM. Optional, if none specified, the system will provide a random password. It can consist of 6-32 characters, letters [A-Za-z], digits [0-9], dash [ - ] and lower dash [ _ ]. You can use both lower- and uppercase letters. initial_root_password 26.4 Build a VM To build or re-build a VM, use the following methods: POST POST /virtual_machines/:virtual_machine_id/build.xml /virtual_machines/:virtual_machine_id/build.json XML Request example curl -i -X POST -H 'Accept: application/xml' -H 'Content-type: application/xml' -u user:userpass -d '<?xml version="1.0" encoding="UTF8"?><virtual_machine><template_id>1</template_id><required_startup>1</required_startup ></virtual_machine>' --url http://onapp.test/virtual_machines/:virtual_machine_id/build.xml JSON Request example curl -i -X POST -H 'Accept: application/json' -H 'Content-type: application/json' -u user:userpass -d '{"virtual_machine":{"template_id":"1","required_startup":"1"}}' -url http://onapp.test/virtual_machines/:virtual_machine_id/build.json Where: template_id * The ID of a template from which a VM should be built. 186 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 required_startup Set to 1 if you wish to start a VM after it is built. Otherwise set to 0. Instead of virtual machine ID (:virtual_machine_id) you may use virtual machine identifier (:virtual_machine_identifier). 26.5 Edit a VM PUT PUT /virtual_machines/:id.xml /virtual_machines/:id.json XML Request example curl -i -X PUT -H 'Accept: application/xml' -H 'Content-type: application/xml' -u user:userpass -d '<?xml version="1.0" encoding="UTF8"?><virtual_machine><label>Test_API_Edit</label><memory>512</memory><cpu_shares>40</c pu_shares><cpus>4</cpus><allow_migration>1</allow_migration><allow_cold_resize>1</allo w_cold_resize></virtual_machine>' --url http://onapp.test/virtual_machines/:id.xml JSON Request example curl -i -X PUT -H 'Accept: application/json' -H 'Content-type: application/json' -u user:userpass -d '{"virtual_machine":{"label":"Test_API_Edit","memory":"512","cpu_shares":"40","cpus":" 4","allow_migration":"1","allow_cold_resize":"1"}}' --url http://onapp.test/virtual_machines/:id.json You can edit the following parameters: label - the VM name memory - the amount of RAM allocated to this VM in Mb cpus - the number of CPUs of this VM cpu_shares - CPU priority percentage allow_migration - set 1 to migrate a VM to a HV with sufficient resources if a hypervisor has insufficient space to resize. Otherwise, set 0. allow_cold_resize – set 1 to switch to cold resize when hot resize failed If the VM is modified successfully, an HTTP 201 response is returned. If scheduling for changes fails, an HTTP 422 response is returned. 187 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 26.6 Change a VM owner Use the following request to reassign a VM to another user: POST POST /virtual_machines/:virtual_machine_id/change_owner.xml /virtual_machines/:virtual_machine_id/change_owner.json XML Request example curl -i -X POST -H 'Accept: application/xml' -H 'Content-type: application/xml' -u user:userpass -d '<user_id>4</user_id>' --url http://onapp.test/virtual_machines/:virtual_machine_id/change_owner.xml JSON Request example curl -i -X POST -H 'Accept: application/json' -H 'Content-type: application/json' -u user:userpass -d "{'user_id':'1'}" --url http://onapp.test/virtual_machines/:virtual_machine_id/change_owner.json Required parameter: user_id * – input ID of a new VM owner Instead of virtual machine ID (:virtual_machine_id) you may use virtual machine identifier (:virtual_machine_identifier). 26.7 Reset root password You can reset a VM password using the following method: POST POST /virtual_machines/:virtual_machine_id/reset_password.xml /virtual_machines/:virtual_machine_id/reset_password.json XML Request example curl -i -X POST -H 'Accept: application/xml' -H 'Content-type: application/xml' -u user:userpass --url http://onapp.test/virtual_machines/:virtual_machine_id/reset_password JSON Request example curl -i -X POST -H 'Accept: application/json' -H 'Content-type: application/json' -u user:userpass --url http://onapp.test/virtual_machines/:virtual_machine_id/reset_password 188 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 Where: virtual_machine_id * - id of the VM, for which you want to reset password. 26.8 Set SSH keys To assign SSH keys of all administrators and a VM owner to a VM, use the following request: POST POST /virtual_machines/:virtual_machine_id/set_ssh_keys.xml /virtual_machines/:virtual_machine_id/set_ssh_keys.json XML Request example curl -X POST -u user:userpass http://onapp.test/virtual_machines/:virtual_machine_id/set_ssh_keys.xml -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -X POST -u user:userpass http://onapp.test/virtual_machines/:virtual_machine_id/set_ssh_keys.json -H 'Accept: application/json' -H 'Content-type: application/json' 26.9 Migrate a VM You can migrate a VM to another hypervisor with the following method: POST POST /virtual_machines/:virtual_machine_id/migrate.xml /virtual_machines/:virtual_machine_id/migrate.json XML Request example curl -i -X POST -H 'Accept: application/xml' -H 'Content-type: application/xml' -u user:userpass -d "<virtual_machine><destination>1</destination><cold_migrate_on_rollback>1</cold_migrat e_on_rollback></virtual_machine>" --url http://onapp.test/virtual_machines/:virtual_machine_id/migrate.xml JSON Request example curl -i -X POST -H 'Accept: application/json' -H 'Content-type: application/json' -u user:userpass -d '{"virtual_machine":{"destination":"1","cold_migrate_on_rollback":"1"}}' --url http://onapp.test/virtual_machines/:virtual_machine_id/migrate.json Where: 189 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 Destination* The ID of a target hypervisor where you migrate a VM cold_migrate_on_rollback Set to 1 if you wish to switch to a cold migration if hot migration fails. Otherwise set to 0. 26.10 Set VIP status To set/remove VIP status for a VM, use the following request: POST POST /virtual_machines/:id/set_vip.xml /virtual_machines/:id/set_vip.json XML Request example curl -i -X POST -H 'Accept: application/xml' -H 'Content-type: application/xml' -u user:userpass --url http://onapp.test/virtual_machines/:virtual_machine_id/set_vip.xml JSON Request example curl -i -X POST -H 'Accept: application/json' -H 'Content-type: application/json' -u user:userpass --url http://onapp.test/virtual_machines/:virtual_machine_id/set_vip.json 26.11 DELETE DELETE Destroy a VM /virtual_machines/:id.xml /virtual_machines/:id.json XML Request example curl -i -X DELETE -u user:userpass --url http://onapp.test/virtual_machines/:id.xml JSON Request example curl -i -X DELETE -u user:userpass --url http://onapp.test/virtual_machines/:id.json 26.12 Resize a VM To resize a VM: POST POST /virtual_machines/:virtual_machine_id/resize.xml /virtual_machines/:virtual_machine_id/resize.json XML Request example 190 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 curl -i -X POST -H 'Accept: application/xml' -H 'Content-type: application/xml' -u user:userpass -d '<?xml version="1.0" encoding="UTF8"?><virtual_machine><memory>512</memory><cpus>2</cpus><cpu_shares>30</cpu_shares><all ow_cold_resize>1</allow_cold_resize></virtual_machine>' --url http://onapp.test/virtual_machines/:virtual_machine_id/resize.xml JSON Request example curl -i -X POST -H 'Accept: application/json' -H 'Content-type: application/json' -u user:userpass -d '{"virtual_machine":{"memory":"512","cpus":"2","cpu_shares":"30","allow_cold_resize":" 1"}}' --url http://onapp.test/virtual_machines/:virtual_machine_id/resize.json You can change the following parameters: memory - the amount of RAM allocated to your VM in MB cpus - the number of CPUs cpu_shares - cpu priority in % allow_cold_resize – set 1 to switch to cold resize when hot resize failed You can also resize a VM using the PUT method (see Edit a VM section). 26.13 Suspend a VM To suspend a VM: POST POST /virtual_machines/:id/suspend.xml /virtual_machines/:id/suspend.json XML Request example curl -i -X POST -u user:userpass --url http://onapp.test /virtual_machines/:virtual_machine_id/suspend.xml JSON Request example curl -i -X POST -u user:userpass --url http://onapp.test /virtual_machines/:virtual_machine_id/suspend.json Where: virtual_machine_id * - ID of a VM you want to suspend. 191 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 26.14 Unsuspend a VM To activate a VM again, use the same request as to suspend it: POST POST /virtual_machines/:id/suspend.xml /virtual_machines/:id/suspend.json For details refer to Suspend a VM section 26.15 Unlock a VM To unlock a VM: POST POST /virtual_machines/:virtual_machine_id/unlock.xml /virtual_machines/:virtual_machine_id /unlock.json XML Request example curl -i -X POST -u user:userpass --url http://onapp.test/virtual_machines/:virtual_machine_id/unlock.xml JSON Request example curl -i -X POST -u user:userpass --url http://onapp.test/virtual_machines/:virtual_machine_id/unlock.json 26.16 Start up a VM To start up a VM: POST POST /virtual_machines/:virtual_machine_id /startup.xml /virtual_machines/:virtual_machine_id /startup.json XML Request example curl -i -X POST -u user:userpass --url http://onapp.test/virtual_machines/:virtual_machine_id/startup.xml JSON Request example curl -i -X POST -u user:userpass --url http://onapp.test/virtual_machines/:virtual_machine_id/startup.json 192 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 26.17 Shut down a VM To shut down a VM: POST POST /virtual_machines/:virtual_machine_id/shutdown.xml /virtual_machines/:virtual_machine_id/shutdown.json XML Request example curl -i -X POST -u user:userpass --url http://onapp.test/virtual_machines/:virtual_machine_id/shutdown.xml JSON Request example curl -i -X POST -u user:userpass --url http://onapp.test/virtual_machines/:virtual_machine_id/shutdown.json 26.18 Stop a VM To stop a VM: POST POST /virtual_machines/:virtual_machine_id/stop.xml /virtual_machines/:virtual_machine_id/stop.json XML Request example curl -i -X POST -u user:userpass --url http://onapp.test/virtual_machines/:virtual_machine_id/stop.xml JSON Request example curl -i -X POST -u user:userpass --url http://onapp.test/virtual_machines/:virtual_machine_id/stop.json 26.19 Reboot a VM To reboot a VM: POST POST /virtual_machines/:virtual_machine_id/reboot.xml /virtual_machines/:virtual_machine_id/reboot.json XML Request example curl -i -X POST -u user:userpass --url http://onapp.test/virtual_machines/:virtual_machine_id/reboot.xml JSON Request example 193 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 curl -i -X POST -u user:userpass --url http://onapp.test/virtual_machines/:virtual_machine_id/reboot.json An HTTP 201 response is returned on a successful reboot. Unsuccessful reboot responses include HTTP 404 (resource not found – e.g. if the VM isn’t online) and HTTP 422 (request cannot be processed – eg if parameters were incorrect). 26.20 Reboot in recovery To reboot a VM in recovery mode with a temporary login (“root”) and password (“recovery”), use the following API calls: POST POST /virtual_machines/:virtual_machine_id/reboot.xml?mode=recovery /virtual_machines/:virtual_machine_id/reboot.json?mode=recovery XML Request example curl -i -X POST -u user:userpass --url http://onapp.test/virtual_machines/:virtual_machine_id/reboot.xml?mode=recovery JSON Request example curl -i -X POST -u user:userpass --url http://onapp.test/virtual_machines/:virtual_machine_id/reboot.json?mode=recovery 26.21 Segregate a VM To segregate a VM (that is, instruct it never to reside on the same hypervisor as another VM), use the following method: POST POST /virtual_machines/:virtual_machine_id/strict_vm.xml /virtual_machines/:virtual_machine_id/strict_vm.json XML Request example curl -i -X POST -H 'Accept: application/xml' -H 'Content-type: application/xml' -u user:userpass -d '<?xml version="1.0" encoding="UTF8"?><virtual_machine><strict_virtual_machine_id>bb6oa3eqdzpcgl</strict_virtual_machine _id></virtual_machine>' --url http://onapp.test/virtual_machines/:virtual_machine_id/strict_vm.xml JSON Request example curl -i -X POST -H 'Accept: application/json' -H 'Content-type: application/json' -u user:userpass -d '{"virtual_machine":{"strict_virtual_machine_id":"gv03xz1x31t53h"}}' --url http://onapp.test/virtual_machines/:virtual_machine_id/strict_vm.json 194 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 Where: strict_virtual_machine_id *- 26.22 the ID of virtual machine you wish to segregate from the given VM Open a VM console To open a VM console: 1. Run the following request: GET GET /virtual_machines/:virtual_machine_id/console.xml /virtual_machines/:virtual_machine_id/console. json 2. Find and copy the value for the remote_key parameter in the response output. 3. Open the following URL in the browser: http://onapp.test/console_remote/[remote_key_parameter_value] 26.23 Billing statistics for a VM You can view the billing statistics for a particular VM using the following request: GET GET /virtual_machines/:virtual_machine_id/vm_stats.xml /virtual_machines/:virtual_machine_id/vm_stats.json <?xml version="1.0" encoding="UTF-8"?> <vm_hourly_stats type="array"> <vm_hourly_stat> <vm_hourly_stat> <created_at type="datetime">2011-08-09T12:00:10Z</created_at> <updated_at type="datetime">2011-08-09T12:00:10Z</updated_at> <usage_cost type="float">0.0</usage_cost> <stat_time type="datetime">2011-08-09T12:00:00Z</stat_time> <id type="integer">8248</id> <vm_resources_cost type="float">4.0</vm_resources_cost> <vm_billing_stat_id type="integer">100175</vm_billing_stat_id> <user_id type="integer">1</user_id> <virtual_machine_id type="integer">44</virtual_machine_id> <currency_code>USD</currency_code> <total_cost type="float">4.0</total_cost> <billing_stats> <virtual_machines type="array"> <virtual_machine> <label>oleg_test_2129</label> <costs type="array"> <cost> <resource_name>cpus</resource_name> <value type="integer">1</value> <cost type="float">0.0</cost> </cost> ... <cost></cost> ... 195 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 </costs> <id type="integer">44</id> </virtual_machine> </virtual_machines> <network_interfaces type="array"> <network_interface> <label>eth0</label> <costs type="array"> <cost> <resource_name>ip_addresses</resource_name> <value type="integer">1</value> <cost type="float">0.0</cost> </cost> ... <cost></cost> ... </costs> <id type="integer">45</id> </network_interface> </network_interfaces> <disks type="array"> <disk> <label>#106</label> <costs type="array"> <cost> <resource_name>disk_size</resource_name> <value type="integer">5</value> <cost type="float">3.0</cost> </cost> </cost> ... <cost></cost> ... </costs> </billing_stats> </vm_hourly_stat> </vm_hourly_stats> Where: created_at – the timestamp in DB when this record was created updated_at – the date when these statistics were updated cost – the total amount of money owed by this particular VM for the resources spent at stat_time updated_at – the time stamp in DB when this record was updated stat_time – the particular hour for which these statistics were generated id – the ID of these statistics user_id - the ID of VM owner currency_code - currency in which this virtual machine is charged within the billing plan billing_stats - an array of billing details for the resources used by this VM virtual_machine - an array of virtual machine billing details: • • label - VM name costs - An array of VM resources with their total prices for the period specified in the stat-time parameter, where: 196 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 o o o o resource_name - the resource in question. This can be cpu_shares, cpus, memory, cpu_usage and template value - the amount of resources allocated to this VM. For the templates resource, this parameter means a template ID in database. cost - the total due for this resource id - Virtual machine ID network_interfaces - an array of network interfaces used by this VM with their billing statistics: • • • label - network interface name used in OnApp id - network interface ID costs - an array of network interface related resources with their total prices for the period specified in the stat-time parameter, where: o resource_name - the resource in question. This can be ip_addresses, rate, data_received and data_sent o value - the amount of resources used by this network interface (the number of IPs, the port speed in Mb per second, the Data sent and received in Gb ) o cost - the total due for the resource disks - an array of disks used by this VM with their billing details: • • • label - disk name used in UI id - disk ID used in database costs - an array of disk related resources with their total prices for the period specified in the stattime parameter, where: o resource_name - the resource in question. This can be disk_size, data_read, data_written, reads_completed and writes_completed o value - the amount of resources used (Gbs of disk size, Gbs of data read/writen, the number of reads/writes) o cost - the total due for the resource total_cost – the total amount of money owed for the VM specified by id parameter for a particular hour specified by stat_time parameter (total_cost = vm_resources_cost + usage_cost) vm_resources_cost – the amount of money due for the VM resources for the particular hour specified by stat_time parameter (memory, disks, templates) usage_cost – the total due for VM usage for this particular hour specified by stat_time parameter (data sent/received, bandwidth, CPU usage) 197 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 27. VM Autoscaling VM autoscaling allows you to automatically increase the RAM, CPU and disk size of a virtual machine. VM resources are scaled based on the rules you specify. For example, you can set up a rule that will add 1000MB of memory to a VM if RAM has been above 90% for the last 10 minutes - but add no more than 5000 MB in total in 24 hours. 27.1 Get the list of autoscaling rules for a VM To get the list of autoscaling rules for a particular VM: GET GET /virtual_machines/:virtual_machine_id/auto_scaling.xml /virtual_machines/:virtual_machine_id/auto_scaling.json XML Output example <?xml version="1.0" encoding="UTF-8"?> <auto_scaling_configurations type="array"> <auto_scaling_configuration> <up_to type="integer">9000</up_to> <for_minutes type="integer">5</for_minutes> <above type="integer">90</above> <created_at type="datetime">2011-07-19T18:56:57+07:00</created_at> <updated_at type="datetime">2011-07-19T18:56:57+07:00</updated_at> <resource>memory</resource> <id type="integer">1</id> <virtual_machine_id type="integer">1063</virtual_machine_id> <add_units type="integer">600</add_units> </auto_scaling_configuration> ... <auto_scaling_configuration></auto_scaling_configuration> ... </auto_scaling_configuration> Where: up_to - the amount of resource which cannot be exceeded within 24 hours period for_minutes - the time threshold before scaling will be triggered above - the amount of the resource usage (%). If this value is reached by the VM during the period specified by the for_minutes parameter, the system will add the amount of units set by the add_units parameters. created_at - the date when the record in DB was created updated_at - the date when the record in DB was updated resource - the resource for which the rule is created (memory/cpu/disk ) 198 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 id - the ID of the rule virtual_machine_id - the ID of the VM to which this rule applies add_units - the amount of resource units which the system should add if the rule is met 27.2 Create autoscaling rule for VM To create autoscaling rule for a virtual machine, use this request: POST POST /virtual_machines/:virtual_machine_id/auto_scaling.xml /virtual_machines/:virtual_machine_id/auto_scaling.json XML Request example curl -X POST -u user:userpass http://onapp.test/virtual_machines/:virual_machine_id/auto_scaling.xml -H 'Accept: application/xml' -H 'Content-type: application/xml' -d '<auto_scaling_configuration><up_to>22</up_to><for_minutes>10</for_minutes><above>5</a bove><resource>cpu</resource><add_units>22</add_units><enabled>1</enabled><allow_cold_ resize>1</allow_cold_resize></auto_scaling_configuration>' JSON Request example curl -X POST -u user:userpass http://onapp.test/virtual_machines/:virual_machine_id/auto_scaling.json -H 'Accept: application/json' -H 'Content-type: application/json' -d '"auto_scaling_configuration":{"above":5,"for_minutes":10,"up_to":11,"resource":"cpu", "add_units":"22","enabled":”1”,"allow_cold_resize":"1"}' Where: up_to * - the amount of resource which cannot be exceeded within 24 hours period for_minutes * - the time threshold before scaling will be triggered above * - the amount of the resource usage (%). If this value is reached by the VM for the period specified by the for_minutes parameter, the system will add the amount of units set by the add_units parameters. resource * - the resource for which the rule is created (memory/cpu/disk ) add_units * - the amount of resource units which the system should add if the rule is met enabled * - set 1 to enable, or 0 to disable allow_cold_resize – set 1 to switch to cold resize when hot resize failed 199 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 27.3 Edit autoscaling rule for a VM At present you cannot edit separate elements of autoscaling rule. To change a rule for a VM you have to create a new rule, using the same request as in Create autoscaling rule section. 27.4 Delete autoscaling rules To delete autoscaling rules, use this request: DELETE DELETE /virtual_machines/:virtual_machine_id/auto_scaling.xml /virtual_machines/:virtual_machine_id/auto_scaling.json XML Request example curl -i -X DELETE -u user:userpass --url http://onapp.test/virtual_machines/:virtual_machine_id/auto_scaling.xml JSON Request example curl -i -X DELETE -u user:userpass --url http://onapp.test/virtual_machines/:virtual_machine_id/auto_scaling.json This will delete all autoscaling rules, set for this VM. 200 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 28. Load Balancers Load balancers distribute requests evenly between clustered virtual machines (nodes), so that no virtual machine is overloaded. Together with nodes, load balancers form Load Balancing Clusters. There are two options of load balancing clusters: Cluster type In this case you specify which VMs (nodes) will participate in a load balancing cluster. You can add and remove clustered VMs as required. Autoscaling type In this case you indicate minimum and maximum number of nodes for a cluster, as well as autoscaling parameters for automatic adding or removing nodes from the cluster. The system creates required number of identical nodes, with the same resource allocation and the same template for each node. Load balancing clusters of both typesuse the same requests. Only some parameters differ. 28.1 Get the list of load balancing clusters To get the list of load balancing clusters, use the following request: GET GET /load_balancing_clusters.xml /load_balancing_clusters.json Load balancing cluster array includes details on load balancers and attached nodes. XML Output example <?xml version="1.0" encoding="UTF-8"?> <load_balancing_clusters type="array"> <load_balancing_cluster> <name>asdas</name> <created_at type="datetime">2011-07-20T17:54:31Z</created_at> <load_balancer_password>ce45tqsb3jub</load_balancer_password> <load_balancer_id type="integer">60</load_balancer_id> <config> <max_node_amount></max_node_amount> <min_node_amount></min_node_amount> </config> <nodes type="array"> <load_balancing_cluster_node> <cluster_id type="integer">5</cluster_id> <ip_address_id type="integer">1</ip_address_id> <created_at type="datetime">2011-07-20T17:54:31Z</created_at> <updated_at type="datetime">2011-07-20T17:54:31Z</updated_at> <id type="integer">10</id> <virtual_machine_id type="integer">41</virtual_machine_id> </load_balancing_cluster_node> </nodes> 201 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 <updated_at type="datetime">2011-07-20T17:54:31Z</updated_at> <ports type="array"> <port>80</port> </ports> <id type="integer">5</id> <user_id type="integer">1</user_id> <load_balancer> <label>asdas</label> <cpus type="integer">1</cpus> <operating_system_distro>lbva</operating_system_distro> <created_at type="datetime">2012-02-28T10:58:56Z</created_at> <template_id type="integer">6</template_id> <operating_system>linux</operating_system> <enable_autoscale nil="true"/> <cpu_shares type="integer">10</cpu_shares> <updated_at type="datetime">2012-02-28T12:30:58Z</updated_at> <memory type="integer">512</memory> <local_remote_access_port type="integer">5901</local_remote_access_port> <allowed_swap type="boolean">true</allowed_swap> <recovery_mode type="boolean">false</recovery_mo de> <allow_resize_without_reboot type="boolean">true</allow_resize_without_reboot> <ip_addresses type="array"> <ip_address> <address>109.123.105.180</address> <disallowed_primary type="boolean">false</disallowed_primary> <created_at type="datetime">2012-01-20T16:02:01Z</created_at> <broadcast>109.123.105.191</broadcast> <free type="boolean">false</free> <updated_at type="datetime">2012-01-20T16:02:01Z</updated_at> <network_id type="integer">1</network_id> <netmask>255.255.255.240</netmask> <network_address>109.123.105.176</network_address> <id type="integer">65</id> <gateway>109.123.105.177</gateway> </ip_address> </ip_addresses> <xen_id type="integer">42</xen_id> <update_billing_stat type="boolean">false</update_billing_stat> <id type="integer">307</id> <hypervisor_id type="integer">1</hypervisor_id> <enable_monitis type="boolean">false</enable_monitis> <user_id type="integer">6</user_id> <allowed_hot_migrate type="boolean">true</allowed_hot_migrate> <admin_note nil="true"/> <vip nil="true"/> <suspended type="boolean">false</suspended> <strict_virtual_machine_id nil="true"/> <note nil="true"/> <total_disk_size type="integer">6</total_disk_size> <template_label>Load Balancer Virtual Appliance</template_label> <hostname>lb.oleg.test.com</hostname> <booted type="boolean">true</booted> <remote_access_password>i1pyx4gnsmkl</remote_access_password> <min_disk_size type="integer">5</min_disk_size> <initial_root_password>z1daxmf66z6q</initial_root_password> <identifier>ju3149gpa8dyio</identifier> <add_to_marketplace nil="true"/> <monthly_bandwidth_used type="integer">4318</monthly_bandwidth_used> <state>new</state> <locked type="boolean">false</locked> <built type="boolean">true</built> </load_balancer> <node_attributes nil="true"></node_attributes> 202 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 <identifier>593089089b16c9c998a43fa2a732028f615ae703</identifier> <cluster_type>cluster</cluster_type> <image_template_id nil="true"></image_template_id> </load_balancing_cluster> </load_balancing_clusters> Description: load_balancing_clusters – an array of all load balancing clusters (may be both cluster and autoscaling types) name - load balancing cluster name created_at - the date when the cluster was created load_balancer_password – root password, which is generated automatically load_balancer_id - the ID of a load balancer added to this cluster config – configuration array, where: • • max_node_amount – maximum number of nodes (for autoscaling types; remains empty for cluster types) min_node_amount – minimum number of nodes (for autoscaling types; remains empty for cluster types) nodes - an array of load balancing cluster nodes with VM details: • • • • cluster_id - the ID of load balancing cluster to which this node belongs ip_address_id – the ID of VM IP address added to a cluster id – node ID virtual_machine_id – the ID of VM added to a cluster updated_at – the date when the cluster was updated ports – the array of ports on which this cluster runs port – the cluster port id – ID of the cluster user_id – ID of the load balancing cluster owner load_balancer • • label – the load balancer name cpus – the number of CPU cores allocated to this load balancer 203 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • operating_system_distro – the distribution of the OS created_at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format template_id – ID of the LB template operating_system - the OS on which the load balancing cluster is based enable_autoscale – true if autoscaling is enabled, otherwise false cpu_shares – the CPU priority of this load balancing cluster updated_at - the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format memory – the amount of RAM allocated to this load balancing cluster local_remote_access_port – the port ID used for used for console access allowed_swap – true if swap disks are allowed, otherwise false recovery_mode – true if recovery mode is allowed, otherwise false allow_resize_without_reboot – true if you can resize a VM’s CPU and RAM without rebooting it ip_addresses - an array of IP addresses assigned to this load balancer and their details: disallowed_primary – true if not allowed to be used as primary (for Load Balancer build), otherwise false broadcast – broadcast address free – true if free, otherwise false network_id – the ID of a network attached to this load balancer netmask – netmask for the IP address network_address – the address of the network gateway – gateway address xen_id – the VM ID set by the virtualization engine id – the load balancing cluster ID hypervisor_id – the ID of the hypervisor used by this load balancing cluster enable_monitis – true if monitis is enabled, otherwise false user_id –the ID of the user who owns this load balancing cluster allowed_hot_migrate – true if hot migration is allowed admin_note – an optional text note vip – true if the VIP status is set, otherwise false suspend – true if suspended, otherwise false strict_virtual_machine_id – the ID of a VM that will never reside in this load balancing cluster note – an optional text, added as a note total_disk_size – the load balancer disk size template_label – the name of the template on which this load balancing cluster is based hostname – the host name for this load balancer booted - true if the machine is booted, otherwise false remote_access_password – the password for remote access min_disk_size – the minimum disk size in GB required for a specified template 204 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 • • • • • initial_root_password – the VM root password identifier – identifier of the load balancer in the database monthly_bandwidth_used – the bandwidth used this month locked – true if locked, otherwise false built – true if the load balancing cluster is built, otherwise false node_attributes – an array of node attributes for autoscaling type, including cpu_shares, memory (RAM), rate_limit (port speed) and cpus (remains empty for cluster type) identifier – the LB identifier in the DB cluster_type – the type of the cluster (either cluster or autoscaleout) image_template_id – the ID of a template on which the nodes of this load balancer are based (empty for cluster type) 28.2 Get load balancing cluster details To get details for a particular load balancing cluster, use the following request: GET GET /load_balancing_clusters/:id.xml /load_balancing_clusters/:id.json XML Output example <?xml version="1.0" encoding="UTF-8"?> <load_balancing_cluster> <name>qqet</name> <created_at type="datetime">2011-04-27T19:22:02+03:00</created_at> <load_balancer> <label>test.test</label> <cpus type="integer">1</cpus> <operating_system_distro>lbva</operating_system_distro> <created_at type="datetime">2012-02-28T10:58:56Z</created_at> <template_id type="integer">6</template_id> <operating_system>linux</operating_system> <enable_autoscale nil="true"/> <cpu_shares type="integer">10</cpu_shares> <updated_at type="datetime">2012-02-28T12:30:58Z</updated_at> <memory type="integer">512</memory> <local_remote_access_port type="integer">5901</local_remote_access_port> <allowed_swap type="boolean">true</allowed_swap> <recovery_mode type="boolean">false</recovery_mo de> <allow_resize_without_reboot type="boolean">true</allow_resize_without_reboot> <ip_addresses type="array"> <ip_address> <address>109.123.105.180</address> <disallowed_primary type="boolean">false</disallowed_primary> <created_at type="datetime">2012-01-20T16:02:01Z</created_at> <broadcast>109.123.105.191</broadcast> <free type="boolean">false</free> <updated_at type="datetime">2012-01-20T16:02:01Z</updated_at> <network_id type="integer">1</network_id> 205 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 <netmask>255.255.255.240</netmask> <network_address>109.123.105.176</network_address> <id type="integer">65</id> <gateway>109.123.105.177</gateway> </ip_address> </ip_addresses> <xen_id type="integer">42</xen_id> <update_billing_stat type="boolean">false</update_billing_stat> <id type="integer">307</id> <hypervisor_id type="integer">1</hypervisor_id> <enable_monitis type="boolean">false</enable_monitis> <user_id type="integer">6</user_id> <allowed_hot_migrate type="boolean">true</allowed_hot_migrate> <admin_note nil="true"/> <vip nil="true"/> <suspended type="boolean">false</suspended> <strict_virtual_machine_id nil="true"/> <note nil="true"/> <total_disk_size type="integer">6</total_disk_size> <template_label>Load Balancer Virtual Appliance</template_label> <hostname>lb.oleg.test.com</hostname> <booted type="boolean">true</booted> <remote_access_password>i1pyx4gnsmkl</remote_access_password> <min_disk_size type="integer">5</min_disk_size> <initial_root_password>z1daxmf66z6q</initial_root_password> <identifier>ju3149gpa8dyio</identifier> <add_to_marketplace nil="true"/> <monthly_bandwidth_used type="integer">4318</monthly_bandwidth_used> <state>new</state> <locked type="boolean">false</locked> <built type="boolean">true</built> </load_balancer> <load_balancer_id type="integer">55</load_balancer_id> <config> <ports type="array"> <port>80</port> </ports> </config> <nodes type="array"/> <updated_at type="datetime">2011-04-27T19:22:02+03:00</updated_at> <id type="integer">10</id> <user_id type="integer">1</user_id> <node_attributes nil="true"></node_attributes> <image_template_id nil="true"></image_template_id> </load_balancing_cluster> The description of the attributes is the same as for the Get the list of load balancing clusters request. 28.3 Edit load balancing cluster details To edit a particular load balancing cluster parameters, use the following request: PUT PUT /load_balancing_clusters/:id.xml /load_balancing_clusters/:id.json JSON Request example 206 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 curl -X PUT -d '{"load_balancing_cluster":{"port":"80","load_balancer_attributes":{"label":"label1", "rate_limit":"0"}}' -u user:userpass http://onapp.test/load_balancing_clusters/:load_balancing_cluster_id.json -H 'Accept: application/json' -H 'Content-type: application/json' Where: load_balancing_cluster * – an array with load balancing cluster details, where: port *- edit port on which the load balancing cluster runs load_balancer_attributes * – an array of LB instance, where: label * – the LB title rate_limit * – the port speed for the LB Using this request you can edit the following load balancing cluster parameters: port, label and rate limit and add node to the load balancing cluster. To see how to add and remove nodes from the cluster type, see the Remove nodes from cluster type and Add nodes to cluster type sections. 28.4 Add a load balancing cluster To add a cluster type or an autoscaling type use the following request: POST POST /load_balancing_clusters.xml /load_balancing_clusters.json XML Request example to add a cluster type curl -i -X POST -H 'Content-Type: application/xml' -H 'Accept: application/xml' -d '<load_balancing_cluster><ports type="array"><port>80</port><port>25001</port></ports><nodes_attributes type="array"><nodes_attribute><ip_address_id>59</ip_address_id><virtual_machine_id>536 </virtual_machine_id></nodes_attribute><nodes_attribute><ip_address_id>60</ip_address_ id><virtual_machine_id>537</virtual_machine_id></nodes_attribute></nodes_attributes><c luster_type>cluster</cluster_type><load_balancer_attributes><label>YR_xml</label><rate _limit>0</rate _limit><hostname>yr.cluster.xml</hostname><primary_network_group_id>3</primary_network _group_id><hypervisor_group_id>1</hypervisor_group_id><hypervisor_id>1</hypervisor_id> </load_balancer_attributes></load_balancing_cluster>' -u user:userpass --url http://onapp.test/load_balancing_clusters.xml JSON Request example to add a cluster type 207 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 curl -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d "{"load_balancing_cluster":{"ports":[80,25001],"load_balancer_attributes":{"label":"YR _json","rate_limit":"0","hostname":"YR.json","primary_network_group_id":"3", "hypervisor_group_id":"1","hypervisor_id":"1"},"cluster_type":"cluster","nodes_attribu tes":[{"ip_address_id":"59","virtual_machine_id":"536"},{"ip_address_id":"60","virtual _machine_id":"537"}]}}" -u user:userpass http://onapp.test/load_balancing_clusters.json Where: load_balancing_cluster * – an array with load balancing cluster details, where: • • • • • ports*- an array of ports on which an LB cluster will run, where: port *- a particular port on which a load balancing cluster will run load_balancer_attributes * – an array of LB instance, where: o label * – the LB title o rate_limit * – the port speed for the LB o hostname * – the hostname of the load balancer o primary_network_group_id – the ID of a network zone assigned to the load balancer cluster o hypervisor_group_id – the ID of a hypervisor zone o hypervisor_id – the ID of a hypervisor cluster_type * – the type of the load balancing cluster. Input cluster for the cluster type nodes_attributes – an array of cluster nodes, where: o virtual_machine_id – the ID of virtual machine, which is added as a node o ip_address_id – the ID of virtual machine IP. XML Request example to add an autoscaling type curl -X POST -d '<load_balancing_cluster><config><max_node_amount>4</max_node_amount><min_node_amount> 2</min_node_amount></config><auto_scaling_in_cpu_attributes><for_minutes>20</for_minut es><units>1</units><enabled>true</enabled><value>60</value></auto_scaling_in_cpu_attri butes><ports type="array"><port>80</port><port>25000</port></ports><auto_scaling_in_memory_attribut es><for_minutes>20</for_minutes><units>1</units><enabled>true</enabled><value>200</val ue></auto_scaling_in_memory_attributes><auto_scaling_out_memory_attributes><for_minute s>5</for_minutes><units>1</units><enabled>true</enabled><value>100</value></auto_scali ng_out_memory_attributes><load_balancer_attributes><label>az_AS</label><hostname>aa</h ostname><rate_limit>0</rate_limit><primary_network_group_id>3</primary_network_group_i d><hypervisor_group_id>1</hypervisor_group_id><hypervisor_id>1</hypervisor_id></load_b alancer_attributes><cluster_type>autoscaleout</cluster_type><node_attributes><cpus>1</ cpus><cpu_shares>1</cpu_shares><memory>128</memory><rate_limit>0</rate_limit></node_at tributes><auto_scaling_out_cpu_attributes><for_minutes>5</for_minutes><units>1</units> <enabled>true</enabled><value>80</value></auto_scaling_out_cpu_attributes><image_templ ate_id>62</image_template_id></load_balancing_cluster>' -u user:userpass http://onapp.test/load_balancing_clusters.xml -H 'Accept: application/xml' -H 'Content-type: application/xml' 208 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 JSON Request example to add an autoscaling type curl -X POST -d '{"load_balancing_cluster":{"config":{"max_node_amount":"4","min_node_amount":"2"},"au to_scaling_in_cpu_attributes":{"for_minutes":"20","units":"1","enabled":"true","value" :"60"},"ports":[80,25000],"auto_scaling_in_memory_attributes":{"for_minutes":"20","uni ts":"1","enabled":"true","value":"200"},"auto_scaling_out_memory_attributes":{"for_min utes":"5","units":"1","enabled":"true","value":"100"},"load_balancer_attributes":{"lab el":"az_AS","hostname":"aa","rate_limit":"0","primary_network_group_id":"3","hyperviso r_group_id":"1","hypervisor_id":"1"},"cluster_type":"autoscaleout","node_attributes":{ "cpus":"1","cpu_shares":"1","memory":"128","rate_limit":"0"},"auto_scaling_out_cpu_att ributes":{"for_minutes":"5","units":"1","enabled":"true","value":"80"},"image_template _id":"62"},"available_vms":""}' -u user:userpass http://onapp.test/load_balancing_clusters.json -H 'Accept: application/json' -H 'Content-type: application/json' Where: Autoscaling cluster parameters: load_balancing_cluster * – an array with load balancing cluster details, where: • • • • • • config * – a configuration array, where: o max_node_amount * - the maximum number of nodes in this cluster o min_node_amount * – the minimum number of nodes in this cluster ports * – the array of ports on which a load balancing cluster will run load_balancer_attributes * – an array of LB instance, where: o label * – the LB title o rate_limit * – the port speed for the LB o hostname * – the hostname of the load balancer o primary_network_group_id – the ID of a network zone assigned to the load balancer cluster o hypervisor_group_id – the ID of a hypervisor zone o hypervisor_id – the ID of a hypervisor cluster_type * – type of load balancing cluster. Input autoscaleout for the autoscaling type nodes_attributes * – an array of cluster nodes, where: o cpus * – number of CPUs for each node o cpu_shares * – the CPU priority of each node o memory * – the amount of RAM for each node o rate_limit * – the port speed for each node auto_scaling_in_memory_attributes – an array of RAM scale in attributes, where: o for_minutes - how long the RAM should be monitored o units - how many nodes are removed from the cluster, if the rule is met o enabled - set 1/true if the rule is enabled. Otherwise set 0/false 209 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 o • • • value - the amount of RAM (MB). If this value is reached by the cluster during the period specified by the for_minutes parameter, the system will remove the amount of units set by the units parameters. auto_scaling_in_cpu_attributes – an array of CPU scale in attributes, similar to RAM scale in attributes auto_scaling_out_memory_attributes - an array of RAM scale out attributes, where: o for_minutes - how long the RAM should be monitored o units - how many nodes are added to the cluster if the rule is met o enabled - set 1/true to enable the rule. Otherwise set false/0. o value - the amount of RAM (MB). If this value is reached by the cluster during the period specified by the for_minutes parameter, the system will add the amount of units set by the units parameters auto_scaling_out_cpu_attributes – an array of CPU scale out attributes, similar to RAM scale out attributes 28.5 Add nodes to cluster type To add new VMs (nodes) to a cluster type, use the following request: PUT PUT /load_balancing_clusters/:id.xml /load_balancing_clusters/:id.json JSON Request example curl -i -X PUT d'{"load_balancing_cluster":{"nodes_attributes":{"[:VM_id]":{"ip_address_id":"2","virt ual_machine_id":"278"},"[:VM_id]":{"ip_address_id":"7","virtual_machine_id":"277"}}}}' -u user:userpass http://onapp.test/load_balancing_clusters/:id.json -H 'Accept: application/json' -H 'Content-type: application/json',"primary_network_group_id":"3","hypervisor_group_id":"1","hypervisor _id":"1 You add new nodes by editing nodes_attributes array, where you add new nodes to already existing ones: load_balancing_cluster – an array, with load balancing cluster details: o • primary_network_group_id – the ID of a network zone assigned to the load balancer cluster o hypervisor_group_id – the ID of a hypervisor zone o hypervisor_id – the ID of a hypervisor nodes_attributes – an array where you may add new nodes o [:VM_id] –input ID of the VM you add to the cluster. Node parameters: ip_address_id – the ID of virtual machine IP 210 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 • id – input id of the existing node or omit it for a new node virtual_machine_id – input the ID of the VM id – input the cluster ID 28.6 Remove nodes from cluster type To remove nodes from cluster type, use the following request: PUT PUT /load_balancing_clusters/:id.xml /load_balancing_clusters/:id.json JSON Request example curl -X PUT d'{"load_balancing_cluster":{"nodes_attributes":{"[:VM_id]":{"_destroy":"1", "virtual_machine_id":"420"}}}}' -u user:userpass http://onapp.test/load_balancing_clusters/:id.json -H 'Accept: application/json' -H 'Content-type: application/json',"primary_network_group_id":"3","hypervisor_group_id":"1","hypervisor _id":"1 Where: load_balancing_cluster – an array, with load balancing cluster details: • • • • • primary_network_group_id – the ID of a network zone assigned to the load balancer cluster hypervisor_group_id – the ID of a hypervisor zone hypervisor_id – the ID of a hypervisor nodes_attributes – an array where you may remove nodes o [:VM_id] – set “0” (zero) for the node you want to delete. Node parameters: ip_address_id – the ID of virtual machine IP destroy – set 1/true to remove this node from the cluster virtual_machine_id – input the ID of the VM id – input the cluster ID 28.7 Configure autoscaling type You may change minimum/maximum number of nodes of autoscaling type, as well as change the autoscaling attributes for RAM and CPU. To configure autoscaling type, use the following request: PUT PUT /load_balancing_clusters/:id.xml /load_balancing_clusters/:id.json 211 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 XML Request example curl -X PUT -d '<load_balancing_cluster><config><max_node_amount>4</max_node_amount><min_node_amount> 2</min_node_amount></config><auto_scaling_in_cpu_attributes><for_minutes>20</for_minut es><units>1</units><enabled>true</enabled><value>60</value></auto_scaling_in_cpu_attri butes><ports type="array"><port>80</port><port>25000</port></ports><auto_scaling_in_memory_attribut es><for_minutes>20</for_minutes><units>1</units><enabled>true</enabled><value>200</val ue></auto_scaling_in_memory_attributes><auto_scaling_out_memory_attributes><for_minute s>5</for_minutes><units>1</units><enabled>true</enabled><value>100</value></auto_scali ng_out_memory_attributes><load_balancer_attributes><label>az_AS</label><hostname>aa</h ostname><rate_limit>0</rate_limit><primary_network_group_id>3</primary_network_group_i d><hypervisor_group_id>1</hypervisor_group_id><hypervisor_id>1</hypervisor_id></load_b alancer_attributes><node_attributes><cpus>1</cpus><cpu_shares>1</cpu_shares><memory>12 8</memory><rate_limit>0</rate_limit></node_attributes><auto_scaling_out_cpu_attributes ><for_minutes>5</for_minutes><units>1</units><enabled>true</enabled><value>80</value>< /auto_scaling_out_cpu_attributes><image_template_id>62</image_template_id></load_balan cing_cluster>' -u user:userpass http://onapp.test/load_balancing_clusters.xml -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -X PUT d'{"load_balancing_cluster":{"config":{"max_node_amount":"4","min_node_amount":"1"},"a uto_scaling_in_cpu_attributes":{"for_minutes":"20","units":"1","enabled":"true","value ":"60"},"ports":["80"],"auto_scaling_in_memory_attributes":{"for_minutes":"20","units" :"1","enabled":"true","value":"200"},"auto_scaling_out_memory_attributes":{"for_minute s":"5","units":"1","enabled":"true","value":"100"},"load_balancer_attributes":{"label" :"az_AS","hostname":"aa","rate_limit":"0","primary_network_group_id":"3","hypervisor_g roup_id":"1","hypervisor_id":"1"},"cluster_type":"autoscaleout","node_attributes":{"cp us":"1","cpu_shares":"1","memory":"128","rate_limit":"0"},"auto_scaling_out_cpu_attrib utes":{"for_minutes":"5","units":"1","enabled":"true","value":"80"},"image_template_id ":"4"},"available_vms":""}' -u user:userpass http://onapp.test/load_balancing_clusters/45.json -H 'Accept: application/json' -H 'Content-type: application/json' Where you may change: Number of nodes • • max_node_amount – maximum number of nodes for the cluster min_node_amount – minimum number of nodes for the cluster Autoscale in/out attributes for RAM and CPU • • • • for_minutes - how long the resource should be monitored units - how many nodes are removed or added to the cluster, if the rule is met enabled - set 1/true if the rule is enabled. Otherwise set 0/false value - the amount of resource. If this value is reached by the cluster during the period specified by the for_minutes parameter, the system will remove the amount of units set by the units parameter. 212 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 28.8 Delete a load balancing cluster To delete a load balancing cluster, use the following request: DELETE DELETE /load_balancing_clusters/:id .xml /load_balancing_clusters/:id .json You can also delete it using this request: DELETE DELETE /load_balancers/:id.xml /load_balancers/:id.json XML Request example curl -i -X DELETE -u user:userpass --url http://onapp.test/load_balancers/:id.xml JSON Request example curl -i -X DELETE -u user:userpass --url http://onapp.test/load_balancers/:id.json If you delete a cluster type – the nodes (VMs) will remain in the system. If you delete an autoscaling type - all its nodes will be deleted as well. 28.9 Configure load balancing cluster ports To set the list of ports on which a load balancing cluster runs, use the following requests: PUT /load_balancing_clusters/:id.xml PUT /load_balancing_clusters/:id.json XML Request example curl -i -X PUT -H 'Content-Type: application/xml' -H 'Accept: application/xml' -d '<load_balancing_cluster><ports type="array"><port>8080</port><port>25025</port> </ports></load_balancing_cluster>' -u user:userpass --url http://onapp.test/load_balancing_clusters/:id.xml JSON Request example curl -X PUT -d '{"load_balancing_cluster":{"ports":[8080,25025]}}' -u onapp_user:userpass http://onapp.test/load_balancing_clusters/:id.json -H 'Accept: application/json' -H 'Content-type: application/json' Where: Ports* – the array of ports on which a load balancing cluster will run 213 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 Port* – a particular port 28.10 Get the list of load balancers To get the list of available load balancers, use the following request: GET GET /load_balancers.xml /load_balancers.json XML Output example <?xml version="1.0" encoding="UTF-8"?> <load_balancers type="array"> <load_balancer> <label>test.test</label> <cpus type="integer">1</cpus> <operating_system_distro>lbva</operating_system_distro> <created_at type="datetime">2012-02-28T10:58:56Z</created_at> <template_id type="integer">6</template_id> <operating_system>linux</operating_system> <enable_autoscale nil="true"/> <cpu_shares type="integer">10</cpu_shares> <updated_at type="datetime">2012-02-28T12:30:58Z</updated_at> <memory type="integer">512</memory> <local_remote_access_port type="integer">5901</local_remote_access_port> <allowed_swap type="boolean">true</allowed_swap> <recovery_mode type="boolean">false</recovery_mo de> <allow_resize_without_reboot type="boolean">true</allow_resize_without_reboot> <ip_addresses type="array"> <ip_address> <address>109.123.105.180</address> <disallowed_primary type="boolean">false</disallowed_primary> <created_at type="datetime">2012-01-20T16:02:01Z</created_at> <broadcast>109.123.105.191</broadcast> <free type="boolean">false</free> <updated_at type="datetime">2012-01-20T16:02:01Z</updated_at> <network_id type="integer">1</network_id> <netmask>255.255.255.240</netmask> <network_address>109.123.105.176</network_address> <id type="integer">65</id> <gateway>109.123.105.177</gateway> </ip_address> </ip_addresses> <xen_id type="integer">42</xen_id> <update_billing_stat type="boolean">false</update_billing_stat> <id type="integer">307</id> <hypervisor_id type="integer">1</hypervisor_id> <enable_monitis type="boolean">false</enable_monitis> <user_id type="integer">6</user_id> <allowed_hot_migrate type="boolean">true</allowed_hot_migrate> <admin_note nil="true"/> <vip nil="true"/> <suspended type="boolean">false</suspended> <strict_virtual_machine_id nil="true"/> <note nil="true"/> <total_disk_size type="integer">6</total_disk_size> <template_label>Load Balancer Virtual Appliance</template_label> <hostname>lb.oleg.test.com</hostname> 214 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 <booted type="boolean">true</booted> <remote_access_password>i1pyx4gnsmkl</remote_access_password> <min_disk_size type="integer">5</min_disk_size> <initial_root_password>z1daxmf66z6q</initial_root_password> <identifier>ju3149gpa8dyio</identifier> <add_to_marketplace nil="true"/> <monthly_bandwidth_used type="integer">4318</monthly_bandwidth_used> <state>new</state> <locked type="boolean">false</locked> <built type="boolean">true</built> </load_balancer> </load_balancers> Parameters description: label – the load balancer name cpus – the number of CPU cores allocated to this load balancer operating_system_distro – the distribution of the OS created_at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format template_id – ID of the LB template operating_system - the OS on which the load balancing cluster is based enable_autoscale – true if autoscaling is enabled, otherwise false cpu_shares – the CPU priority of this load balancing cluster updated_at –- the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format memory – the amount of RAM allocated to this load balancing cluster local_remote_access_port – the port ID used for used for console access allowed_swap – true if swap disks are allowed, otherwise false recovery_mode – true if recovery mode is allowed, otherwise false allow_resize_without_reboot – true if you can resize a VM’s CPU and RAM without rebooting it ip_addresses - an array of IP addresses assigned to this load balancer and their details: disallowed_primary – true if not allowed to be used as primary (for Load Balancer build), otherwise false broadcast – broadcast address free – true if free, otherwise false network_id – the ID of a network attached to this load balancer netmask – netmask for the IP address network_address – the address of the network gateway – gateway address xen_id – the VM ID set by the virtualization engine id – the load balancing cluster ID hypervisor_id – the ID of the hypervisor used by this load balancing cluster enable_monitis – true if monitis is enabled, otherwise false user_id – the ID of the user who owns this load balancing cluster allowed_hot_migrate – true if hot migration is allowed admin_note – an optional text note 215 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 vip – true if the VIP status is set, otherwise false suspend – true if suspended, otherwise false strict_virtual_machine_id – the ID of a VM that will never reside in this load balancing cluster note – an optional text, added as a note total_disk_size – the load balancer disk size template_label – the name of the template on which this load balancing cluster is based hostname – the host name for this load balancer booted - true if the machine is booted, otherwise false remote_access_password – the password for remote access min_disk_size – the minimum disk size in GB required for a specified template initial_root_password – the VM root password identifier – identifier of the load balancer in the database monthly_bandwidth_used – the bandwidth used this month state locked – true if locked, otherwise false built – true if the load balancing cluster is built, otherwise false 28.11 Get load balancer details To get details for a particular load balancer, use the following request: GET GET /load_balancers/:id.xml /load_balancers/:id.json XML Output example <?xml version="1.0" encoding="UTF-8"?> <load_balancers type="array"> <load_balancer> <label>test.test</label> <cpus type="integer">1</cpus> <operating_system_distro>lbva</operating_system_distro> <created_at type="datetime">2012-02-28T10:58:56Z</created_at> <template_id type="integer">6</template_id> <operating_system>linux</operating_system> <enable_autoscale nil="true"/> <cpu_shares type="integer">10</cpu_shares> <updated_at type="datetime">2012-02-28T12:30:58Z</updated_at> <memory type="integer">512</memory> <local_remote_access_port type="integer">5901</local_remote_access_port> <allowed_swap type="boolean">true</allowed_swap> <recovery_mode type="boolean">false</recovery_mo de> <allow_resize_without_reboot type="boolean">true</allow_resize_without_reboot> <ip_addresses type="array"> <ip_address> <address>109.123.105.180</address> <disallowed_primary type="boolean">false</disallowed_primary> <created_at type="datetime">2012-01-20T16:02:01Z</created_at> <broadcast>109.123.105.191</broadcast> <free type="boolean">false</free> <updated_at type="datetime">2012-01-20T16:02:01Z</updated_at> <network_id type="integer">1</network_id> 216 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 <netmask>255.255.255.240</netmask> <network_address>109.123.105.176</network_address> <id type="integer">65</id> <gateway>109.123.105.177</gateway> </ip_address> </ip_addresses> <xen_id type="integer">42</xen_id> <update_billing_stat type="boolean">false</update_billing_stat> <id type="integer">307</id> <hypervisor_id type="integer">1</hypervisor_id> <enable_monitis type="boolean">false</enable_monitis> <user_id type="integer">6</user_id> <allowed_hot_migrate type="boolean">true</allowed_hot_migrate> <admin_note nil="true"/> <vip nil="true"/> <suspended type="boolean">false</suspended> <strict_virtual_machine_id nil="true"/> <note nil="true"/> <total_disk_size type="integer">6</total_disk_size> <template_label>Load Balancer Virtual Appliance</template_label> <hostname>lb.oleg.test.com</hostname> <booted type="boolean">true</booted> <remote_access_password>i1pyx4gnsmkl</remote_access_password> <min_disk_size type="integer">5</min_disk_size> <initial_root_password>z1daxmf66z6q</initial_root_password> <identifier>ju3149gpa8dyio</identifier> <add_to_marketplace nil="true"/> <monthly_bandwidth_used type="integer">4318</monthly_bandwidth_used> <state>new</state> <locked type="boolean">false</locked> <built type="boolean">true</built> </load_balancer> For parameters description refer to a Get the list of load balancers section. 28.12 Edit a load balancer To edit a load balancer, use this request: PUT PUT /load_balancers/:id.xml /load_balancers/:id.json JSON Request example curl -i -X PUT -d '{"load_balancer":{label:"Pasha2", hostname:"Pasha2", rate_limit:10}}' -u user:userpass http://onapp.test/load_balancers/:id -H 'Accept: application/json' -H 'Content-type: application/json' Where you can edit: label – the LB label hostname – hostname, associated with the LB rate_limit – the port speed, set for the LB 217 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 28.13 Start up a load balancer To start up a load balancer, use the following request: POST POST onapp.test/load_balancers/:load_balancer_id/startup.xml onapp.test/load_balancers/:load_balancer_id/startup.json XML Request example curl -i -X POST -H 'Accept: application/xml' -H 'Content-type: application/xml' -u user:userpass --url http://onapp.test/load_balancers/:load_balancer_id/startup.xml JSON Request example curl -i -X POST -H 'Accept: application/json' -H 'Content-type: application/json' -u user:userpass --url http://onapp.test/load_balancers/:load_balancer_id/startup.json 28.14 Stop a load balancer To stop a load balancer, use the following request: POST /load_balancers/:load_balancer_id/stop.xml POST /load_balancers/:load_balancer_id/stop.json XML Request example curl -i -X POST -H 'Accept: application/xml' -H 'Content-type: application/xml' -u user:userpass --url http://onapp.test/load_balancers/:load_balancer_id/stop.xml JSON Request example curl -i -X POST -H 'Accept: application/json' -H 'Content-type: application/json' -u user:userpass --url http://onapp.test/load_balancers/:load_balancer_id/stop.json 28.15 Shut down a load balancer To shut down a load balancer, use the following request: POST POST /load_balancers/:load_balancer_id/shutdown.xml /load_balancers/:load_balancer_id/shutdown.json XML Request example curl -i -X POST -H 'Accept: application/xml' -H 'Content-type: application/xml' -u user:userpass --url http://onapp.test/load_balancers/:load_balancer_id/shutdown.xml JSON Request example 218 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 curl -i -X POST -H 'Accept: application/json' -H 'Content-type: application/json' -u user:userpass --url http://onapp.test/load_balancers/:load_balancer_id/shutdown.json 28.16 Unlock a load balancer To unlock a load balancer: POST POST /load_balancers/:load_balancer_id/unlock.xml /load_balancers/:load_balancer_id/unlock.json XML Request example curl -i -X POST -H 'Accept: application/xml' -H 'Content-type: application/xml' -u user:userpass --url http://onapp.test/load_balancers/:load_balancer_id/unlock.xml JSON Request example curl -i -X POST -H 'Accept: application/json' -H 'Content-type: application/json' -u user:userpass --url http://onapp.test/load_balancers/:load_balancer_id/unlock.json 28.17 Rebuild a load balancer To rebuild a load balancer, use the following request: POST POST /load_balancers/:load_balancer_id/rebuild.xml /load_balancers/:load_balancer_id/rebuild.json XML Request example curl -X POST -u user:userpass http://onapp.test/load_balancers/:load_balancer_id/rebuild.xml -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON request example curl -X POST -u user:userpass http://onapp.test/load_balancers/:load_balancer_id/rebuild.json -H 'Accept: application/json' -H 'Content-type: application/json' 28.18 Suspend a load balancer To suspend a load balancer: POST POST /load_balancers/:load_balancer_id/suspend.xml /load_balancers/:load_balancer_id/suspend.json 219 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 XML Request example curl -i -X POST -H 'Accept: application/xml' -H 'Content-type: application/xml' -u user:userpass --url http://onapp.test/load_balancers/:load_balancer_id/suspend.xml JSON Request example curl -i -X POST -H 'Accept: application/json' -H 'Content-type: application/json' -u user:userpass --url http://onapp.test/load_balancers/:load_balancer_id/suspend.json To unsuspend a load balancer, use the same request again. 28.19 View load balancer billing statistics To view billing statistics for a load balancer: GET /load_balancers/:identifier/vm_stats.xml GET /load_balancers/:identifier/vm_stats.json Define a shorter period by setting Start and End time in the API call: GET /load_balancers/:identifier/vm_stats.xml?period[startdate]=YYYY-MMDD+hh%3Amm%3Ass&period[enddate]=YYYY-MM-DD+hh%3Amm%3Ass GET /load_balancers/:identifier/vm_stats.json?period[startdate]=YYYY-MMDD+hh%3Amm%3Ass&period[enddate]=YYYY-MM-DD+hh%3Amm%3Ass XML output example: <?xml version="1.0" encoding="UTF-8"?> <vm_stats type="array"> <vm_hourly_stat> <created_at type="datetime">2011-11-01T00:00:16Z</created_at> <usage_cost type="float">0.0</usage_cost> <updated_at type="datetime">2011-11-01T00:00:16Z</updated_at> <stat_time type="datetime">2011-11-01T00:00:00Z</stat_time> <vm_resources_cost type="float">0.0</vm_resources_cost> <total_cost type="float">0.0</total_cost> <id type="integer">9596</id> <vm_billing_stat_id type="integer">7807</vm_billing_stat_id> <user_id type="integer">1</user_id> <billing_stats> <virtual_machines type="array"> <virtual_machine> <label>qapl-cluster</label> <costs type="array"> <cost> <value type="integer">10</value> <cost type="float">0.0</cost> <resource_name>cpu_shares</resource_name> 220 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 </cost> </costs> <id type="integer">351</id> </virtual_machine> </virtual_machines> <network_interfaces type="array"> <network_interface> <label>eth0</label> <costs type="array"> <cost> <value type="integer">2</value> <cost type="float">0.0</cost> <resource_name>ip_addresses</resource_name> </cost> ... <cost></cost> ... </costs> <id type="integer">401</id> </network_interface> </network_interfaces> <disks type="array"> <disk> <label>#770</label> <costs type="array"> <cost> <value type="integer">5</value> <cost type="float">0.0</cost> <resource_name>disk_size</resource_name> </cost> ... <cost></cost> ... </costs> <id type="integer">770</id> </disk> </disks> <load_balancers type="array"> <load_balancer> <label>qapl-cluster</label> <costs type="array"> <cost> <value type="integer">2</value> <cost type="float">0.0</cost> <resource_name>template</resource_name> </cost> </costs> <id type="integer">351</id> </load_balancer> </load_balancers> </billing_stats> <virtual_machine_id type="integer">351</virtual_machine_id> <currency_code>USD</currency_code> </vm_hourly_stat> </vm_stats> Where: created_at - the timestamp in DB when this record was created 221 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 updated_at - the date when these statistics were updated usage_cost - the total due for LB usage for this particular hour specified by stat_time parameter (data sent/received, bandwidth, CPU usage) total_cost - the total amount of money owed by this particular LB for the resources spent at stat_time total_cost - the total amount of money owed for the LB specified by id parameter for a particular hour specified by stat_time parameter (total_cost = vm_resources_cost + usage_cost) vm_resources_cost - the amount of money due for the LB resources for the particular hour specified by stat_time parameter (memory, disks, templates) stat_time - the particular hour for which these statistics were generated id - the ID of these statistics user_id - the ID of LB owner currency_code - currency in which this load balancer is charged within the billing plan billing_stats - an array of billing details for the resources used by this LB virtual_machines - an array of LB billing details: • • label - LB name costs - an array of LB resources with their total prices for the period specified in the stat-time parameter, where o resource_name - the resource in question. This can be cpu_shares, cpus, memory, template, cpu_usage o value - the amount of resources allocated to this VM. Here are the units of measurment for each type of resource_name: cpu_shares – CPU priority percentage cpus - number of CPU cores memory - amount of RAM in Mb cpu_usage - CPU time in seconds cost - the total due for this resource id - load balancer ID network_interfaces - an array of network interfaces used by this LB with their billing statistics: o o o label - network interface name used in OnApp id - network interface ID costs - an array of network interface related resources with their total prices for the period specified in the stat-time parameter, where: 222 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 o o o resource_name - the resource in question. This can be ip_addresses, rate, data_received and data_sent value - the amount of resources used by this network interface.Here are the units of measurment for each type of resource_name: ip_addresses - number of IPs rate - the port speed in Mb per second data_received - amount of received data in Kb data_sent - amount of sent data in Kb cost - the total due for the resource disks - an array of disks used by this LB with their billing details: • • • label - disk name used in UI id - disk ID used in database costs - an array of disk related resources with their total prices for the period specified in the stat-time parameter, where: o resource_name - the resource in question. This can be disk_size, data_read, data_written, reads_completed and writes_completed o value - the amount of resources used. Here are the units of measurment for each type of resource_name: disk_size - size in GB data_read - read data in Kb data_written - amount of written data in Kb reads - number read operations writes - number of write operations o cost - the total due for the resource load_balancers - an array of load balancer billing details: • • • label - load balancer name id - the load balancer ID costs - an array of load balancer related resources with their total prices for the period specified in the stat-time parameter, where: o value - the template ID in this case. o cost - the total due for the resource. o resource_name - currently for load balancers only template resource is supported. 223 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 29. CDN Edge Servers CDN edge servers are the virtual machines which form a Content Delivery Network. In this network the web content is cached and delivered to end users from the server which is closest to the user or has the best availability. 29.1 View edge servers To view all edge servers in the cloud with their details, use the following request: GET GET /edge_servers.xml /edge_servers.json XML Output example <?xml version="1.0" encoding="UTF-8"?> <edge_servers type="array"> <edge_server> <label>QAVP XEN server</label> <cpus type="integer">1</cpus> <aflexi_id nil="true"></aflexi_id> <ip_addresses type="array"></ip_addresses> <operating_system_distro>ubuntu</operating_system_distro> <created_at type="datetime">2011-10-13T08:58:00Z</created_at> <template_id type="integer">14</template_id> <operating_system>linux</operating_system> <enable_autoscale nil="true"></enable_autoscale> <cpu_shares type="integer">1</cpu_shares> <updated_at type="datetime">2011-10-13T12:45:19Z</updated_at> <memory type="integer">512</memory> <local_remote_access_port type="integer">5900</local_remote_access_port> <allowed_swap type="boolean">true</allowed_swap> <recovery_mode type="boolean">false</recovery_mode> <allow_resize_without_reboot type="boolean">false</allow_resize_without_reboot> <xen_id type="integer">2</xen_id> <update_billing_stat type="boolean">true</update_billing_stat> <id type="integer">118</id> <hypervisor_id type="integer">2</hypervisor_id> <enable_monitis nil="true"></enable_monitis> <user_id type="integer">1</user_id> <allowed_hot_migrate type="boolean">false</allowed_hot_migrate> <admin_note nil="true"></admin_note> <total_disk_size type="integer">20</total_disk_size> <vip nil="true"></vip> <suspended type="boolean">false</suspended> <strict_virtual_machine_id nil="true"></strict_virtual_machine_id> <note nil="true"></note> <template_label>Debian 6.0 x64</template_label> <hostname>second.qavp</hostname> <booted type="boolean">true</booted> <remote_access_password>ra3g57xkaxij</remote_access_password> <min_disk_size type="integer">5</min_disk_size> <initial_root_password>6ok0637src0y</initial_root_password> <identifier>lf1jf5j4fpw9u5</identifier> <add_to_marketplace type="boolean">false</add_to_marketplace> <monthly_bandwidth_used type="integer">0</monthly_bandwidth_used> 224 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 <state>new</state> <locked type="boolean">false</locked> <built type="boolean">true</built> </edge_server> </edge_servers> Where: label – an arbitrary name of the edge server cpus – number of CPU cores allocated to this edge server aflexi_id – the server identifier of the edge ip_addresses – an array of assigned IP addresses operating_system_distro – the distribution of the Operating System template_id – the ID of the template, on which the edge server is based operating_system – type of Operating System enable_autoscale – false; not available for edge servers cpu_shares – the CPU priority percentage memory – the amount of RAM resources allocated to this edge server local_remote_access_port – the port ID used for console access allowed_swap – true if swap is allowed; otherwise false recovery_mode – true if the server is booted in the recovery mode; otherwise false allow_resize_without_reboot – true if adjusting resource allocation without reboot is possible; otherwise false xen_id – the edge server ID set by the virtualization engine update_billing_stat - deprecated attribute; will be removed in upcoming release id – the edge server ID in OnApp CP database hypervisor_id – the ID of the hypervisor, on which the server is deployed enable_monitis - deprecated attribute; will be removed in upcoming release user_id – the ID of the user, who is the server owner allowed_hot_migrate – true if hot migration is allowed; otherwise false 225 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 admin_note – an optional reminder for this VM created by an administrator total_disk_size – total disk space in GB of primary and swap disks vip – true if the server has VIP status for migration; otherwise false suspended – true if suspended; otherwise false strict_virtual_machine_id - the ID of a virtual machine (or edge server) that will never reside on the same HV with this server note - an optional reminder for this VM made by a user account template_label – label of the template on which the server is based; currently – Debian 6.0 x64 hostname – the name of your host booted – true if the server is booted; otherwise false remote_access_password – the password for remote access min_disk_size – minimum disk space required by the template initial_root_password – the server root password identifier – the edge server identifier add_to_marketplace - true if this edge server is added to the marketplace; otherwise false monthly_bandwidth_used – the bandwidth used by the server for this month state – deprecated attribute; will be removed in upcoming release locked – true if locked; otherwise false 29.2 View edge server details To view the edge server details: GET GET /edge_servers/:id.xml /edge_servers/:id.json For details refer to View edge servers section. 29.3 Create edge server To create an edge server, use the following API call: 226 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 POST POST /edge_servers.xml /edge_servers.json XML Request example curl -i -X POST -d '<edge_server><label>az_CDN_test</label><cpus>1</cpus><data_store_group_primary_id>2</ data_store_group_primary_id><primary_network_group_id>3</primary_network_group_id><tem plate_id>398</template_id><cpu_shares>1</cpu_shares><memory>512</memory><required_virt ual_machine_build>1</required_virtual_machine_build><hypervisor_group_id>1</hypervisor _group_id><hypervisor_id>1</hypervisor_id><required_ip_address_assignment>1</required_ ip_address_assignment><hostname>acdnt</hostname><primary_disk_size>5</primary_disk_siz e><rate_limit>0</rate_limit></edge_server>' -u admin:dev9dot162 http://onapp.test/edge_servers.xml -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X POST -d '{"edge_server":{"label":"az_CDN_test","cpus":"1","data_store_group_primary_id":"2","p rimary_network_group_id":"3","template_id":"398","cpu_shares":"1" ,"memory":"512","required_virtual_machine_build":"1","hypervisor_group_id":"1","hyperv isor_id":"1","required_ip_address_assignment":"1","hostname":"acdnt","primary_disk_siz e":"5","rate_limit":"0"}}' -u user:userpass http://onapp.test/edge_servers.json -H 'Accept: application/json' -H 'Content-type: application/json' Where: label * – an arbitrary name of your CDN edge server. The label can consist of letters [A-Za-z], digits [0-9], dash [ - ], lower dash [ _ ], space character [ ], at sign [@], brackets [(){}],slashes [/\], caret [^],dollar sign [$], asterisk [*] comma [,] and dot [.]. You can use both lower- and uppercase letters.hostname * – the name of your host template_id * – the ID of the template, on which this edge server will be based hypervisor_id * - indicate the ID of the hypervisor, on which the server will be deployed hypervisor_group_id * - indicate the hypervisor zone ID cpus * - the amount of CPU cores allocated to this edge server cpu_shares * - the percentage of allocated CPU priority resource memory * - the amount of RAM, which you want to allocate to this edge server primary_disk_size * - the size in GB of the primary disk data_store_group_primary_id – specify the ID of a data store zone, where you want to locate the disk of your server. If not specified – the system will select the data store zone with higher available capacity 227 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 primary_network_group_id – indicate the network zone ID required_virtual_machine_build – set “1” to build the server automatically after creation. Otherwise set “0” required_ip_address_assignment - set “1” if you want IP address to be assigned automatically after creation. Otherwise set “0” 29.4 Edit edge server To change the server label and resource allocation: PUT PUT /edge_servers/:id.xml /edge_servers/:id.json XML Request example curl -i -X PUT -d '<edge_server><label>az_CDN_test_1</label><cpus>1</cpus><cpu_shares>10</cpu_shares><me mory>512</memory></edge_server>' -u onapp.test http://onapp.test/edge_servers/:id.xml -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X PUT -d '{"edge_server":{"label":"az_CDN_test_3","cpus":"1","cpu_shares":"20","memory":"512"}} ' -u onapp.test http://onapp.test/edge_servers/:id.json -H 'Accept: application/json' -H 'Content-type: application/json' Where: label – an arbitrary name of your CDN edge server cpus - the amount of CPU cores allocated to this edge server cpu_shares - the percentage of allocated CPU priority resource memory - the amount of RAM, which you want to allocate to this edge server 29.5 Reboot edge server To reboot the edge server: POST POST /edge_servers/:edge_server_id/reboot.xml /edge_servers/:edge_server_id/reboot.json 228 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 XML Request example curl -i -X POST -u user:userpass http://onapp.test/edge_servers/:edge_server_id/reboot.xml -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X POST -u user:userpass http://onapp.test/edge_servers/:edge_server_id/reboot.json -H 'Accept: application/json' -H 'Content-type: application/json' 29.6 Reboot in recovery To reboot the edge server in recovery mode with a temporary login (“root”) and password (“recovery”), use the following API calls: POST POST /edge_servers/:edge_server_id/reboot.xml?mode=recovery /edge_servers/:edger_server_id/reboot.json?mode=recovery XML Request example curl -i -X POST -u user:userpass --url http://onapp.test/edge_servers/:edger_server_id/reboot.xml?mode=recovery JSON Request example curl -i -X POST -u user:userpass --url http://onapp.test/edge_servers/:edge_server_id/reboot.json?mode=recovery 29.7 Startup edge server POST POST /edge_servers/:edge_server_id/startup.xml /edge_servers/:edge_server_id/startup.json XML Request example curl -i -X POST -u user:userpass http://onapp.test/edge_servers/:edge_server_id/startup.xml -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X POST -u user:userpass http://onapp.test/edge_servers/:edge_server_id/startup.json -H 'Accept: application/json' -H 'Content-type: application/json' 29.8 Shut down edge Server To terminate the edge server gracefully: 229 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 POST POST /edge_servers/:edge_server_id/shutdown.xml /edge_servers/:edge_server_id/shutdown.json XML Request example curl -i -X POST -u user:userpass http://onapp.test/edge_servers/:edge_server_id/shutdown.xml -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X POST -u user:userpass http://onapp.test/edge_servers/:edge_server_id/shutdown.json -H 'Accept: application/json' -H 'Content-type: application/json' 29.9 Stop edge server To terminate the edge server forcefully: POST POST /edge_servers/:edge_server_id/stop.xml /edge_servers/:edge_server_id/stop.json XML Request example curl -i -X POST -u user:userpass http://onapp.test/edge_servers/:edge_server_id/stop.xml -H 'Accept: application/xml' H 'Content-type: application/xml' JSON Request example curl -i -X POST -u user:userpass http://onapp.test/edge_servers/:edge_server_id/stop.json -H 'Accept: application/json' -H 'Content-type: application/json' 29.10 Rebuild edge server To rebuild (or build manually) the edge server, use the following request: POST POST /edge_servers/:edge_server_id/build.xml /edge_servers/:edge_server_id/build.json XML Request example curl -i -X POST -u user:userpass http://onapp.test/edge_servers/:edge_server_id/build.xml -d'<?xml version="1.0" encoding="UTF8"?><edge_server><template_id>398</template_id><required_startup>1</required_startup>< /edge_server>'-H 'Accept: application/xml' -H 'Content-type: application/xml' 230 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 JSON Request example curl -i -X POST -u user:userpass http://onapp.test/edge_servers/:edge_server_id/build.json -d '{"edge_server":{"template_id":"398","required_startup":"1"}}' -H 'Accept: application/json' -H 'Content-type: application/json' Where you have to send: template_id * - the ID of the template on which this server will be based required_startup – set “1” to start up the server automatically after build. Otherwise set “0” 29.11 POST POST Suspend/unsuspend edge server /edge_servers/:edge_server_id/suspend.xml /edge_servers/:edge_server_id/suspend.json XML Request example curl -i -X POST -u user:userpass http://onapp.test/edge_servers/:edge_server_id/suspend.xml -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X POST -u user:userpass http://onapp.test/edge_servers/:edge_server_id/suspend.json -H 'Accept: application/json' -H 'Content-type: application/json' To unsuspend the server, run the request again. 29.12 Rerun edge creation scripts When an edge server is built, the system will run the scripts for creation of an edge server. You can do it manually, using the following request: POST POST /edge_servers/:edge_server_id/rerun_edge_scripts.xml /edge_servers/:edge_server_id/rerun_edge_scripts.json XML Request example curl -i -X GET -u user:userpass http://onapp.test/edge_servers/:edge_server_id/rerun_edge_scripts.xml -H 'Accept:application/xml' -H 'Content-type:application/xml' 231 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 JSON Request example curl -i -X GET -u user:userpass http://onapp.test/edge_servers/:edge_server_id/rerun_edge_scripts.json -H 'Accept:application/json' -H 'Content-type:application/json' 29.13 Unlock edge server To unlock the edge server: POST POST /edge_servers/:edge_server_id/unlock.xml /edge_servers/:edge_server_id/unlock.json XML Request example curl -i -X POST -u user:userpass http://onapp.test/edge_servers/:edge_server_id/unlock.xml -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X POST -u user:userpass http://onapp.test/edge_servers/:edge_server_id/unlock.json -H 'Accept: application/json' -H 'Content-type: application/json' 29.14 Delete edge server DELETE DELETE /edge_servers/:id.xml /edge_servers/:id.json XML Request example curl -i -X DELETE -u user:userpass http://onapp.test/edge_servers/:id.xml -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X DELETE -u user:userpass http://onapp.test/edge_servers/:id.json -H 'Accept: application/json' -H 'Content-type: application/json' 29.15 Migrate edge server To migrate an edge server to another hypervisor, use the following request: POST /edge_servers/:edge_server_id/migrate.xml POST /edge_servers/:edge_server_id/migrate.json 232 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 XML Request example curl -i -X POST -H 'Accept: application/xml' -H 'Content-type: application/xml' -u user:userpass -d "<edge_server><destination>1</destination><cold_migrate_on_rollback>1</cold_migrate_on _rollback></edge_server>" --url http://onapp.test/edge_servers/:edge_server_id/migrate.xml JSON Request example curl -i -X POST -H 'Accept: application/json' -H 'Content-type: application/json' -u user:userpass -d '{"edge_server":{"destination":"1","cold_migrate_on_rollback":"1"}}' --url http://onapp.test/edge_servers/:edge_server_id/migrate.json Where: destination * - the ID of a target hypervisor, to which you migrate the edge server cold_migrate_on_rollback - set 1 if you wish to switch to a cold migration if hot migration fails. Otherwise set 0. 29.16 Open the server console To open an edge server console: 1. Run the following request: GET GET /edge_servers/:edge_server_id/console.xml /edge_servers/:edge_server_id/console.json 2. Find and copy the value for the remote_key parameter in the response output. 3. Open the following URL in the browser: http://onapp.test/console_remote/[remote_key_parameter_value] 29.17 Segregate edge server To segregate an edge server (that is, instruct it never to reside on the same hypervisor as another VM or edge server), use the following method: POST POST /edge_servers/:edge_server_id/strict_vm.xml /edge_servers/:edge_server_id/strict_vm.json XML Request example 233 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 curl -i -X POST -H 'Accept: application/xml' -H 'Content-type: application/xml' -u user:userpass -d '<?xml version="1.0" encoding="UTF8"?><edge_server><strict_virtual_machine_id>bb6oa3eqdzpcgl</strict_virtual_machine_id> </edge_server>' --url http://onapp.test/edge_servers/:edge_server_id/strict_vm.xml JSON Request example curl -i -X POST -H 'Accept: application/json' -H 'Content-type: application/json' -u user:userpass -d '{"edge_server":{"strict_virtual_machine_id":"gv03xz1x31t53h"}}' -url http://onapp.test/edge_servers/:edge_server_id/strict_vm.json Where: strict_virtual_machine_id * - the ID of virtual machine you wish to segregate from the given edge server 29.18 Reset root password You can reset password of the edge server using the following method: POST POST /edge_servers/:edge_server_id/reset_password.xml /edge_servers/:edge_server_id/reset_password.json XML Request example curl -i -X POST -H 'Accept: application/xml' -H 'Content-type: application/xml' -u user:userpass --url http://onapp.test/edge_servers/:edge_server_id/reset_password.xml JSON Request example curl -i -X POST -H 'Accept: application/json' -H 'Content-type: application/json' -u user:userpass --url http://onapp.test/edge_servers/:edge_server_id/reset_password.json 29.19 Change edge server owner Use the following request to reassign an edge server to another user: POST POST /edge_servers/:edge_server_id/change_owner.xml /edge_servers/:edge_server_id/change_owner.json XML Request example curl -i -X POST -H 'Accept: application/xml' -H 'Content-type: application/xml' -u user:userpass -d '<user_id>4</user_id>' --url http://onapp.test/edge_servers/:edge_server_id/change_owner.xml JSON Request example 234 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 curl -i -X POST -H 'Accept: application/json' -H 'Content-type: application/json' -u user:userpass -d "{'user_id':'1'}" --url http://onapp.test/edge_servers/:edge_server_id/change_owner.json Required parameter: user_id * – input ID of a new server owner 29.20 Set VIP status To give your edge server a migration priority, set the VIP status for it with the following request: POST POST /edge_servers/:edge_server_id/set_vip.xml /edge_servers/:edge_server_id/set_vip.json XML Request example curl -i -X POST -H 'Accept: application/xml' -H 'Content-type: application/xml' -u user:userpass --url http://onapp.test/edge_servers/:edge_server_id/set_vip.xml JSON Request example curl -i -X POST -H 'Accept: application/json' -H 'Content-type: application/json' -u user:userpass --url http://onapp.test/edge_servers/:edge_server_id/set_vip.json Run the same request again to remove the VIP status. 29.21 Edit admin note To edit/make an admin note, use the following request: PUT PUT /edge_ersvers/:edge_server_id.xml /edge_servers/:edge_server_id.json XML Request example curl -i -X PUT -u user:userpass http://onapp.test/edge_servers/:edge_server_id.xml -d '<edge_server><admin_note>agfagwe tiuuytjgh yuytu</admin_note></edge_server>' -H 'Accept:application/xml' -H 'Content-type:application/xml' JSON Request example curl -i -X PUT -u user:userpass http://onapp.test/edge_servers/:edge_server_id.json -d '{"edge_server":{"admin_note":"kjfjhjtrtjt"}}' -H 'Accept:application/json' -H 'Content-type:application/json' 235 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 Where: admin_note – enter the text of your note. 29.22 CDN edge server disks Since CDN edge servers are VMs in their essence, you may perform all the same actions with edge disks as with VM disks. The only difference would be in the routes for the following requests: To add a disk to CDN edge server: POST POST /edge_servers/:edge_server_id/disks.xml /edge_servers/:edge_server_id/disks.json Parameters description and request example. To view the edge server disks: GET GET /edge_servers/:edge_server_id/disks.xml /edge_servers/:edge_server_id/disks.json Parameters description and output example. For other possible requests refer to corresponding sections of Disks chapter. 29.23 CDN edge server backups You can create backups for the edge server and later on use the backups to restore the disks. To get the list of all backups made for this edge server: GET GET /edge_servers/:edge_server_id/backups.xml /edge_servers/:edge_server_id/backups.json Parameters description and output example. To create a backup of a disk, use the following method: POST POST /settings/disks/:disk_id/backups.xml /settings/disks/:disk_id /backups.json Request example. To restore a disk from a backup, use the following method: POST POST /backups/:backup_id/restore.xml /backups/:backup_id/restore.json Request example. To delete a backup: DELETE DELETE /backups/:id.xml /backups/:id.json 236 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 Request example. 29.24 CDN edge server network interfaces Here is the list of API calls for managing CDN edge servers’ network interfaces. Edge servers’ network interfaces have the same attributes as network interfaces of virtual machines. To get the list of network interfaces allocated to this particular edge server: GET GET /edge_servers/:edge_server_id/network_interfaces.xml /edge_servers/:edge_server_id/network_interfaces.json Parameters description and output example. To get a particular network interface details: GET GET /edge_servers/:edge_server_id/network_interfaces/:id.xml /edge_servers/:edge_server_id/network_interfaces/:id.json Parameters description and output example. To edit network interface details: PUT PUT /edge_servers/:edge_server_id/network_interfaces/:id.xml /edge_servers/:edge_server_id/network_interfaces/:id.json Parameters description and request example. To add a new network interface: POST POST /edge_servers/:edge_server_id/network_interfaces.xml /edge_servers/:edge_server_id/network_interfaces.json Parameters description and request example. To delete a network interface from the edge server: DELETE DELETE /edge_servers/:edge_server_id/network_interfaces/:id.xml /edge_servers/:edge_server_id/network_interfaces/:id.json Parameters description and request example. 29.25 IP address joins An IP address allocated to an edge server is an IP address join. Use the following methods to view, assign and delete IP address joins of your CDN edge servers. To get the list of IP address assignments for a particular edge server: GET GET /edge_servers/:edge_server_id/ip_addresses.xml /edge_servers/:edge_server_id/ip_addresses.json Parameters description and output example. To assign an IP Address to an edge server: 237 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 POST POST /edge_servers/:edge_server_id/ip_addresses.xml /edge_servers/:edge_server_id/ip_addresses.json Parameters description and request example. To delete an IP address assignment from a particular VM: DELETE DELETE /edge_servers/:edge_server_id/ip_addresses/:id.xml /edge_servers/:edge_server_id/ip_addresses/:id.json Parameters description and request example. 29.26 Rebuild Network for edge server It is required to rebuild network after any changes on IP address joins or network interfaces. To rebuild network, use the following request: POST POST /edge_servers/:edge_server_id/rebuild_network.xml /edge_servers/:edge_server_id/rebuild_network.json XML Request example curl -i -X POST -u user:userpass http://onapp.test/edge_servers/:edge_server_id/rebuild_network.xml -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X POST -u user:userpass http://onapp.test/edge_servers/:edge_server_id/rebuild_network.json -H 'Accept: application/json' -H 'Content-type: application/json' 29.27 Firewall rules for CDN edge servers Firewall rules for CDN edge servers function in the same way as for VMs. Use the following requests to see, add, edit and delete firewall rules. To get the list of firewall rules assigned to a VM, use the following request: GET GET /edge_servers/:edge_server_id/firewall_rules.xml /edge_servers/:edge_server_id/firewall_rules.json Parameters description and output example. To edit a firewall rule, use the following request: PUT PUT /edge_servers/:edge_server_id/firewall_rules/:id.xml /edge_servers/:edge_server_id/firewall_rules/:id.json Parameters description and request example. To add a firewall rule, use the following request: 238 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 POST POST /edge_servers/:edge_server_id/firewall_rules.xml /edge_servers/:edge_server_id/firewall_rules.json Parameters description and request example. To delete a firewall rule, use the fllowing request: DELETE DELETE /edge_servers/:edge_server_id/firewall_rules/:id.xml /edge_servers/:edge_server_id/firewall_rules/:id.json Parameters description and request example. 29.28 Billing statistics for CDN edge server You can view the billing statistics for a particular edge server using the following request: GET GET /edge_servers/:edge_server_id/vm_stats.xml /edge_servers/:edge_server_id/vm_stats.json <?xml version="1.0" encoding="UTF-8"?> <vm_stats type="array"> <vm_hourly_stat> <created_at type="datetime">2011-11-01T00:00:13Z</created_at> <updated_at type="datetime">2011-11-01T00:00:13Z</updated_at> <stat_time type="datetime">2011-11-01T00:00:00Z</stat_time> <total_cost type="float">0.0</total_cost> <id type="integer">9582</id> <vm_billing_stat_id type="integer">7795</vm_billing_stat_id> <user_id type="integer">1</user_id> <billing_stats> <virtual_machines type="array"> <virtual_machine> <label>QAVP XEN serveridze</label> <costs type="array"> <cost> <value type="integer">100</value> <resource_name>cpu_shares</resource_name> <cost type="float">0.0</cost> </cost> ... <cost></cost> ... </costs> <id type="integer">237</id> </virtual_machine> </virtual_machines> <network_interfaces type="array"> <network_interface> <label>eth0</label> <costs type="array"> <cost> <value type="integer">1</value> <resource_name>ip_addresses</resource_name> <cost type="float">0.0</cost> </cost> ... <cost></cost> ... </costs> <id type="integer">254</id> </network_interface> 239 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 </network_interfaces> <disks type="array"> <disk> <label>#499</label> <costs type="array"> <cost> <value type="integer">20</value> <resource_name>disk_size</resource_name> <cost type="float">0.0</cost> </cost> ... <cost></cost> ... </costs> <id type="integer">499</id> </disk> </disks> <edge_servers type="array"> <edge_server> <label>QAVP XEN serveridze</label> <costs type="array"> <cost> <value type="integer">14</value> <resource_name>template</resource_name> <cost type="float">0.0</cost> </cost> </costs> <id type="integer">237</id> </edge_server> </edge_servers> </billing_stats> <usage_cost type="float">0.0</usage_cost> <virtual_machine_id type="integer">237</virtual_machine_id> <currency_code>USD</currency_code> <vm_resources_cost type="float">0.0</vm_resources_cost> </vm_hourly_stat> </vm_stats> Where: created_at – the timestamp in DB when this record was created updated_at – the date when these statistics were updated cost – the total amount of money owed by this particular edge server for the resources spent at stat_time stat_time – the particular hour for which these statistics were generated id – the ID of these statistics user_id - the ID of edge server owner currency_code - currency in which this virtual machine is charged within the billing plan billing_stats - an array of billing details for the resources used by this edge server virtual_machine - an array of edge server billing details: • • label – name of the edge server costs - an array of edge server resources with their total prices for the period specified in the stattime parameter, where: 240 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 o o o o resource_name - the resource in question. This can be cpu_shares, cpus, memory, cpu_usage and template value - the amount of resources allocated to this edge server. Here are the units of measurment for each type of resource_name: cpu_shares - CPU priority percentage cpus - number of CPU cores memory - amount of RAM in Mb cpu_usage - CPU time in seconds cost - the total due for this resource id - Virtual machine ID network_interfaces - an array of network interfaces used by this edge server with their billing statistics: • • • label - network interface name used in OnApp id - network interface ID costs - an array of network interface related resources with their total prices for the period specified in the stat-time parameter, where: o resource_name - the resource in question. This can be ip_addresses, rate, data_received and data_sent o value - the amount of resources used by this network interface. Here are the units of measurment for each type of resource_name: ip_addresses - number of IPs rate - the port speed in Mb per second data_received - amount of received data in Kb data_sent - amount of sent data in Kb o cost - the total due for the resource disks - an array of disks used by this edge server with their billing details: • • • label - disk name used in UI id - disk ID used in database costs - an array of disk related resources with their total prices for the period specified in the stattime parameter, where: o resource_name - the resource in question. This can be disk_size, data_read, data_written, reads_completed and writes_completed o value - the amount of resources used. Here are the units of measurment for each type of resource_name: disk_size - size in GB data_read - read data in Kb data_writen - amount of written data in Kb reads - number read operations writes - number of write operations 241 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 o cost - the total due for the resource edge_server - an array of edge server with its billing details: • • • label – edge server name used in UI id – server ID used in database costs - an array of related resources with their total prices for the period specified in the stat-time parameter, where: o resource_name - the resource in question. In this case - template o value – here, the template ID in the database o cost - the total due for the resource total_cost – the total amount of money owed for the edge server specified by id parameter for a particular hour specified by stat_time parameter (total_cost = vm_resources_cost + usage_cost) vm_resources_cost – the amount of money due for the edge server resources for the particular hour specified by stat_time parameter (memory, disks, templates) usage_cost – the total due for edge server usage for this particular hour specified by stat_time parameter (data sent/received, bandwidth, CPU usage) 242 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 30. CDN Resources A CDN resource is a host (e.g. a specific web server), the content of which you are going to distribute over the network of edge servers. The list of servers taking part in distributing/caching of data is limited to the locations added to those edge groups assigned to the resource. 30.1 Enable CDN Before a user can make use of CDN resources, it is necessary to enable CDN first. To enable CDN, run the following request: POST /cdn_resources/enable.xml POST /cdn_resources/enable.json XML request example: curl -i -X POST http://onapp.test/cdn_resources/enable.xml -u user:userpass -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON request example: curl -i -X POST http://onapp.test/cdn_resources/enable.json -u user:userpass -H 'Accept: application/json' -H 'Content-type: application/json' 30.2 View the list of CDN resources To see all CDN resources in the cloud, use the following request: GET GET /cdn_resources.xml /cdn_resources.json XML Output example <?xml version="1.0" encoding="UTF-8"?> <cdn_resources type="array"> <cdn_resource> <created_at type="datetime">2011-10-13T15:25:43+05:30</created_at> <resource_type>HTTP_PULL</resource_type> <updated_at type="datetime">2011-10-13T15:25:43+05:30</updated_at> <origins_for_api type="array"> <origins_for_api> <value>qa2.onappdev.com</value> <key></key> </origins_for_api> </origins_for_api> <id type="integer">2</id> <user_id type="integer">1</user_id> <cdn_hostname>cdn.qa2.onappdev.com</cdn_hostname> <aflexi_resource_id>211714645</aflexi_resource_id> <last_24h_cost type="float">0.0</last_24h_cost> 243 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 </cdn_resource> ... <cdn_resource></cdn_resource> ... </cdn_resources> Where: resource_type – currently, only HTTP PULL origins_for_api – the path from which the CDN requests the content value – the path to the content key – access key, if any id – the resource ID in the database user_id – the ID of the user, who owns the resource cdn_hostname - the hostname which will serve static content aflexi_resource_id – the resource ID in the Aflexi database last_24h_cost - the amount due for the last 24 hours 30.3 View CDN resource basic details To view details of the particular CDN resource: GET GET /cdn_resources/:id.xml /cdn_resources/:id.json XML Output example: <?xml version="1.0" encoding="UTF-8"?> <cdn_resource> <origins_for_api type="array"> <origin> <value>testhost2.com.uk</value> <key></key> </origin> </origins_for_api> <created_at type="datetime">2012-02-24T13:10:43+02:00</created_at> <status>ACTIVE</status> <last_24h_cost type="float">0.0</last_24h_cost> <resource_type>HTTP_PULL</resource_type> <updated_at type="datetime">2012-02-24T13:10:43+02:00</updated_at> <id type="integer">1</id> <user_id type="integer">1</user_id> <cdn_hostname>testhost.com.uk</cdn_hostname> <aflexi_resource_id>903435027</aflexi_resource_id> 244 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 <edge_groups type="array"> <edge_group> <label>CDN Sync runner (DONT TOUCH)</label> <created_at type="datetime">2012-02-22T14:52:21+02:00</created_at> <updated_at type="datetime">2012-02-22T14:52:21+02:00</updated_at> <id type="integer">30</id> </edge_group> </edge_groups> </cdn_resource> Where: resource_type – currently, only HTTP PULL origins – the path from which the CDN requests the content value – the path to the content key – access key, if any id – the resource ID in the database user_id – the ID of the user, who owns the resource cdn_hostname - the hostname which will serve static content aflexi_resource_id – the resource ID in the Aflexi database created_at – the date when the record was created in DB updated_at – the date when the record was updated status – the resource status (can be Active, Suspended, Inactive) last_24h_cost – the amount of money owed for the resource for the last 24 hours. edge_groups – the array of edge groups assigned to this resource, where: label – the label of the particular edge group assigned id – the edge group id 30.4 View CDN resource advanced details To view advanced details of the CDN resource, use the following request: GET GET /cdn_resources/:id/advanced.xml /cdn_resources/:id/advanced.json XML Output example 245 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 <?xml version="1.0" encoding="UTF-8"?> <cdn_resource><password_unauthorized_html>anytext</password_unauthorized_html> <url_signing_on type="boolean">true</url_signing_on> <cache_expiry type="integer">90</cache_expiry> <url_signing_key>dcahcgDAD</url_signing_key> <hotlink_policy>ALLOW_BY_DEFAULT</hotlink_policy> <publisher_name>admin</publisher_name> <domains>www.example.com</domains> <password_on type="boolean">true</password_on> <ip_access_policy>ALLOW_BY_DEFAULT</ip_access_policy> <passwords> <qqqqqq>wwwwwww</qqqqqq> </passwords> <country_access_policy>BLOCK_BY_DEFAULT</country_access_policy> </cdn_resource> Where: password_unauthorized_html – the message that is displayed when there is unauthorized access hotlink_policy – displays the hotlink policy; either NONE (disabled), ALLOW_BY_DEFAULT or BLOCKED_BY_DEFAULT country_policy – displays access policy to the CDN resource’s content for specified countries; either NONE (disabled), ALLOW_BY_DEFAULT or BLOCKED_BY_DEFAULT ip_access_policy – displays access policy from a range of IP addresses; either NONE (disabled), ALLOW_BY_DEFAULT or BLOCKED_BY_DEFAULT publisher_name – login name of the user, who created the resource domains password_on – true, if the access to the resource is restricted; otherwise false passwords – an array of username and password for restricted access in the following format: <username>password</username> cache_expiry – cache expiry in minutes url_signing_on – true if the access requires URL signing; otherwise false url_signing_key – the key for URL signing; a signed URL looks like: http://example.com/filename?hash=url-signing-key== 30.5 View the list of available edge groups To view the list of all the edge groups and their locations, which are available to create CDN resources on, use the following request: 246 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 GET GET /cdn_resources/available_edge_groups.xml /cdn_resources/available_edge_groups.json The list of available edge groups is defined by the billing plan to which a user is assigned. XML Output example: <?xml version="1.0" encoding="UTF-8"?> <edge_groups type="array"> <edge_group> <label>eg01</label> <edge_group_locations type="array"> <edge_group_location> <city>dallas</city> <price type="decimal">0.7</price> <created_at type="datetime">2012-03-01T11:16:10+02:00</created_at> <country>US</country> <aflexi_location_id type="integer">147</aflexi_location_id> <updated_at type="datetime">2012-03-01T11:16:10+02:00</updated_at> <id type="integer">10</id> <operator>WK</operator> <edge_group_id type="integer">35</edge_group_id> </edge_group_location> </edge_group_locations> <created_at type="datetime">2012-03-01T11:09:28+02:00</created_at> <updated_at type="datetime">2012-03-01T11:09:28+02:00</updated_at> <id type="integer">35</id> </edge_group> </edge_groups> Where: edge_groups – the array of edge groups with their locations available for a user to create a CDN resource on. edge_group – the particular edge group details: label – the edge group label edge_group_locations – the array of locations assigned to this group: edge_group_location – the list of details for a particular edge group city – the city where the edge server is located price - price per GB of sold excess bandwidth created_at – the date when the record was created in DB country – ther country where the server is located 247 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 aflexi_location_id – the ID of this location in Aflexi database updated_at – the date when the record was updated in DB id – the location ID operator – the location operator edge_group_id – the ID of the edge group to which this location is assigned 30.6 Create CDN Resource To create a CDN resource, use the following request: POST POST /cdn_resources.xml /cdn_resources.json XML Request example curl -i -X POST -d '<cdn_resource><cdn_hostname>az.test.api</cdn_hostname><edge_group_ids type="array"><edge_group_id type="integer">1</edge_group_id></edge_group_ids><resource_type>HTTP_PULL</resource_ty pe><origin>origin4.com</origin></cdn_resource>' -u admin:dev7dot194 http://onapp.test/cdn_resources.xml -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X POST -d '{"cdn_resource":{"edge_group_ids":["1"],"resource_type":"HTTP_PULL","origin":"originr 2.com","cdn_hostname":"cdn.test92.com"}}' -u admin:changeme http://onapp.test/cdn_resources.json -H 'Accept: application/json' -H 'Content-type: application/json' Where you have to send: origin * - the path from which the CDN requests the content cdn_hostname * - indicate the hostname which will serve static content resource_type * - currently, only HTTP_PULL edge_group_ids * - indicate the ID(s) of required CDN edge groups 30.7 Create CDN Resource with advanced settings To create a CDN resource with advanced settings, use the following request: 248 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 POST POST /cdn_resources.xml /cdn_resources.json JSON Request example curl -i -X POST -d '{"cdn_resource":{"ip_access_policy":"ALLOW_BY_DEFAULT","ip_addresses":"10.10.10.10, 20.20.20.0/24","hotlink_policy":"ALLOW_BY_DEFAULT","domains":"www.yoursite.come mirror.yoursite.com", "resource_type":"HTTP_PULL", "edge_group_ids":["1","3"], "form_pass":{"pass":["534254rgertw5w65"], "user":["herh"]}, "country_access_policy":"ALLOW_BY_DEFAULT", "countries":"", "cache_expiry":"10", "origin":"az.za","cdn_hostname":"az.advanced.api", "password_on":"treytryertyrty", "url_signing_on":"1","password_unauthorized_html":"agafgshgthweregtrherh","url_signing _key":"DMF1ucDxtqgxwYQ"},"advanced_settings":"1"}' -u user:userpass http://onapp.test/cdn_resources.json -H 'Accept: application/json' -H 'Content-type: application/json' Where: origin * - the path from which the CDN requests the content cdn_hostname * - indicate the hostname which will serve static content resource_type * - currently, only HTTP_PULL edge_group_ids * - indicate the ID(s) of required CDN edge groups advanced_settings * - set 1 to enable advanced settings ip_access_policy - configure a rule to enable/disable access to the CDN resource’s content for a range of IP addresses: • • • ALLOW_BY_DEFAULT - to enable BLOCK_BY_DEFAULT - to disable NONE - to switch off the rule ip_addresses - IP address(es) related to ip_access_policy parameter; The comma-separated list of IP addresses or IP ranges allowed/blocked by default. Use the following format "10.10.10.10, 20.20.20.0/24" hotlink_policy - configure a rule to enable/disable hotlink policy regarding the domains specified by the domains parameter: • • • ALLOW_BY_DEFAULT - to enable BLOCK_BY_DEFAULT - to disable NONE - to switch off the rule domains - domains related to hotlink_policy 249 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 country_access_policy - configure a rule to enable/disable access to the CDN resource’s content for specified countries: • • • ALLOW_BY_DEFAULT - to enable BLOCK_BY_DEFAULT - to disable NONE - to switch off the rule countries - IDs of the countries, related to country_access_policy. You can find the IDs of the countries in the database or in the html source of the CDN Resource > Edit screen of your Control Panel. cache_expiry - set the cache expiry time in minutes url_signing_on - set 1 to enable and protect your files from unauthorized access with a key url_signing_key - input the key for URL signing password_on - set 1 to enable and to restrict access to the resource (cdn_hostname); otherwise set 0 form_pass - an array with usernames and passwords to access the resource pass - password user - username password_unauthorized_html - text, which will be displayed in case of fail of authentication 30.8 Edit CDN resource To edit details of the CDN resource, use the following API call: PUT PUT /cdn_resources/:id.xml /cdn_resources/:id.json XML Request example curl -i -X PUT -d '<cdn_resource><cdn_hostname>az.test.api</cdn_hostname><edge_group_ids type="array"><edge_group_id type="integer">1</edge_group_id></edge_group_ids><resource_type>HTTP_PULL</resource_ty pe><origin>origin4.com</origin></cdn_resource>' -u user:userpass http://onapp.test/cdn_resources.xml -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example 250 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 curl -i -X PUT -d '{"cdn_resource":{"edge_group_ids":["1"],"resource_type":"HTTP_PULL","origin":"originr 2.com","cdn_hostname":"cdn.test92.com"}}' -u user:userpass http://onapp.test/cdn_resources.json -H 'Accept: application/json' -H 'Content-type: application/json' Where you can edit all strings: origin - the path from which the CDN requests the content cdn_hostname - indicate the hostname which will serve static content resource_type - currently, only HTTP_PULL edge_group_ids - indicate the ID(s) of required CDN edge groups 30.9 Edit CDN resource advanced settings To edit advanced settings of the CDN resource, use the following request: PUT PUT /cdn_resources/:id.xml /cdn_resources/:id.json curl -i -X PUT -d '{"cdn_resource":{"ip_access_policy":"ALLOW_BY_DEFAULT", "hotlink_policy":"ALLOW_BY_DEFAULT", "resource_type":"HTTP_PULL", "edge_group_ids":["1"], "form_pass":{"pass":["", "534254rgertw5w65"], "user":["", "asdh"]}, "country_access_policy":"ALLOW_BY_DEFAULT", "cache_expiry":"10", "origin":"az.za", "cdn_hostname":"az.advanced.api.edit", "password_on":"[FILTERED]", "url_signing_on":"1", "password_unauthorized_html":"[FILTERED]", "ip_addresses":"", "url_signing_key":"DMF1ucDxtqgxwYQ"}, "advanced_settings":"1"}' -u user:userpass http://onapp.test/cdn_resources/3.json -H 'Accept: application/json' -H 'Content-type: application/json For parameters description, refer to Create CDN resource with advanced settings section. 30.10 Prefetch CDN resource content To pre-populate HTTP PULL content to the CDN, use the following API call: POST POST /cdn_resources/:id/prefetch.xml /cdn_resources/:id/prefetch.json XML Request example curl -i -X POST -u user:userpass http://onapp.test/cdn_resources/:cdn_resource_id/prefetch.xml -d '<prefetch_paths>/home/123.jpeg</prefetch_paths>' -H 'Accept:application/xml' -H 'Content-type:application/xml' JSON Request example 251 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 curl -i -X POST -u user:userpass http://onapp.test/cdn_resources/:cdn_resource_id/prefetch.json -d '{"prefetch_paths":"/home/123.jpeg"}' -H 'Accept:application/json' -H 'Contenttype:application/json' Where: prefetch_path *– path to the file you want to prefetch 30.11 Purge CDN resource content To remove content from HTTP Pull cache, use the following request: POST POST /cdn_resources/: id/purge.xml /cdn_resources/: id/purge.json XML Request example curl -i -X POST -u user:userpass http://onapp.test/cdn_resources/:cdn_resource_id/purge.xml -d '<purge_paths>/home/123.jpeg</purge_paths>' -H 'Accept:application/xml' -H 'Contenttype:application/xml' JSON Request example curl -i -X POST -u user:userpass http://onapp.test/cdn_resources/:cdn_resource_id/purge.json -d '{"purge_paths":"/home/123.jpeg"}' -H 'Accept:application/json' -H 'Contenttype:application/json' Where: purge_path – path to the content you want to remove 30.12 Delete CDN resource To delete a CDN resource: DELETE DELETE /cdn_resources/:id.xml /cdn_resources/:id.json XML Request example curl -i -X DELETE -u user:userpass http://onapp.test /cdn_resources/:id.xml JSON Request example 252 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 curl -i -X DELETE -u user:userpass http://onapp.test/cdn_resources/:id.json 30.13 View bandwidth statistics To get bandwidth statistics for the resources or a particular resource, use the following request: GET GET /cdn_resources/bandwidth.xml /cdn_resources/bandwidth.json You can also define a shorter period, specify a particular resource or location and set the type: XML Request example curl -i -X GET -u user:userpass -H 'Accept: application/xml' -H 'Content-type: application/xml' --url "http://onapp.test/cdn_resources/bandwidth.xml?start=2011-0901&end=2012-09-01&resources\[\]=787341593&locations\[\]=18&type=MBPS" JSON Request example curl -i -X GET -u user:userpass -H 'Accept: application/json' -H 'Content-type: application/json' --url "http://onapp.test/cdn_resources/bandwidth.json?start=2011-0901&end=2012-09-01&resources\[\]=787341593&locations\[\]=18&type=MBPS" Where: start – the start date to generate statistics in the YYYY-MM-DD format end – the end date to generate statistics in the YYYY-MM-DD format resources – the identifier of the resource in Aflexi database. To get the identifier, check with aflexi_resource_id parameter in the GET /cdn_resources/:id.{format} request. locations – the ID of the location type – the statistics type (MBPS or GB). XML output example: <?xml version="1.0" encoding="UTF-8"?> <stats type="array"> <stat> <non_cached type="float">144.0</non_cached> <cached type="float">1456.0</cached> <date type="datetime">2012-02-15T00:00:00+00:00</date> </stat> </stats> 253 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 Where: non_cached – the amount of content which is not cached cached – the amount of data cached date – the point of time for which the statistics is generated 30.14 View billing statistics for a resource To view billing statistics for a resource: GET /cdn_resources/:id/billing.xml GET /cdn_resources/:id/billing.json You can also define a shorter period by setting Start and End date: GET /cdn_resources/:id/billing.xml?period[startdate]=YYYY-MMDD+hh%3Amm%3Ass&period[enddate]=YYYY-MM-DD+hh%3Amm%3Ass GET /cdn_resources/:id/billing.json?period[startdate]=YYYY-MMDD+hh%3Amm%3Ass&period[enddate]=YYYY-MM-DD+hh%3Amm%3Ass XML output example: <?xml version="1.0" encoding="UTF-8"?> <edge_statistics type="array"> <edge_statistic> <data_non_cached type="integer">9000000</data_non_cached> <created_at type="datetime">2012-02-18T00:15:00Z</created_at> <data_cached type="integer">91000000</data_cached> <updated_at type="datetime">2012-02-18T00:15:00Z</updated_at> <id type="integer">1846</id> <cdn_resource_id type="integer">60</cdn_resource_id> <user_id type="integer">1552</user_id> <edge_group_location_id type="integer">47</edge_group_location_id> <edge_id type="integer">393278157</edge_id> <location_id type="integer">210</location_id> <edge_group_id type="integer">22</edge_group_id> <cost type="float">0.0103</cost> </edge_statistic> </edge_statistics> <user_hourly_stats type="array"> <user_hourly_stat> <edge_group_label>WHMCS Edge Group</edge_group_label> <target_id type="integer">7</target_id> <cost type="float">12.0000004172325</cost> <stat_time type="datetime">2012-03-01T11:00:00Z</stat_time> <value type="decimal">2.4</value> 254 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 </user_hourly_stat> Where: data_non_cached – the amount of data which is not cached created_at – the date when the record was created in DB data_cached – the amount of data which is cached updated_at – the date when the record was updated in DB id – the ID of these statistics cdn_resource_id - the ID of the CDNresource for which these statistics are generated user_id – the ID of the user who owns a resource edge_group_location_id – the ID of the join of the location and edge group edge_id - the ID of the edge server in Aflexi DB edge_id location_id - the ID of the location edge_group_id – the ID of the edge group edge_ - the ID of the edge group_id 255 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 31. CDN Edge groups CDN edge groups are groups of edge servers – your own, and those you subscribe to from the CDN marketplace. They are usually grouped by location, so they represent a pool of servers for a given geographical area. Once you have created an edge group containing edge servers in specific locations, you can then assign the group (or groups) to a specific CDN resource. You need to associate CDN Edge groups with billing plans to make them available for users. 31.1 View CDN edge groups To view CDN edge groups available in the cloud: GET GET /edge_groups.xml /edge_groups.json XML Output example <?xml version="1.0" encoding="UTF-8"?> <edge_groups type="array"> <edge_group> <label>tredty</label> <created_at type="datetime">2011-10-11T12:58:40Z</created_at> <updated_at type="datetime">2011-10-11T12:58:40Z</updated_at> <id type="integer">1</id> </edge_group> ... <edge_group></edge_group> ... </edge_groups> Where: label – the edge group label id – the group id in the database 31.2 View CDN edge group details To view the edge group details, use the following request: GET GET /edge_groups/:id.xml /edge_groups/:id.json XML Output example 256 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 <?xml version="1.0" encoding="UTF-8"?> <edge_group> <label>VLTEst</label> <created_at type="datetime">2011-11-07T13:17:21Z</created_at> <updated_at type="datetime">2011-11-07T13:17:21Z</updated_at> <id type="integer">1</id> <available_locations type="array"> <aflexi_location> <price type="float">0.0</price> <region>H9</region> <city>london</city> <latitude type="float">51.5</latitude> <country>GB</country> <updatedAt type="datetime">2011-10-12T12:52:45Z</updatedAt> <id type="integer">21</id> <deleted type="boolean">false</deleted> <geoblocking type="boolean">false</geoblocking> <operator> <name>Operator Name</name> <companyName>OnAPP Development</companyName> <companyDescription></companyDescription> <statusReason></statusReason> <updatedAt type="datetime">2011-10-12T12:51:44Z</updatedAt> <username>onapp-87-3550df8b64c5106eab79e2c0cb0176dc</username> <role>OPERATOR</role> <id type="integer">550464843</id> <companyPhone>0</companyPhone> <principal> </principal> <createdAt type="datetime">2011-10-12T12:51:44Z</createdAt> <status>ACTIVE</status> <email>[email protected]</email> </operator> <createdAt type="datetime">2011-10-12T12:52:45Z</createdAt> <longitude type="float">-0.116667</longitude> <description></description> <status>ACTIVE</status> </aflexi_location> </available_locations> <assigned_locations type="array"> <aflexi_location> <price type="float">2.0</price> <region>15</region> <city>lvov</city> <latitude type="float">49.8333</latitude> <country>UA</country> <updatedAt type="datetime">2011-11-07T13:14:59Z</updatedAt> <id type="integer">30</id> <deleted type="boolean">false</deleted> <geoblocking type="boolean">false</geoblocking> <operator> <name>Operator Name</name> <companyName>OnAPP Development</companyName> <companyDescription></companyDescription> <statusReason></statusReason> <updatedAt type="datetime">2011-10-12T12:51:44Z</updatedAt> <username>onapp-87-3550df8b64c5106eab79e2c0cb0176dc</username> <role>OPERATOR</role> <id type="integer">550464843</id> <companyPhone>0</companyPhone> <principal> </principal> <createdAt type="datetime">2011-10-12T12:51:44Z</createdAt> 257 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 <status>ACTIVE</status> <email>[email protected]</email> </operator> <createdAt type="datetime">2011-11-07T13:14:59Z</createdAt> <longitude type="float">24.0</longitude> <description></description> <status>ACTIVE</status> </aflexi_location> ... <aflexi_location></aflexi_location> ... </assigned_locations> </edge_group> Where: available_locations – an array of all available locations assigned_locations – an array of locations, which are assigned to the group aflexi_location – an array of location details city – city where the edge server is located region – region where the edge server is located price – price per GB of sold excess bandwidth latitude – latitude of the server location longitude – longitude of the server location country – country where the server is located updatedAt – date when the location was updated deleted – true if the location is deleted; otherwise false id – the ID of location in the OnApp CP data base operator – an array with details on location operator • • • • • • name – name of the operator companyName – name of the company to whom this location belongs companyDescription – optional description of the company username - username of the user role – role of the user: OPERATOR - a user that operates the cloud and enables the CDN for it; PUBLISHER – a user that creates CDN resources in OnApp CP id – the ID of the user in OnApp Dashboard, which is also stored in OnApp CP database to reference the users 258 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 • • • companyPhone – telephone number of the company status – status of the operator (i.e. VALIDATING, ACTIVE, RESTRICTED, SUSPENDED) email – contact email of the user geoblocking – true, if Geo blocking is enabled ( a technology to prevent access to web sites from visitors in particular countries or regions); otherwise false createdAt - date, when the location was created description – optional description of the location status – the location status (i.e. ACTIVE, DELETED) 31.3 Create CDN edge group To create an edge group, use the following API call: POST POST /edge_groups.xml /edge_groups.json XML Request example curl -i -X POST -u user:userpass http://onapp.test/edge_groups.xml -d '<edge_group><label>az_3</label></edge_group>' -H 'Accept:application/xml' -H 'Content-type:application/xml' JSON Request example curl -i -X POST -u user:userpass http://onapp.test/edge_groups.json -d '{"edge_group":{"label":"az_4"}}' -H 'Accept:application/json' -H 'Contenttype:application/json' Parameters: label * - the name of new group 31.4 Edit CDN edge group You can edit the label of the edge group: PUT PUT /edge_groups/:id.xml /edge_groups/:id.json XML request example 259 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 curl -i -X PUT -u user:userpass http://onapp.test/edge_groups/:id.xml -d '<edge_group><label>az_5</label></edge_group>' -H 'Accept:application/xml' -H 'Content-type:application/xml' JSON Request example curl -i -X PUT -u user:userpass http://onapp.test/edge_groups/:id.json -d '{"edge_group":{"label":"az_6"}}' -H 'Accept:application/json' -H 'Contenttype:application/json' 31.5 Delete CDN edge group To delete the edge group, use the following request: DELETE DELETE /edge_groups/:id.xml /edge_groups/:id.json XML Request example curl -i -X DELETE -u user:userpass http://onapp.test/edge_groups/:id.xml -H 'Accept:application/xml' -H 'Content-type:application/xml' JSON Request example curl -i -X DELETE -u user:userpass http://onapp.test/edge_groups/:id.json -H 'Accept:application/json' -H 'Content-type:application/json' 31.6 Assign location to the group CDN edge group details return the array of all locations available to your cloud. Check the ID of the required location and assign it to the group with the following API call: POST POST /edge_groups/:edge_group_id/assign.xml /edge_groups/:edge_group_id/assign.json XML Request example curl -i -X POST -u user:userpass http://onapp.test/edge_groups/1/assign.xml -d '<location>175</location>' -H 'Accept:application/xml' -H 'Contenttype:application/xml' JSON Request example curl -i -X POST -u user:userpass http://onapp.test/edge_groups/1/assign.json -d '{"location":"175"}' -H 'Accept:application/json' -H 'Content-type:application/json' 260 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 Where: location * - input the ID of the required location 31.7 Unassign location from the group To remove a location from the group, use the following method: POST POST /edge_groups/:edge_group_id/unassign.xml /edge_groups/:edge_group_id/unassign.json XML Request example curl -i -X POST -u user:userpass http://onapp.test/edge_groups/1/unassign.xml -d '<location>175</location>' -H 'Accept:application/xml' -H 'Contenttype:application/xml' JSON Request example curl -i -X POST -u user:userpass http://onapp.test/edge_groups/1/unassign.json -d '{"location":"175"}' -H 'Accept:application/json' -H 'Content-type:application/json' 261 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 32. CDN usage statistics CDN usage statistics shows the detailed information on all the resources used by CDN. GET /cdn_usage_statistics.xml GET /cdn_usage_statistics.json XML Output example: <?xml version="1.0" encoding="UTF-8"?> <cdn_stats> <cdn_stat> <edge_group_id>30</edge_group_id> <cached>0.0</cached> <user_id>1530</user_id> <location_id>331</location_id> <non_cached>0.0</non_cached> </cdn_stat> </cdn_stats> Where: edge_group_id - the ID of the edge group in use cached - the amount of data cached user_id - the ID of the OnApp user location_id - the ID of the location assigned to this particular edge group (edge_group_id) in OnApp non_cached - the amount of data non-cached 262 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 33. DNS setup The DNS setup chapter provides OnApp customers with information how to create a DNS hostname. After you create a DNS hostname, you get access to creating and managing DNS zones. 33.1 Get DNS domain details To view the DNS domain details, send the following request: GET /settings/dns_setup.xml GET /settings/dns_setup.json XML Output example <?xml version="1.0" encoding="UTF-8"?> <dns_setup> <domain>mydns.com</domain> </dns_setup> Where: domain – DNS domain name. 33.2 Set up DNS domain To set up DNS domain, use the following methods: POST /settings/dns_setup.xml POST /settings/dns_setup.json XML Request example curl -i -H 'Accept: application/xml' -H 'Content-type: application/xml' -u user:userpass http://onapp.test/settings/dns_setup.xml -X POST -d "<dns_setup><domain>new-mydns.com</domain></dns_setup>" JSON Request example curl -i -H 'Accept: application/json' -H 'Content-type: application/json' -u user:userpass http://onapp.test/settings/dns_setup.json -X PUT -d '{"dns_setup": {"domain": "my-dns2.com"}}' Where: The only required parameter is domain * – DNS domain name. XML Response example <?xml version="1.0" encoding="UTF-8"?> <dns_setup> 263 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 <domain>mydns.com</domain> </dns_setup> 33.3 Edit DNS domain To edit DNS domain, send the following request: PUT /settings/dns_setup.xml PUT /settings/dns_setup.json XML Request example curl -i -H 'Accept: application/xml' -H 'Content-type: application/xml' -u user:userpass http://onapp.test/settings/dns_setup.xml -X PUT -d "<dns_setup><domain>my-dns.com</domain></dns_setup>" JSON Request example curl -i -H 'Accept: application/json' -H 'Content-type: application/json' -u user:userpass http://onapp.test/settings/dns_setup.json -X PUT -d '{"dns_setup": {"domain": "my-dns2.com"}}' Where: The only required parameter is domain * – DNS domain name. You will get a 200 status response on success and 404 if the domain name is invalid or you entered incorrect URL. 33.4 Get the list of glue records To get the list of glue records, use the following request: GET /settings/dns_setup/glue_records.xml GET /settings/dns_setup/glue_records.json XML Output example <?xml version="1.0" encoding="UTF-8"?> <hash> <ns1>109.23.125.206</ns1> <ns2>109.23.125.206</ns2> <ns3>109.23.125.206</ns3> <ns4>109.23.125.206</ns4> </hash> Where: ns1, ns2, ns3, ns4 – DNS domain glue records. 264 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 265 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 34. DNS zone OnApp DNS Zone feature allows you to manage your and your clients’ domain DNS. Each time DNS zone, record or setup settings are refreshed, the DNS configuration is immediately updated on the DNS vendor server. 34.1 Get the list of own DNS zones To get the list of your own DNS zones: GET /dns_zones.xml GET /dns_zones.json XML Response example <?xml version="1.0" encoding="UTF-8"?> <dns_zones type="array"> <dns_zone> <name>dns_example</name> <created_at type="datetime">2011-12-19T12:51:02Z</created_at> <updated_at type="datetime">2011-12-19T12:51:02Z</updated_at> <id type="integer">5</id> <user_id type="integer">1</user_id> </dns_zone> Where: name – DNS zone name created_at – the date when the DNS zone was created in the [YYYY][MM][DD]T[hh][mm][ss]Z format updated_at – the date when the DNS zone was updated in the [YYYY][MM][DD]T[hh][mm][ss]Z format id – DNS zone ID user_id – the ID of a user who has created a DNS zone 34.2 Get the list of users DNS zones To get the list of DNS zones created by users: GET /dns_zones/user.xml GET /dns_zones/user.json XML Output example 266 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 <?xml version="1.0" encoding="UTF-8"?> <dns_zones type="array"> <dns_zone> <name>yoyohow.com</name> <created_at type="datetime">2011-12-30T11:56:55Z</created_at> <updated_at type="datetime">2011-12-30T11:56:55Z</updated_at> <id type="integer">13</id> <user_id type="integer">1</user_id> </dns_zone> </dns_zones> Where: name – DNS zone name created_at – the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format updated_at – the date when the DNS zone was updated in the [YYYY][MM][DD]T[hh][mm][ss]Z format id – DNS zone ID user_id – the ID of a user who has created a DNS zone 34.3 Get the domain zone details The following method returns details for a particular domain zone: GET /dns_zones/:id.xml GET /dns_zones/:id.json XML Output example <?xml version="1.0" encoding="UTF-8"?> <dns_zone> <name>abc3.com</name> <created_at type="datetime">2011-12-19T12:51:02Z</created_at> <updated_at type="datetime">2011-12-19T12:51:02Z</updated_at> <id type="integer">5</id> <user_id type="integer">1</user_id> </dns_zone> Where: name– DNS zone name created_at – the date when the DNS zone was created in the [YYYY][MM][DD]T[hh][mm][ss]Z format updated_at – the date when the DNS zone was updated in the [YYYY][MM][DD]T[hh][mm][ss]Z format id – DNS zone ID 267 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 user_id – the ID of a user who has created a DNS zone 34.4 Add new DNS zone Use the following methods to create a new DNS zone: POST /dns_zones.xml POST /dns_zones.json XML Request example curl -i -X POST http://onapp.test/dns_zones.xml -d '<dns_zone><name>domain.com</name><auto_populate>1</auto_populate></dns_zone>' -u user:userpass -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X POST http://onapp.test/dns_zones.json -d '{"dns_zone":{"name":"domain.com", "auto_populate":"1" }}' -u user:userpass -H 'Accept: application/json' -H 'Contenttype: application/json' Where: name * – name of a DNS zone you create auto_populate – autopopulate option lets you automatically import your existing DNS settings. To autopopulate your DNS settings, set the autopopulate value 1, otherwise set 0. You will get a 200 status response on success, and 404 if there is no DNS zone with a requested ID or you entered incorrect URL. 34.5 Delete DNS zone To delete a DNS zone, use the following API call: DELETE /dns_zones/:id.xml DELETE /dns_zones/:id.json XML Request example Curl -i -X DELETE --url http://onapp.test/dns_zones/:dns_zone_id.xml -u user:userpass JSON Request example curl -i -X DELETE --url http://onapp.test/dns_zones/:dns_zone_id.json -u user:userpass 268 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 You will get a 200 status response on success, and 404 if there is no DNS zone with a requested ID or you entered incorrect URL. 34.6 Get the list of name servers To get the list of name servers, use the following request: GET /dns_zones/name_servers.xml GET /dns_zones/name_servers.json XML Output example <?xml version="1.0" encoding="UTF-8"?> <strings type="array"> <string>ns1.qaonapp.com</string> <string>ns2.qaonapp.com</string> <string>ns3.qaonapp.com</string> <string>ns4.qaonapp.com</string> </strings> 34.7 Get the list of DNS Zone Records Use the following API calls to view DNS zone records: GET /dns_zones/:dns_zone_id/records.xml GET /dns_zones/:dns_zone_id/records.json XML Output example <?xml version="1.0" encoding="UTF-8"?> dns_zone> <name>example.com</name> <created_at type="datetime">2012-01-19T16:53:47Z</created_at> <updated_at type="datetime">2012-01-19T16:53:47Z</updated_at> <id type="integer">322</id> <user_id type="integer">1</user_id> <records> <MX type="array"> <dns_record> <name>@</name> <ttl type="integer">3600</ttl> <priority type="integer">10</priority> <id type="integer">3540</id> <type>MX</type> <hostname>mx1.me.com.akadns.net</hostname> </dns_record> </MX> <SRV type="array"> <dns_record> <name>_xmpp._tcp</name> <ttl type="integer">86400</ttl> <port type="integer">5222</port> <weight type="integer">1</weight> <priority type="integer">0</priority> <id type="integer">4533</id><type>SRV</type> 269 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 <hostname>jabber.example.com</hostname> </dns_record> </SRV> <A type="array"> <dns_record> <name>@</name> <ttl type="integer">20</ttl> <id type="integer">3547</id> <type>A</type> <ip>17.172.192.8</ip> </dns_record> </A> <CNAME type="array"> <dns_record> <name>www</name> <ttl type="integer">3600</ttl> <id type="integer">3551</id> <type>CNAME</type> <hostname>www.me.com.edgekey.net</hostname> </dns_record> </CNAME> <AAAA type="array"> <dns_record> <name>sdfgeg</name> <ttl type="integer">456</ttl> <id type="integer">4052</id> <type>AAAA</type> <ip>::</ip> </dns_record> </AAAA> <TXT type="array"> <dns_record> <name>@</name> <ttl type="integer">3600</ttl> <id type="integer">3546</id> <txt>v=spf1 ip4:17.0.0.0/8 ~all</txt> <type>TXT</type> </dns_record> </TXT> <NS type="array"> <dns_record> <name>@</name> <ttl type="integer">86400</ttl> <id type="integer">3555</id> <type>NS</type> <hostname>ns1.testeteststestt.com</hostname> </dns_record> </NS> <SOA type="array"> <dns_record> <name>@</name> <serial type="integer">2010111206</serial> <primaryNs>ns1.testeteststestt.com</primaryNs> <retry type="integer">172800</retry> <ttl type="integer">86400</ttl> <id type="integer">3539</id> <refresh type="integer">12096007</refresh> <type>SOA</type> <minimum type="integer">1200</minimum> <expire type="integer">2592000</expire> <hostmaster>admin.example.com</hostmaster> </dns_record> </SOA> 270 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 </records> </dns_zone> Where: name – DNS zone name. created_at – the date when the DNS zone was created in the [YYYY][MM][DD]T[hh][mm][ss]Z format updated_at - the date when the DNS zone was updated in the [YYYY][MM][DD]T[hh][mm][ss]Z format id – DNS zone ID user_id – the ID of a user who has created a DNS zone The array of DNS records sorted by type with their details: MX – the array of mail exchange records with the following parameters: name – DNS domain set for the record ttl – time to live value id – DNS zone ID type – the type of the record. For this array, it is MX priority - the mail server preference hostname – DNS hostname SRV – the array of service records with the following parameters: name – DNS domain set for the record ttl – time to live value port – the port on this target host of this service. weight – the proportion of traffic the server pointed to will handle. priority – the priority of the target host id – DNS zone ID hostname – DNS hostname A – the array of A host records with the following parameters: name – DNS domain set for the record 271 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 ttl – time to live value id – DNS zone ID type – the type of the record. For this array, it is A ip – domain IP CNAME – the array of CNAME records with the following parameters: name – DNS domain set for the record ttl – time to live value id – DNS zone ID type – the type of the record. For this array, it is CNAME hostname – DNS hostname AAAA – the array of AAAA record with the following parameters: name – DNS domain set for the record ttl – time to live value id – DNS zone ID type – the type of the record. For this array, it is AAAA ip – domain IP TXT – the array of TXT record with the following parameters: name – DNS domain set for the record ttl – time to live value id – DNS zone ID txt – TXT value type - the type of the record. For this array, it is TXT NS – the array of name server records with the following parameters: name – DNS domain set for the record ttl – time to live value 272 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 id – DNS zone ID type – the type of the record. For this array, it is NS hostname – DNS hostname SOA – the array of start of authority record with the following parameters: name – DNS domain set for the record serial – DNS zone serial number primary Ns – primary name server retry - the amount of time your secondary name servers will wait to contact the primary name server again if the last attempt failed ttl – time to live value id – DNS zone ID refresh – the number of seconds between update requests type – DNS record name. For this array, it is SOA minimum – value of negative caching (in seconds) expire - the number of seconds a server will wait before considering the data invalid if it cannot reach the primary name server hostmaster – a hostmaster e-mail address 34.8 Get a particular record’s details GET /dns_zones/:dns_zone_id/records/:record_id.xml GET /dns_zones/:dns_zone_id/records/:record_id.json XML Output example <?xml version="1.0" encoding="UTF-8"?> <dns_record> <name>sub2</name> <ttl type="integer">121</ttl> <id type="integer">2689</id> <type>A</type> <ip>127.0.0.0</ip> </dns_record> Where: 273 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 name – DNS zone name. ttl – the time to live value type – the record type. This can be one of the following records: NS, A, AAAA, CNAME, MX, TXT or SRV id – DNS zone ID ip – domain IP 34.9 Create DNS record To create a DNS record: POST /dns_zones/:dns_zone_id/records.xml POST /dns_zones/:dns_zone_id/records.json XML Request example curl –i-X POST http://onapp.test/dns_zones/:dns_zone_id/records.xml -d "<dns_record><name>test</name><ttl>111</ttl><type>A</type><ip>127.1.1.1</ip></dns_reco rd>" -u user:userpass -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X POST http://onapp.test/dns_zones/:dns_zone_id/records.json -d '{"dns_record":{"name":"TEST_NAME",ttl:"111",type:"A",ip:"127.1.1.1"}}' -u user:userpass -H 'Accept: application/json' -H 'Content-type: application/json' Where: name * – DNS record name ttl * – the time to live value type * – the record type ip * – host IP ( for A and AAAA records) XML Response example <?xml version="1.0" encoding="UTF-8"?> <dns_record> <name>test23</name> <ttl>111</ttl> <id type="integer">2696</id> <type>A</type> <ip>127.1.1.1</ip> </dns_record> 274 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 34.10 Edit DNS records To edit a DNS record: PUT /dns_zones/:dns_zone_id/records/:record_id.xml PUT /dns_zones/:dns_zone_id/records/:record_id.json XML Request example curl –i-X PUT http://onapp.test/dns_zones/:dns_zone_id/records/:record_id.xml -d "<dns_record><name>test</name><ttl>86400</ttl></dns_record>" -u user:userpass -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -i -X PUT http://onapp.test/dns_zones/:dns_zone_id/records/:record_id.json -d '{"dns_record":{"name":"TEST_NAME",ttl:"111"}}' -u user:userpass -H 'Accept: application/json' -H 'Content-type: application/json' You can edit the following parameters for the following DNS records: MX record: name * – DNS domain set for the record ttl * – time to live value priority * – the mail server preference hostname * – DNS hostname SRV record: name * – DNS domain set for the record ttl * – time to live value port * – the port on this target host of this service. weight * – the proportion of traffic the server pointed to will handle. priority * – the priority of the target host hostname * – DNS hostname A record: name * – DNS domain set for the record 275 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 ttl * – time to live value ip * – domain IP CNAME record name * – DNS domain set for the record ttl * – time to live value hostname * – DNS hostname AAAA record name * – DNS domain set for the record ttl * – time to live value ip * – domain IP TXT record name * – DNS domain set for the recor ttl * – time to live value txt * – TXT value NS record name * – DNS domain set for the record ttl * – time to live value hostname * – DNS hostname SOA record name * – DNS domain set for the record serial * – zone serial number primary Ns * – primary name server retry * – the amount of time your secondary name servers will wait to contact the primary name server again if the last attempt failed (in seconds) ttl * – time to live value refresh * – the number of seconds between update requests 276 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 minimum * – value of negative caching (in seconds) expire * – the number of seconds a server will wait before considering the data invalid if it cannot reach the primary name server hostmaster * – a hostmaster email address XML Response example <?xml version="1.0" encoding="UTF-8"?> <dns_record> <name>@</name> <ttl type="integer">1001</ttl> <id type="integer">2680</id> <type>NS</type> <hostname>ns1.worldcdn-beta-operator.doubleukay.com</hostname> </dns_record> You will get a 200 status response on success, and 404 if there is no DNS zone with a requested ID or you entered incorrect URL. 34.11 Delete a record To delete a record: DELETE /dns_zones/:dns_zone_id/records/:record_id.xml DELETE /dns_zones/:dns_zone_id/records/:record_id.json XML Request example curl -i-X DELETE --url http://onapp.test/dns_zones/:dns_zone_id/records/:record_id.xml -u user:userpass JSON Request example curl -X DELETE --url http://onapp.test/dns_zones/:dns_zone_id/record/:record_id.json -u user:userpass 277 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 35. Backups Lists the backups taken of that virtual machine, and provides tools to restore a backup, delete backups, and convert backups to templates. 35.1 Get the list of VM backups GET GET /virtual_machines/:virtual_machine_id/backups.xml /virtual_machines/:virtual_machine_id/backups.json An array of backups is returned. If there are no backups, an empty array is returned. XML Output example <?xml version="1.0" encoding="UTF-8"?> <backups type="array"> <backup> <marked_for_delete type="boolean">false</marked_for_delete> <disk_id type="integer">4180</disk_id> <built_at type="datetime">2011-02-18T23:38:51Z</built_at> <disk_id type="integer">38</disk_id> <created_at type="datetime">2011-02-18T23:35:54Z</created_at> <operating_system_distro>rhel</operating_system_distro> <operating_system>linux</operating_system> <template_id type="integer">19</template_id> <allowed_swap type="boolean">true</allowed_swap> <backup_type>normal</backup_type> <updated_at type="datetime">2011-02-18T23:38:51Z</updated_at> <allow_resize_without_reboot type="boolean">true</allow_resize_without_reboot> <id type="integer">15</id> <backup_server_id type="integer">1</backup_server_id> <allowed_hot_migrate type="boolean">true</allowed_hot_migrate> <backup_size>442788</backup_size> <identifier>c4th2akcgycse7</identifier> <min_disk_size type="integer">0</min_disk_size> <built type="boolean">true</built> <locked type="boolean">false</locked> </backup> </backups> Where: marked_for_delete – the backup is marked for deletion (for autobackups) built_at – the date when the disk backup was built disk_id – the id of a disk backed up created_at – the date when the record in the database was created updated_at – the date when this record in database was updated 278 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 operating_system_distro – the OS distribution of the VM backed up operating_system – the OS of the VM backed up template_id – the ID of a template from which the VM backed up was built allowed_swap – True if swap disk is allowed for VM backed up backup_type – Disk backup allowed_resize_without_reboot – True if resizing CPU & RAM is allowed without restarting the VM backed up ID – the ID of this backup backup_server_id – the ID of the backup server on which the backup is stored allowed_hot_migrate – True if hot migration is allowed for the VM backed up backup_size – the disk space taken by this backup in MB min_disk_size – the minimum disk size built – true if the VM backed up has been built locked – true if the VM backed up has been locked 35.2 Create a disk backup To create a backup of a disk, use the following method: POST POST /settings/disks/:disk_id/backups.xml /settings/disks/:disk_id /backups.json XML Request example curl -i -X POST -H 'Accept: application/xml' -H 'Content-type: application/xml' -u user:userpass --url http://onapp.test/settings/disks/:disk_id/backups.xml JSON Request example curl -i -X POST -H 'Accept: application/json' -H 'Content-type: application/json' -u user:userpass --url http://onapp.test/settings/disks/:disk_id/backups.json 35.3 Convert a backup to a template You can convert a backup into a custom template. A label for a template can be set with the backup[label], minimum disk size and minimum memory size parameters. 279 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 POST POST /backups/:backup_id/convert.xml /backups/:backup_id/convert.json XML Request example curl -i -X POST -H 'Accept: application/xml' -H 'Content-type: application/xml' -u user:userpass -d'<?xml version="1.0" encoding="UTF-8" ?><backup><label>template.label</label><min_disk_size>50</min_disk_size><min_memory_si ze>1024</min_memory_size></backup>' --url http://onapp.test/backups/:backup_id/convert.xml JSON Request example curl -i -X POST -H 'Accept: application/json' -H 'Content-type: application/json' -u user:userpass -d'{"backup":{"label":"backup_label", "min_disk_size":"20", "min_memory_size":"512"}}' –url http://onapp.test/backups/:backup_id/convert.json 35.4 Restore a backup You can restore a disk from a backup, using the following method: POST POST /backups/:backup_id/restore.xml /backups/:backup_id/restore.json XML Request example curl -i -X POST -H 'Accept: application/xml' -H 'Content-type: application/xml' -u user:userpass --url http://onapp.test/backups/:backup_id/restore.xml JSON Request example curl -i -X POST -H 'Accept: application/json' -H 'Content-type: application/json' -u user:userpass --url http://onapp.test/backups/:backup_id/restore.json 35.5 Delete a backup To delete a disk backup: DELETE DELETE /backups/:id.xml /backups/:id.json XML Request example curl -i -X DELETE -H 'Accept: application/xml' -H 'Content-type: application/xml' -u user:userpass --url http://onapp.test/backups/:id.xml JSON Request example 280 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 curl -i -X DELETE -H 'Accept: application/json' -H 'Content-type: application/json' -u user:userpass --url http://onapp.test/backups/:id.json An HTTP 200 response is returned on success, an HTTP 404 error is returned if a requested backup does not exist. 281 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 36. Autobackup presets Autobackup presets are a simple way to set up an automatic backup schedule when Virtual Machines are created. Once configured, they can be applied to a VM automatically when the Automatic Backups Required parameter is enabled during VM creation. 36.1 Get the list of autobackup presets To get the list of available autobackup presets, use the following request: GET GET /autobackup_presets.xml /autobackup_presets.json An array of autobackup presets is returned. If there are no presets, an empty array is returned. XML Output example <?xml version="1.0" encoding="UTF-8"?> <autobackup_templates type="array"> <autobackup_template> <duration type="integer">1</duration> <created_at type="datetime">2011-07-14T15:01:38Z</created_at> <updated_at type="datetime">2011-07-28T11:49:52Z</updated_at> <period>days</period> <id type="integer">1</id> <enabled type="boolean">true</enabled> </autobackup_template> <autobackup_template> <duration type="integer">1</duration> <created_at type="datetime">2011-07-14T15:01:38Z</created_at> <updated_at type="datetime">2011-07-28T11:50:21Z</updated_at> <period>weeks</period> <id type="integer">2</id> <enabled type="boolean">true</enabled> </autobackup_template> ... <autobackup_template></autobackup_template> ... </autobackup_templates> Explanation of the data returned: duration created at period updated at enabled id the number specifying how often a backup should be taken the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format the time period (days, weeks, months, or years) the date when the autobackup preset was updated in the [YYYY][MM][DD]T[hh][mm][ss]Z format true if the autobackup preset is enabled, otherwise false. the ID of the autobackup preset 282 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 36.2 Get autobackup preset details This method will output the details for a particular autobackup preset. GET GET /autobackup_presets/:id.xml /autobackup_presets/:id.json XML Output example <?xml version="1.0" encoding="UTF-8"?> <autobackup_template> <duration type="integer">1</duration> <created_at type="datetime">2011-01-06T10:49:43Z</created_at> <period>days</period> <updated_at type="datetime">2011-01-06T10:49:43Z</updated_at> <enabled type="boolean">true</enabled> <id type="integer">1</id> </autobackup_template> Where: duration created_at period updated_at enabled id edit the number specifying how often a backup should be taken the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format specifies the time period (days, weeks, months, or years) the date when the autobackup preset was updated in the [YYYY][MM][DD]T[hh][mm][ss]Z format set True if autobackup preset is enabled, otherwise False edit an autobackup preset ID 36.3 Edit an autobackup preset To edit an autobackup preset, use the following method: PUT PUT /autobackup_presets/:id.xml /autobackup_presets/:id.json XML Request example curl -i -X PUT -H 'Accept: application/xml' -H 'Content-type: application/xml' -u user:userpass -d'<?xml version="1.0" encoding="UTF8"?><autobackup_template><duration>5</duration><period>days</period><enabled>false</en abled></autobackup_template>' --url http://onapp.test/autobackup_presets/:id.xml JSON Request example curl -i -X PUT -H 'Accept: application/json' -H 'Content-type: application/json' -u user:userpass -d'{"autobackup_template":{"duration":"5","period":"weeks","enabled": "false"}}' --url http://onapp.test/autobackup_presets/:id.json You can edit the following parameters: 283 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 duration enabled Edit the number specifying how often a backup should be taken Set True if autobackup preset is enabled, otherwise False Every autobackup_preset_id has its defined period (either days, or weeks, or months, or years), which cannot be altered. 284 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 37. Schedules Schedules are concerned with backups scheduled for virtual machines in the cloud. When a schedule is no longer needed, it can be deleted so that the task will no longer run. 37.1 Get the list of schedules This method outputs an array of the disk backups scheduled within your cloud. If there are no schedules, an empty array is returned. GET GET /schedules.xml /schedules.json XML Output example <?xml version="1.0" encoding="UTF-8"?> <schedules> <schedule> <duration>1</duration> <created_at>2011-07-20T15:16:16Z</created_at> <target_id>112</target_id> <updated_at>2011-07-28T15:16:18Z</updated_at> <period>days</period> <action>autobackup</action> <start_at>2011-07-29T15:16:16Z</start_at> <id>33</id> <user_id>1</user_id> <schedule_logs> <schedule_log> <created_at>2011-07-28T15:16:17Z</created_at> <updated_at>2011-07-28T15:16:17Z</updated_at> <schedule_id>33</schedule_id> <id>12</id> <log_output></log_output> <status>complete</status> </schedule_log> ... <schedule_log></schedule_logs> ... <params nil="true"></params> <failure_count>0</failure_count> <status>enabled</status> <target_type>Disk</target_type> </schedule> </schedules> Where: duration created_at target_id How often a disk backup is taken The date in the [YYYY][MM][DD]T[hh][mm][ss]Z format The disk ID for which a backup is taken 285 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 Period updated_at Action Id start_at user_id failure_count Status target_type Time period for a backup schedule (days, weeks, months, or years) The date when a schedule was updated in the [YYYY][MM][DD]T[hh][mm][ss]Z format Currently, only autobackup action is performed by schedules Schedule ID The date when a backup started in the [YYYY][MM][DD]T[hh][mm][ss]Z format The ID of a user who created this schedule The number of requests processed until the task fails The status of the backup schedule (enabled, disabled, or failed) Currently, you can schedule backup of Disks only 37.2 Get schedule details Use this method to get details for a particular disk backup schedule: GET GET /schedules/:id.xml /schedules/:id.json XML Output Example <?xml version="1.0" encoding="UTF-8"?> <schedules> <schedule> <duration>1</duration> <created_at>2011-07-20T15:16:16Z</created_at> <target_id>112</target_id> <updated_at>2011-07-28T15:16:18Z</updated_at> <period>days</period> <action>autobackup</action> <start_at>2011-07-29T15:16:16Z</start_at> <id>33</id> <user_id>1</user_id> <schedule_logs> <schedule_log> <created_at>2011-07-28T15:16:17Z</created_at> <updated_at>2011-07-28T15:16:17Z</updated_at> <schedule_id>33</schedule_id> <id>12</id> <log_output></log_output> <status>complete</status> </schedule_log> ... <schedule_log></schedule_logs> ... <params nil="true"></params> <failure_count>0</failure_count> <status>enabled</status> <target_type>Disk</target_type> </schedule> Where: 286 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 Duration created_at target_id Period updated_at Action Id start_at user_id failure_count Status target_type How often a disk backup is taken The date in the [YYYY][MM][DD]T[hh][mm][ss]Z format The disk ID for which a backup is taken Time period for a backup schedule (days, weeks, months, or years) The date when a schedule was updated in the [YYYY][MM][DD]T[hh][mm][ss]Z format Currently, only autobackup action is performed by schedules Schedule ID The date when a backup started in the [YYYY][MM][DD]T[hh][mm][ss]Z format The ID of a user who created this schedule The number of requests processed until the task fails The status of the backup schedule (enabled, disabled, or failed) Currently, you can schedule backup of Disks only 37.3 Edit a schedule To edit a schedule, use the following method: PUT PUT /schedules/:id.xml /schedules/:id.json XML Request example curl -i -X PUT -H 'Accept: application/xml' -H 'Content-type: application/xml' d'<?xml version="1.0" encoding="UTF8"?><schedule><duration>3</duration><period>days</period><status>enabled</status></sch edule>' -u user:userpass --url http://onapp.test/schedules/:id.xml JSON Request example curl -i -X PUT -H 'Accept: application/json' -H 'Content-type: application/json' d'{"schedule":{"duration":"1","period":"years","status":"enabled"}}' -u user:userpass --url http://onapp.test/schedules/:id.json Currently, you can edit the following parameters: duration* How often a disk backup is taken period* Time period for a backup schedule (days, weeks, months, or years) status* Set enabled to activate a schedule. 287 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 37.4 Delete a schedule DELETE DELETE /schedules/:id.xml /schedules/:id.json XML Request example curl -i -X DELETE -H 'Accept: application/xml' -H 'Content-type: application/xml' -u user:userpass --url http://onapp.test/schedules/:id.xml JSON Request example curl -i -X DELETE -H 'Accept: application/json' -H 'Content-type: application/json' -u user:userpass --url http://onapp.test/schedules/:id.json 288 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 38. License How to show the details of the OnApp license key edit license details. 38.1 Get license details To see the license details, use the following request: GET GET /settings/license.xml /settings/license.json Output example application_state> <license_type>PAID</license_type> <core_limit type="integer">-1</core_limit> <valid_license type="boolean">true</valid_license> </application_state> Where: license_type – type of the license core_limit – number of CPU cores allowed by license; “-1” stands for unlimited number of cores valid_license – true, if valid 38.2 Edit license details To update license, use the following call: PUT PUT /settings.xml /settings.json XML Request example curl -i -X PUT -u user:userpass http://onapp.test/settings.xml d'<configuration><licence_key>NNNN-NNNNN-NNNNN-NNNNN-NNNNNNNNNN</licence_key></configuration>' -H 'Accept: application/xml' -H'Contenttype: application/xml' JSON Request example curl -i -X PUT -u user:userpass http://onapp.test/settings.json d'{"configuration":{"licence_key":"NNNN-NNNNN-NNNNN-NNNNN-NNNNN-NNNNN"}}' -H 'Accept: application/json' -H'Content-type: application/json' 289 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 Where: license_key – the key of your OnApp license 290 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 39. SSH keys 39.1 View SSH keys To see all the keys in the cloud, use the following request: GET GET /settings/ssh_keys.xml /settings/ssh_keys.json XML Output example: <?xml version="1.0" encoding="UTF-8"?> <ssh_keys type="array"> <ssh_key> <created_at type="datetime">2011-09-13T16:10:02Z</created_at> <updated_at type="datetime">2011-09-13T16:10:02Z</updated_at> <id type="integer">3</id> <user_id type="integer">1</user_id> <key>ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAqzsLk+oPP9Qxz0Xgpqoe9DqNV7Qe3+oig/o6Ubt30Yh+Zarf8NXctqqeam C1KrlMt12d0AWd38dZ0CU6Eru/2ciwzz2IB0MLrTyjfLCNe2CW64uNjhSS1SH6gSjJUYwHSi7jUBl0vlGtJ7js wBdhgaKkjk1vXH3YFLTHPuKU+pc= [email protected] </key> </ssh_key> </ssh_keys> Where: ssh_key – an array which displays the key info id – the SSH key ID user_id – ID of the user to whom the key belongs key – SSH key 39.2 Add a SSH key To add SSH keys to a user profile, use the following call: POST POST /user/:user_id/ssh_keys.xml /user/:user_id/ssh_keys.json XML Request example curl -X POST -u user:userpass http://onapp.test/users/:user_id/ssh_keys.xml -H 'Accept: application/xml' -H 'Content-type: application/xml' –d’<ssh_key><key> ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAqzsLk+oPP9Qxz0Xgpqoe9DqNV7Qe3+oig/o6Ubt30Yh+Zarf8NXctqqeam C1KrlMt12d0AWd38dZ0CU6Eru/2ciwzz2IB0MLrTyjfLCNe2CW64uNjhSS1SH6gSjJUYwHSi7jUBl0vlGtJ7js wBdhgaKkjk1vXH3YFLTHPuKU+pc= [email protected]</key></ssh_key>’ JSON Request example 291 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 curl -X POST -u user:userpass http://onapp.test/users/:user_id/ssh_keys.json -H 'Accept: application/json' -H 'Content-type: application/json' –d’{“ssh_key”:{“key”:” ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAqzsLk+oPP9Qxz0Xgpqoe9DqNV7Qe3+oig/o6Ubt30Yh+Zarf8NXctqqeam C1KrlMt12d0AWd38dZ0CU6Eru/2ciwzz2IB0MLrTyjfLCNe2CW64uNjhSS1SH6gSjJUYwHSi7jUBl0vlGtJ7js wBdhgaKkjk1vXH3YFLTHPuKU+pc= [email protected]”}}’ Where: key * - a SSH key in the following format: ssh-[type] [ascii-symbols allowed for base64 string] [user credentials] 39.3 Edit a SSH key To edit a SSH key you may use both types of requests: PUT PUT /users/:user_id/ssh_keys/:id.xml /users/:user_id/ssh_keys/:id.json or PUT PUT /settings/ssh_keys/:id.xml /settings/ssh_keys/:id.json XML Request example curl -X POST -u user:userpass http://onapp.test/users/:user_id/ssh_keys/:id.xml -H 'Accept: application/xml' -H 'Content-type: application/xml' –d’<ssh_key><key> ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAqzsLk+oPP9Qxz0Xgpqoe9DqNV7Qe3+oig/o6Ubt30Yh+Zarf8NXctqqeam C1KrlMt12d0AWd38dZ0CU6Eru/2ciwzz2IB0MLrTyjfLCNe2CW64uNjhSS1SH6gSjJUYwHSi7jUBl0vlGtJ7js wBdhgaKkjk1vXH3YFLTHPuKU+pc= [email protected]</key></ssh_key>’ JSON Request example curl -X POST -u user:userpass http://onapp.test/users/:user_id/ssh_keys/:id.json -H 'Accept: application/json' -H 'Content-type: application/json' –d’{“ssh_key”:{“key”:” ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAqzsLk+oPP9Qxz0Xgpqoe9DqNV7Qe3+oig/o6Ubt30Yh+Zarf8NXctqqeam C1KrlMt12d0AWd38dZ0CU6Eru/2ciwzz2IB0MLrTyjfLCNe2CW64uNjhSS1SH6gSjJUYwHSi7jUBl0vlGtJ7js wBdhgaKkjk1vXH3YFLTHPuKU+pc= [email protected]”}}’ 39.4 Delete a SSH key. To delete a SSH from the system (and from the user profile), use the following request: DELETE DELETE /settings/ssh_keys/:id.xml /settings/ssh_keys/:id.json 292 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 XML Request example curl -X DELETE -u user:userpass http://onapp.test/settings/ssh_keys/:id.xml -H 'Accept: application/xml' -H 'Content-type: application/xml' JSON Request example curl -X DELETE -u user:userpass http://onapp.test/settings/ssh_keys/:id.json -H 'Accept: application/json' -H 'Content-type: application/json' 293 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 40. Statistics Statistics show detailed information on the resources used by virtual machines. Get daily stats (information on the resources used by virtual machines): GET GET /usage_statistics.xml /usage_statistics.json Only the GET method is available for statistics. This method sends back usage statistics for all virtual machines in the cloud (per VM for the last 48 hours). XML Output example <?xml version="1.0" encoding="UTF-8"?> <vm_stats> <vm_stat> <data_sent>0.0</data_sent> <reads_completed>328892.0</reads_completed> <data_received>0.0</data_received> <cpu_usage>2813.0</cpu_usage> <virtual_machine_id>883</virtual_machine_id> <writes_completed>193395.0</writes_completed> <data_read>1315568.0</data_read> <user_id>1</user_id> <data_written>773580.0</data_written> </vm_stat> ... <vm_stat></vm_stat> ... </vm_stats> Explanation of the data returned data_sent - the amount of Kilobytes sent by this VM reads_completed - the number of read operations performed by the disk data_received - the amount of Kilobytes received by this VM cpu_usage - shows how long (in seconds) the VM has been using CPU for the last 72 hours or during the specified period virtul_machine_id - the ID of the VM for which these statistics are generated writes_completed - the number of write operations performed by the disk data_read - the amount of data read from a disk in Kilobytes 294 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 data_written - the amount of data written to a disk in Kilobytes Other statistics generated in the system: • • • • • • View user’s statistics View billing statistics for a user View disk IOPS (Input/Output statistics) Billing statistics for a VM Billing statistics for CDN edge servers View Load balancer billing statistics 295 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 41. Background task daemon Background task daemon starts/stops/reloads/checks status of all background tasks that run in the system. 41.1 Start background task daemon To start background task daemon, run: POST /sysadmin_tools/daemon/start.xml POST /sysadmin_tools/daemon/start.json Request example: curl -i -X POST -u user:userpass http://onapp.test/sysadmin_tools/daemon/start.xml 'Accept: application/xml' -H 'Content-type: application/xml' Response example: <?xml version="1.0" encoding="UTF-8"?> <daemon> <status>Online</status> </daemon> 41.2 Stop background task daemon To stop background task daemon: POST /sysadmin_tools/daemon/stop.xml POST /sysadmin_tools/daemon/stop.json Request example: curl -i -X POST -u user:userpass http://onapp.test/sysadmin_tools/daemon/stop.xml 'Accept: application/xml' -H 'Content-type: application/xml' Response example: <?xml version="1.0" encoding="UTF-8"?> <daemon> <status>Offline</status> </daemon> 296 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 41.3 Reload background task daemon To reload a background task daemon: POST /sysadmin_tools/daemon/reload.xml POST /sysadmin_tools/daemon/reload.json Request example: curl -i -X POST -u user:userpass http://onapp.test/sysadmin_tools/daemon/reload.xml -H 'Accept: application/xml' -H 'Content-type: application/xml' Response example: <?xml version="1.0" encoding="UTF-8"?> <daemon> <status>OK</status> </daemon> 41.4 Get background task daemon status To get backgrounbd task daemon status: GET /sysadmin_tools/status.xml GET /sysadmin_tools/status.json Request example: curl -i -X GET -u user:userpass http://onapp.test/sysadmin_tools/daemon/status.xml -H 'Accept: application/xml' -H 'Content-type: application/xml' Response example: <?xml version="1.0" encoding="UTF-8"?> <daemon> <status>Online</status> </daemon> 297 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 42. Transactions This class represents all the operations happening in your cloud, such as VM provisioning, OS configuring, VM start up, operations with disks, and so on. 42.1 Get the list of transactions GET GET /transactions.xml /transactions.json XML Output example: <?xml version="1.0" encoding="UTF-8"?> <transactions type="array"> <transaction> <pid type="integer">2632</pid> <created_at type="datetime">2011-07-20T08:28:54Z</created_at> <start_after type="datetime">2011-07-20T08:28:54Z</start_after> <updated_at type="datetime">2011-07-20T08:28:59Z</updated_at> <actor nil="true"></actor> <priority type="integer">10</priority> <parent_type>VirtualMachine</parent_type> <action>startup_virtual_machine</action> <id type="integer">1547</id> <user_id type="integer">13</user_id> <dependent_transaction_id nil="true"></dependent_transaction_id> <allowed_cancel type="boolean">true</allowed_cancel> <parent_id type="integer">34</parent_id> <started_at type="datetime">2011-07-20T08:28:56Z</started_at> <params> </params> <log_output></log_output> <status>complete</status> <identifier>huilp6uzskz8rr</identifier> </transaction> ... <transaction></transaction> ... </transactions> Where: pid — external process ID created_at — the time when the record of transaction was made in the database, in the [YYYY][MM][DD]T[hh][mm][ss]Z format start_after — the time after which the transaction may start, in the [YYYY][MM][DD]T[hh][mm][ss]Z format finished_at — reserved detail updated_at — the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format actor — reserved detail priority — priority of the transaction (reserved detail) parent_type — the type of the transaction target (virtual machine, disk, hypervisor) 298 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 action — the type of transaction performed id —transaction ID user_id —ID of the user who performed the transaction dependent_transaction_id —ID of the transaction that the current transaction depends on. For independent transactions this remains empty. allowed_cancel —true if cancellation is allowed. Otherwise false. parent_id — ID of the target VM, disk or hypervisor started_at —time when the transaction was started, in the the [YYYY][MM][DD]T[hh][mm][ss]Z format params —parameters of the transaction log_output —an array with log output details status —status of the transaction (complete, failed, pending, etc) identifier —identifier of the virtual machine 42.2 Get the list of a VM’s transactions GET GET /virtual_machines/:virtual_machine_id/transactions.xml /virtual_machines/:virtual_machine_id/transactions.json XML Output example <?xml version="1.0" encoding="UTF-8"?> <transactions type="array"> <transaction> <pid type="integer">2632</pid> <created_at type="datetime">2011-07-20T08:28:54Z</created_at> <start_after type="datetime">2011-07-20T08:28:54Z</start_after> <updated_at type="datetime">2011-07-20T08:28:59Z</updated_at> <actor nil="true"></actor> <priority type="integer">10</priority> <parent_type>VirtualMachine</parent_type> <action>startup_virtual_machine</action> <id type="integer">1547</id> <user_id type="integer">13</user_id> <dependent_transaction_id nil="true"></dependent_transaction_id> <allowed_cancel type="boolean">true</allowed_cancel> <parent_id type="integer">34</parent_id> <started_at type="datetime">2011-07-20T08:28:56Z</started_at> <params> </params> <log_output></log_output> <status>complete</status> <identifier>huilp6uzskz8rr</identifier> </transaction> ... <transaction></transaction> ... </transactions> Where: pid — external process ID 299 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 created_at — the time when the record of transaction was made in the database, in the [YYYY][MM][DD]T[hh][mm][ss]Z format start_after — the time after which the transaction may start, in the [YYYY][MM][DD]T[hh][mm][ss]Z format finished_at — reserved detail updated_at — the date in the [YYYY][MM][DD]T[hh][mm][ss]Z format actor — reserved detail priority — priority of the transaction (reserved detail) parent_type — type of the transaction target (virtual machine, disk, hypervisor) action — the type of transaction performed id —transaction ID user_id —ID of the user who performed the transaction dependent_transaction_id —ID of the transaction that the current transaction depends on. For independent transactions this remains empty. allowed_cancel —true if cancellation is allowed. Otherwise false. parent_id — ID of the target VM, disk or hypervisor started_at —time when the transaction was started in the the [YYYY][MM][DD]T[hh][mm][ss]Z format params —parameters of the transaction log_output —an array with log output details status —status of the transaction (complete, failed, pending, etc) identifier —identifier of the virtual machine 42.3 Get a particular transaction’s details GET GET /transactions/:id.xml /transactions/:id.json For details refer to the Get the list of transactions section. 300 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 43. Logs OnApp logs all cloud management actions that take place on cloud resources, including virtual machines, disks, data stores, hypervisors, templates and networks, as well as alerts and notifications. 43.1 Get the list of log items GET GET /logs.xml /logs.json XML Output example <?xml version="1.0" encoding="UTF-8"?> <log_items type="array"> <log_item> <created_at type="datetime">2011-07-25T15:26:44+07:00</created_at> <target_id type="integer">22386</target_id> <updated_at type="datetime">2011-07-25T15:26:44+07:00</updated_at> <id type="integer">22903</id> <target_type>Transaction</target_type> <status>Complete</status> <action>RebootVirtualMachine</action> </log_item> ... <log_item></log_item> ... </log_items> Where: created_at – time in the [YYYY][MM][DD]T[hh][mm][ss]Z format updated_at – time in the [YYYY][MM][DD]T[hh][mm][ss]Z format id – log item ID target_id – ID of the transaction (item in the transaction list. See Get the list of transaction) target_type – type of log item (either Transaction or Alert). action - the action name status - the action status (Complete, Warn, Pending, or Failed) 43.2 Get log item details GET GET /logs/:id.xml /logs/:id.json XML Output example <?xml version="1.0" encoding="UTF-8"?> <log_item> <created_at type="datetime">2011-07-25T15:26:44+07:00</created_at> 301 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 <target_id type="integer">22386</target_id> <updated_at type="datetime">2011-07-25T15:26:44+07:00</updated_at> <id type="integer">22903</id> <target_type>Transaction</target_type> <status>Complete</status> <action>RebootVirtualMachine</action> </log_item> For details refer to Get the list of log items. 302 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 44. System configuration Lists the configuration settings of your OnApp installation. 44.1 View system configuration To see all the system configuration, use the following request: GET GET /settings/configuration.xml /settings/configuration.json XML Output example <?xml version="1.0" encoding="UTF-8"?> <settings> <use_ssh_file_transfer type="boolean">true</use_ssh_file_transfer> <ssh_file_transfer_server>IP ADDRESS</ssh_file_transfer_server> <ssh_file_transfer_user>root</ssh_file_transfer_user> <ssh_file_transfer_options>-o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -o PasswordAuthentication=no</ssh_file_transfer_options> <template_path>/onapp/templates</template_path> <backups_path>/onapp/backups</backups_path> <update_server_url>http://repo.onapp.com/</update_server_url> <license_key>NNNN-NNNNN-NNNNN-NNNNN-NNNNN-NNNNN</license_key> <generate_comment># Automatically generated by OnApp (2.3.0-21)</generate_comment> <simultaneous_backups type="integer">2</simultaneous_backups> <simultaneous_backups_per_datastore type="integer">2</simultaneous_backups_per_datastore> <simultaneous_backups_per_hypervisor type="integer">1</simultaneous_backups_per_hypervisor> <simultaneous_transactions type="integer">3</simultaneous_transactions> <remote_access_session_start_port type="integer">30000</remote_access_session_start_port> <remote_access_session_last_port type="integer">30099</remote_access_session_last_port> <system_email>[email protected]</system_email> <ajax_power_update_time type="integer">8000</ajax_power_update_time> <ajax_pagination_update_time type="integer">9000</ajax_pagination_update_time> <hypervisor_live_times type="integer">12</hypervisor_live_times> <cpu_guarantee type="boolean">false</cpu_guarantee> <system_host>onapp.com</system_host> <system_notification type="boolean">true</system_notification> <system_support_email>[email protected]</system_support_email> <recovery_templates_path>/onapp/tools/recovery</recovery_templates_path> <remove_backups_on_destroy_vm type="boolean">true</remove_backups_on_destroy_vm> <disable_hypervisor_failover type="boolean">false</disable_hypervisor_failover> <ips_allowed_for_login nil="true"></ips_allowed_for_login> <monitis_path>/usr/local/monitis</monitis_path> <monitis_account>MONITIS ACCOUNT</monitis_account> <monitis_apikey>111111111nnnnnnnnnnNNN</monitis_apikey> <locales type="array"> <locale>en</locale> </locales> <virtual_machines_per_page type="integer">10</virtual_machines_per_page> <hypervisors_per_page type="integer">10</hypervisors_per_page> <logs_per_page type="integer">10</logs_per_page> <templates_per_page type="integer">10</templates_per_page> 303 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 <network_ip_addresses_per_page type="integer">10</network_ip_addresses_per_page> <billing_plans_per_page type="integer">10</billing_plans_per_page> <permissions_per_page type="integer">25</permissions_per_page> <disks_per_page type="integer">10</disks_per_page> <schedules_per_page type="integer">10</schedules_per_page> <transactions_per_page type="integer">10</transactions_per_page> <default_vm_os>Linux</default_vm_os> <default_vm_template type="integer">0</default_vm_template> <default_firewall_policy>ACCEPT</default_firewall_policy> <app_name>OnApp</app_name> <show_ip_address_selection_for_new_vm type="boolean">true</show_ip_address_selection_for_new_vm> <backup_taker_delay type="integer">5</backup_taker_delay> <billing_stat_updater_delay type="integer">5</billing_stat_updater_delay> <cluster_monitor_delay type="integer">15</cluster_monitor_delay> <hypervisor_monitor_delay type="integer">5</hypervisor_monitor_delay> <schedule_runner_delay type="integer">5</schedule_runner_delay> <transaction_runner_delay type="integer">5</transaction_runner_delay> </settings> Where: use_ssh_file_transfer - set true to allow secure file access, transfer and management to a remote server ssh_file_transfer_server - the address of the remote server ssh_file_transfer_user - the login used for remote server authentication. A password is not required, as it is required that you store a host key ssh_file_transfer_options - SSH protocol options that set the rules and behavior of how to log into the remote server template_path - path to the directory where templates will be stored backups_path - path to the directory where backups will be stored update_server_url - URL address where OnApp software updates are downloaded from license_key - license key of your OnApp CP generate_comment - this text is added by OnApp to system configuration files, such as resolv.conf simultaneous_backups - the maximum allowed number of simultaneous hypervisor and data store backup processes simultaneous_backups_per_datastore - the maximum number of simultaneous data store backup processes simultaneous_backups_per_hypervisor - the maximum number of simultaneous hypervisor backup processes 304 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 simultaneous_transactions - the number of transaction runners which the daemon will execute at the same time remote_access_session_start_port - the first port in the range, which are used to remotely connect to virtual machines using the integrated VNC console remote_access_session_last_port - the last port in the range, which are used to remotely connect to virtual machines using the integrated VNC console system_email - the email address from which help requests and email alerts are sent ajax_power_update_time - how often VM status is refreshed on the Virtual Machines screen in ms ajax_pagination_update_time - how often the dashboard, logs and other items are refreshed in ms hypervisor_live_times - determines how many times the Control Panel server will attempt to contact a hypervisor before failover is initiated cpu_guarantee - if true, the system will make sure there is enough CPU on the cloud to create a new VM system_host –the system host server IP or URL; email alerts link to transaction logs for alert events, and those logs are opened from the server configured here system_notification - set true to enable email alerts system_support_email - the email address to which the system will send alerts about failed transactions and change of hypervisor status recovery_templates_path - path to the directory where recovery templates will be stored remove_backups_on_destroy_vm - set true to remove all VM backups after this VM was deleted disable_hypervisor_failover - true, if hypervisor failover will not initiate after meeting the value of the hypervisor_live_times parameter ips_allowed_for_login - list of IP addresses allowed for login to OnApp CP monitis_path - path to the directory where Monitis client (to enable autoscale) will be installed monitis_account - name of the Monitis account monitis_apikey - API key to access the Monitis account locales - an array of locals (the locale code) available for the users virtual_machines_per_page - number of virtual machines displayed per page hypervisors_per_page - number of hypervisors displayed per page 305 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 logs_per_page - number of logs displayed per page templates_per_page - number of templates displayed per page network_ip_addresses_per_page - number of IP addresses displayed per page billing_plans_per_page - number of billing plans displayed per page permissions_per_page - number of permissions displayed per page disks_per_page - number of disks displayed per page schedules_per_page - number of schedules displayed per page transactions_per_page - number of transactions displayed per page default_vm_os - default OS to create a new VM default_vm_template - default VM template to create a new virtual machine default_firewall_policy - default firewall policy for all VMs (unless set otherwise for a particular VM) app_name - application name displayed on the login screen show_ip_address_selection_for_new_vm - set true to enable IP address assignment during VM creation backup_taker_delay - frequency in seconds for launching the Backup Taker task billing_stat_updater_delay - frequency in seconds for launching the Billing Stats Monitor task cluster_monitor_delay - frequency in seconds for launching the Cluster Monitor task hypervisor_monitor_delay - frequency in seconds for launching the Hypervisor Monitor task schedule_runner_delay - frequency in seconds for launching the Schedule Runner task transaction_runner_delay - frequency in seconds for launching the Transaction Runner task 306 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 45. Version To check the version of your cloud installation, use the following request: GET GET /version.xml /version.json XML Output example <?xml version="1.0" encoding="UTF-8"?> <onapp> <version>2.2 </version> </onapp> Json Output example {"version":"2.2"} 307 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 46. Document revisions v1.7, 21st November 2012 • Corrected View Bandwidth Statistics API requests. v1.6, 27th June 2012 • Removed deprecated password confirmation parameter, and and added a note about API key to the Create a user & Edit a user sections. v1.5, 12th April 2012 Added: • • • • • • • • • • • • • • • Created separate License section. New billing plan limit for data store and network zones Backup server zones chapter Backup servers chapter Add limits for backup server zones section Get backup server zone resource details section DNS setup chapter DNS zone chapter Apply a Firewall rule section Background task daemon chapter User additional fields chapter Documentation conventions section. View user's statistics for a particular period section Added CDN usage statistics chapterAdded Enable CDN section to the CDN Resources chapter Added View billing statistics for a resource section Updated: • • • • • • • • • Updated incorrect Create CDN Edge Group API request API output examples in Get backup server details and Search backups sections API calls in Billing plans chapter Deleted an IP address join section Edit a role and Add a new role sections with the correct parameters API calls in Convert a backup to a template section Load Balancers section with the latest parameters Create a VM section adds info on new Windows licensing type Changed CPU share parameter to CPU priority 308 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 • • • • • • • • • • • • • • Get the list of backups available for a disk section Get the list of system templates section Get the list of VM backups section Hypervisors chapter with the latest parameters Create a virtual machine section with the info on setting data store zone for primary and swap disks The Currencies chapter with the precision_for_unit parameter Added label description in Create edge server section Added additional fields array in XML output in Get the list of users section Edited XML and JSON request examples in Create a user and Edit a user sections Edited XML Output example in View CDN resource advanced details section Corrected Reboot a hypervisor XML request example. View user's statistics section Updated Logs chapter with the new parameters Updated Edit a hypervisor zone section V1.4, 12th January 2012 • Corrected a typo in xml for Add a payment and Edit a payment sections (</payment>, not </payments> V1.3, 8th December 2011 • • Added o Get the list of data store joins attached to the hypervisor section o Add a data store join to the hypervisor o Remove a data store join from the hypervisor o Get the list of network joins of the hypervisor o Add a network join to the hypervisor o Remove a network join from the hypervisor o System configuration chapter o View a CDN resource advanced details o Create a CDN resource with advanced settings o Edit CDN resource advanced settings Updated o Edit a VM, Resize a VM, Create autoscaling rule for a VM with the info on setting cold resize o Get the list of hypervisors, Get the list of unassigned hypervisors, Get hypervisor details, Add a new hypervisor, and Edit a hypervisor sections with the latest parameters. o Removed redundant parameters from View CDN edge group details section o Corrected request for Delete a payment section 309 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 V1.2, 14th November 2011 • Added o o o o o o o o o o o o o o o o o o o o CDN Resources chapter. Migrate edge server section. Open the server console section. Segregate edge server section. Reset root password section. Change edge server owner section. Set VIP status section. Edit admin note section. Billing statistics for CDN edge server section. CDN edge server backups section. CDN edge server network interfaces section. IP address joins section. Firewall rules for CDN edge servers section. Reboot in recovery section. Create CDN edge group section. Edit CDN edge group section. Delete CDN edge group section. Assign location to the group section. Unassign location from the group section. Add limits for edge groups section • Updated: o View CDN edge group details section. o View billing statistics for a user section o parameters for Get the list of system templates and Get the template details sections o output example and parameters description for Get the list of VMs section o output example and parameters description for Get the list of users section o error codes returned when you Edit a VM • Replaced Add disk to edge server, Resize edge server disk and Delete edge server disk sections with CDN edge server disks section. v1.1, 14th October 2011 • Added: o CDN Edge Servers chapter o CDN Edge Groups chapter o Delete a template section 310 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012 v1.0, 3rd October 2011 • Added: o SSH keys chapter. o Migrate a disk section. o Get the list of VMs running on the hypervisor section. o Set VIP status section. o Reboot in recovery section. o Set SSH keys section. o Rebuild VM network section. o Add nodes to cluster type section. o Remove nodes from cluster type section. o Configure autoscaling type section. o Rebuild a load balancer section. o Attach/remove a hypervisor from a hypervisor zone section. o See user limits section. • Updated o Add base resources to a billing plan section. Now it consists of the following subsections: Add Virtual Machines base resource limits, Add other base resource limits, Add limits for template groups and hypervisor zones, Add limits for data store zones and Add limits for network zones. o Add a load balancing cluster section. o Create a user and Create a VM sections now contain password validation requirements. o Edit a user group section contains both XML and JSON request examples. o Delete a user group section contains both XML and JSON request examples. o Get the list of hypervisors section contains updated XML output example and parameters description. o Attach a template to a group section contains both XML and JSON request examples. o Detach a template from a group section contains both XML and JSON request examples. o Make a template public section updated with both XML and JSON request examples. Cosmetic changes. Other detail is unchanged from v 1.1 of the API Guide for OnApp 2.2 • • 311 st OnApp Cloud 2.3.2 | API Guide | v1.7 | 21 November 2012
* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project
advertisement
© 2021