2009-03-11T05:45:43Z

Flesh out VM backup semantics 1054 CloudAPIVMRequests 10

<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 © Sun Microsystems, 2009. This work is licensed under [http://creativecommons.org/licenses/by/3.0/ Creative Commons Attribution 3.0 Unported License]

<h1>Cloud API Specification - Requests to VM Resources</h1> The requests documented in this section are directed to VM resources, which represent virtual machines. <div id='toc' class='toc'> <div id='toctitle' class='toc-title'> Contents </div> <div id='toccontents' class='toc-contents'><ul><li>1 <a href='#Get_VM'> Get VM </a></li> <li>2 <a href='#Update_VM_Properties'> Update VM Properties </a></li> <li>3 <a href='#Delete_VM'> Delete VM </a></li> <li>4 <a href='#Attach_VM_To_Public_Address_or_VNet'> Attach VM To Public Address or VNet </a></li> <li>5 <a href='#Detach_VM_From_Public_Address_or_VNet'> Detach VM From Public Address or VNet </a></li> <li>6 <a href='#Create_VM_Backup_Snapshot'> Create VM Backup Snapshot </a></li> <li>7 <a href='#Control_VM'> Control VM </a></li> </ul></div> </div> <h1><a name='Get_VM'></a> Get VM </h1> 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". <pre> GET /vms/33333 Host: example.com Authorization: Basic xxxxxxxxxxxxxxxxxxx Accept: application/vnd.com.sun.cloud.VM+json X-Cloud-Client-Specification-Version: 0.1 </pre>Example Response: <pre> HTTP/1.1 200 OK Content-Type: application/vnd.com.sun.cloud.VM+json Content-Length: nnn { "name" : "web01", "uri" : "<a class='external' href="http://example.com/vms/33333">http://example.com/vms/33333</a>" "run_status" : "STARTED", "description" : "This is the old description" ... "back_up" : "<a class='external' href="http://example.com/back-up?vm=33333">http://example.com/back-up?vm=33333</a>" "attach" : "<a class='external' href="http://example.com/attach?vm=33333">http://example.com/attach?vm=33333</a>", "detach" : "<a class='external' href="http://example.com/detach-ip?vm=33333">http://example.com/detach-ip?vm=33333</a>", ... } </pre><h1><a name='Update_VM_Properties'></a> Update VM Properties </h1> 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. <pre> 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" } </pre>Example Response: <pre> 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 } </pre><h1><a name='Delete_VM'></a> Delete VM </h1> 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". <pre> DELETE /vdcs/MyStore/vms/AppTier Host: example.com Authorization: Basic xxxxxxxxxxxxxxxxxxx X-Compute-Client-Specification-Version: 0.1 </pre>Example Response: <pre> 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*" } </pre><h1><a name='Attach_VM_To_Public_Address_or_VNet'></a> Attach VM To Public Address or VNet </h1> 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". <pre> 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" : "<a class='external' href="http://example.com/addresses/107.236.66.83">http://example.com/addresses/107.236.66.83</a>" } </pre>Example 1 Response: <pre> 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" } </pre>Example 2 Request: Attach VM "web01" to VNet "Front End". <pre> 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" : "<a class='external' href="http://example.com/vnets/abcdefg">http://example.com/vnets/abcdefg</a>" } </pre>Example 2 Response: <pre> 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 } </pre><h1><a name='Detach_VM_From_Public_Address_or_VNet'></a> Detach VM From Public Address or VNet </h1> 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". <pre> 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" : "<a class='external' href="http://example.com/addresses/107.236.66.83">http://example.com/addresses/107.236.66.83</a>" } </pre>Example 1 Response: <pre> 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 } </pre>Example 2 Request: Detach VM "web01" from VNet "Front End". <pre> 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" : "<a class='external' href="http://example.com/vnets/abcdefg">http://example.com/vnets/abcdefg</a>" } </pre>Example 2 Response: <pre> 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" } </pre><h1><a name='Create_VM_Backup_Snapshot'></a> Create VM Backup Snapshot </h1> 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". <pre> 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" } </pre>Example Response: <pre> 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" } </pre><h1><a name='Control_VM'></a> Control VM </h1> 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. <pre> 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" } </pre>Example Response: <pre> 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" } </pre> Here is a table describing the effects and usage of the available control URIs. <div style="overflow-x: auto;"><div style="margin: 0px 2px 0px 2px;"> <table - border="1" width="100%"><tr><th> Change Type </th><th> Start State </th><th> Transitional State </th><th> Transitional State </th><th> Transitional State </th><th> Destination State </th></tr> <tr><td> start </td><td> STOPPED </td><td> STARTING </td><td></td><td></td><td> STARTED </td></tr> <tr><td> stop </td><td> STARTED </td><td> STOPPING </td><td></td><td></td><td> STOPPED </td></tr> <tr><td> reboot </td><td> STARTED </td><td> STOPPING </td><td> STOPPED </td><td> STARTING </td><td> STARTED </td></tr> <tr><td> hibernate </td><td> STARTED </td><td> SLEEPING </td><td></td><td></td><td> ASLEEP </td></tr> <tr><td> resume </td><td> ASLEEP </td><td> WAKING </td><td></td><td></td><td> STARTED </td></tr> </table> </div></div> Copyright © Sun Microsystems, 2009. This work is licensed under <a class='external' href="http://creativecommons.org/licenses/by/3.0/">Creative Commons Attribution 3.0 Unported License</a>

2009-09-24T20:28:39Z

3636