<h1>Cloud API Specification - Requests to VM Resources</h1> The requests documented in this section are directed to ''VM'' resources, which represent virtual machines. __TOC__ = Get VM = Retrieve information about a specific VM associated with a specified Cluster. '''Synopsis:''' GET {URI of VM from the owning Cluster} '''Request Headers:''' Accept, Authorization, X-Cloud-Client-Specification-Version. '''Request Message Body:''' N/A. '''Response Headers:''' Content-Length, Content-Type. '''Response Message Body:''' VM. '''Response Status:''' 200, 400, 401, 403, 404. '''Example Request:''' Retrieve information about a VM instance "web01". GET /vms/33333 Host: example.com Authorization: Basic xxxxxxxxxxxxxxxxxxx Accept: application/vnd.com.sun.cloud.VM+json X-Cloud-Client-Specification-Version: 0.1 '''Example Response:''' HTTP/1.1 200 OK Content-Type: application/vnd.com.sun.cloud.VM+json Content-Length: nnn { "name" : "web01", "uri" : "http://example.com/vms/33333" "run_status" : "STARTED", "description" : "This is the old description" ... "back_up" : "http://example.com/back-up?vm=33333" "attach" : "http://example.com/attach?vm=33333", "detach" : "http://example.com/detach-ip?vm=33333", ... } = Update VM Properties = Update an existing virtual machine definition. '''Synopsis:''' PUT { URI of VM } '''Request Headers:''' Accept, Authorization, Content-Length, Content-Type, X-Cloud-Client-Specification-Version. '''Request Parameters:''' N/A. '''Request Message Body:''' VM. '''Response Headers:''' Content-Length, Content-Type. '''Response Message Body:''' Status for use in tracking update progress. '''Response Status:''' 202, 400, 401, 403, 404. '''Status "op" Value:''' "update-VM". '''Status "target_uri" identifies:''' The VM receiving the PUT. '''Example Request:''' Update an existing VM named "web01" by modifying its description. PUT /vms/33333 Host: example.com Authorization: Basic xxxxxxxxxxxxxxxxxxx Accept: application/vnd.com.sun.cloud.VM+json Content-Length: nnn Content-Type: application/vnd.com.sun.cloud.VM+json X-Cloud-Client-Specification-Version: 0.1 { "description" : "This is the new description" } '''Example Response:''' HTTP/1.1 202 Accepted Content-Type: application/vnd.com.sun.cloud.Status+json Content-Length: nnn { "op": "update-VM", "progress": 100, "target_uri": "/vms/33333", "status_uri": "/statuses?op=update-vm&seq=912874502", "status" : 200 } = Delete VM = Delete an existing virtual machine currently associated with the specified virtual private data center. '''Synopsis:''' DELETE { URI of VM } '''Request Headers:''' Authorization, X-Compute-Client-Specification-Version. '''Request Parameters:''' N/A. '''Request Message Body:''' N/A. '''Response Headers:''' Content-Length, Content-Type. '''Response Message Body:''' Status for use in tracking deletion progress. '''Response Status:''' 202, 400, 401, 403, 404. '''Status "op" Value:''' "delete-VM". '''Status "target_uri" identifies:''' The VM being deleted. '''Example Request:''' Delete an existing VM named "AppTier" from an existing VDC named "MyStore". DELETE /vdcs/MyStore/vms/AppTier Host: example.com Authorization: Basic xxxxxxxxxxxxxxxxxxx X-Compute-Client-Specification-Version: 0.1 '''Example Response:''' HTTP/1.1 202 Accepted Content-Type: application/vnd.com.sun.cloud.Status+json Content-Length: nnn { "op": "delete-VM", "progress": 0, "target_uri": "/vdcs/MyStore/vms/AppTier", "status_uri": "/statuses?op=delete-vm&vm=00eAA.f*" } = Attach VM To Public Address or VNet = Attach the specified VM to a Public Address or VNet, depending on the media type of the included representation. '''Synopsis:''' POST { VM's attach URI } '''Request Headers:''' Authorization, Content-Length, Content-Type, X-Cloud-Client-Specification-Version. '''Request Parameters:''' N/A. '''Request Message Body:''' Public Address or VNet resource model. Only the "uri" element of this resource model '''MUST''' be included. '''Response Headers:''' Content-Length, Content-Type. '''Response Message Body:''' Status for use in tracking attachment progress. '''Response Status:''' 202, 400, 401, 403, 404. '''Status "op" Value:''' "attach". '''Status "target_uri" identifies:''' The VM being attached to. '''Example 1 Request:''' Attach VM "web01" to Public Address "Load Balanced". POST /attach?vm=33333 Host: example.com Authorization: Basic xxxxxxxxxxxxxxxxxxx Content-Length: nnn Content-Type: application/vnd.com.sun.cloud.PublicAddress+json X-Cloud-Client-Specification-Version: 0.1 { "uri" : "http://example.com/addresses/107.236.66.83" } '''Example 1 Response:''' HTTP/1.1 202 Accepted Content-Type: application/vnd.com.sun.cloud.Status+json Content-Length: nnn { "op": "attach", "progress": 0, "target_uri": "/X03/VirtualMachines/F83", "status_uri": "/statuses?op=attach-public&a=107.236.66.83" } '''Example 2 Request:''' Attach VM "web01" to VNet "Front End". POST /attach?vm=33333 Host: example.com Authorization: Basic xxxxxxxxxxxxxxxxxxx Content-Length: nnn Content-Type: application/vnd.com.sun.cloud.VNet+json X-Cloud-Client-Specification-Version: 0.1 { "uri" : "http://example.com/vnets/abcdefg" } '''Example 2 Response:''' HTTP/1.1 202 Accepted Content-Type: application/vnd.com.sun.cloud.Status+json Content-Length: nnn { "op": "attach", "progress": 100, "target_uri": "/X03/VirtualMachines/F83", "status_uri": "/statuses?op=attach-public&v=abcdefg", "status": 200 } = Detach VM From Public Address or VNet = Detach the specified VM from a Public Address or VNet, depending on the media type of the included representation. '''Synopsis:''' POST { VM's detach URI } '''Request Headers:''' Authorization, Content-Length, Content-Type, X-Cloud-Client-Specification-Version. '''Request Parameters:''' N/A. '''Request Message Body:''' Public Address or VNet resource model. Only the "uri" element of this resource model '''MUST''' be included. '''Response Headers:''' Content-Length, Content-Type. '''Response Message Body:''' Status for use in tracking detachment progress. '''Response Status:''' 202, 400, 401, 403, 404. '''Status "op" Value:''' "detach". '''Status "target_uri" identifies:''' The VM being detached from. '''Example 1 Request:''' Detach VM "web01" from Public Address "Load Balanced". POST /detach?vm=33333 Host: example.com Authorization: Basic xxxxxxxxxxxxxxxxxxx Content-Length: nnn Content-Type: application/vnd.com.sun.cloud.PublicAddress+json X-Cloud-Client-Specification-Version: 0.1 { "uri" : "http://example.com/addresses/107.236.66.83" } '''Example 1 Response:''' HTTP/1.1 202 Accepted Content-Type: application/vnd.com.sun.cloud.Status+json Content-Length: nnn { "op": "detach", "progress": 100, "target_uri": "/X03/VirtualMachines/F83", "status_uri": "/statuses?op=detach&a=107.236.66.83", "status": 200 } '''Example 2 Request:''' Detach VM "web01" from VNet "Front End". POST /detach?vm=33333 Host: example.com Authorization: Basic xxxxxxxxxxxxxxxxxxx Content-Length: nnn Content-Type: application/vnd.com.sun.cloud.VNet+json X-Cloud-Client-Specification-Version: 0.1 { "uri" : "http://example.com/vnets/abcdefg" } '''Example 2 Response:''' HTTP/1.1 202 Accepted Content-Type: application/vnd.com.sun.cloud.Status+json Content-Length: nnn { "op": "detach", "progress": 0, "target_uri": "/X03/VirtualMachines/F83", "status_uri": "/statuses?op=detach&v=web01" } = Create VM Backup Snapshot = Capture a backup snapshot of this VM, based on the characteristics in this request. '''Synopsis:''' POST { VM's back_up URI } '''Request Headers:''' Authorization, Content-Length, Content-Type, X-Cloud-Client-Specification-Version. '''Request Parameters:''' N/A. '''Request Message Body:''' Backup resource model. '''Response Headers:''' Content-Length, Content-Type. '''Response Message Body:''' Status for use in tracking backup progress. '''Response Status:''' 202, 400, 401, 403, 404. '''Status "op" Value:''' "back_up". '''Status "target_uri" identifies:''' The Backup being created. '''Example Request:''' Create backup of VM "web01". POST /back_up?vm=33333 Host: example.com Authorization: Basic xxxxxxxxxxxxxxxxxxx Content-Length: nnn Content-Type: application/vnd.com.sun.cloud.Backup+json X-Cloud-Client-Specification-Version: 0.1 { "name" : "web01_backup_YYYYMMDD" } '''Example Response:''' HTTP/1.1 202 Accepted Content-Type: application/vnd.com.sun.cloud.Status+json Content-Length: nnn { "op": "back_up", "progress": 0, "target_uri": "/X03/VirtualMachines/F83/Backups/456", "status_uri": "/statuses?op=back_up&b=456" } = Control VM = A ''VM'' resource model may include one or more URIs in the ''controllers'' field, each keyed by the name of a state change being requested. Only the state changes that are legal for the current state of the VM will be included. A client application requests a state change by doing a POST to the corresponding URI, and including in the request body an arbitrary set of name/value pairs used to influence the operation of the state change. By convention, the name/value pairs included in the request may contain a field named ''note'' whose value is a text string intended for recording in a log on the server, to help identify this request during log file analysis. '''Synopsis:''' POST {URI provided in VM representation} '''Request Headers:''' Accept, Authorization, Content-Length, Content-Type, X-Cloud-Client-Specification-Version. '''Request Parameters:''' N/A. '''Request Message Body:''' Name/value pairs, with media type "application/json". '''Response Headers:''' Content-Length, Content-Type. '''Response Message Body:''' Status for use in tracking request progress. '''Response Status:''' 202, 400, 401, 403, 404. '''Status "op" Value:''' "start-VM", "stop-VM", "reboot-VM", "hibernate-VM", "resume-VM" '''Status "target_uri" identifies:''' The VM receiving the request. '''Example Request:''' Start this VM. POST /vms/33333?control=start Host: example.com Authorization: Basic xxxxxxxxxxxxxxxxxxx Content-Length: nnn Content-Type: application/json X-Compute-Client-Specification-Version: 0.1 { "note" : "Start this web tier server" } '''Example Response:''' HTTP/1.1 202 Accepted Content-Type: application/vnd.com.sun.cloud.Status+json Content-Length: nnn { "op": "start-VM", "progress": 0, "target_uri": "/vms/33333", "status_uri": "/statuses?op=start-VM&vm=33333" } Here is a table describing the effects and usage of the available control URIs. {|- border="1" width="100%" ! Change Type ! Start State ! Transitional State ! Transitional State ! Transitional State ! Destination State |- | start | STOPPED | STARTING | | | STARTED |- | stop | STARTED | STOPPING | | | STOPPED |- | reboot | STARTED | STOPPING | STOPPED | STARTING | STARTED |- | hibernate | STARTED | SLEEPING | | | ASLEEP |- | resume | ASLEEP | WAKING | | | STARTED |} Copyright &copy; Sun Microsystems, 2009. This work is licensed under [http://creativecommons.org/licenses/by/3.0/ Creative Commons Attribution 3.0 Unported License]