Last updated September 24, 2009 20:28, by Craig McClanahan
Feedicon  

Cloud API Specification - Requests to VM Resources

The requests documented in this section are directed to VM resources, which represent virtual machines.


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.

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 Creative Commons Attribution 3.0 Unported License

  • Mysql
  • Glassfish
  • Jruby
  • Rails
  • Nblogo
Terms of Use; Privacy Policy;
© 2013, Oracle Corporation and/or its affiliates
(revision 20131025.e7cbc9d)
 
 
Close
loading
Please Confirm
Close