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
