Jump to Page:

The APIs for the Sun Cloud was started in February 2009, is owned by russcastronovo, and has 233 members.

» Join This Project

Last updated August 20, 2009 23:17, by Tim Bray

Cloud API Specification - Requests to Cluster Resources

The requests documented in this section are directed to Cluster resources, which represent sets of virtual machines and private networks.

Contents

1 Get Cluster
2 Update Cluster Properties
3 Delete Cluster
4 Create VM
5 Create VNet
6 Create Cluster
7 Control Cluster

Get Cluster

Retrieve information about a specific cluster.

Synopsis: GET {URI of Cluster from representation of containing VDC}

Request Headers: Accept, Authorization, X-Cloud-Client-Specification-Version.

Request Message Body: N/A.

Response Headers: Content-Length, Content-Type.

Response Message Body: Cluster.

Response Status: 200, 400, 401, 403, 404.

Example Request: Retrieve information about a Cluster instance named "Staging WebTier".

 GET /clusters/123456
 Host: example.com
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Accept: application/vnd.com.sun.cloud.Cluster+json
 X-Cloud-Client-Specification-Version: 0.1

Example Response:

 HTTP/1.1 200 OK
 Content-Type: application/vnd.com.sun.cloud.Cluster+json
 Content-Length: nnn
 
 {
   "name": "Staging Web Tier",
   "uri" : "http://example.com/clusters/123456",
   "tags" : [ "staging" ],
   "vms": [
     { "name" : "web01", "uri" : "http://example.com/vms/0003", ... },
     ...
   ],
   "controllers" : {
      "halt" : "http://example.com/cluster/halt?cluster=123456",
   }
 }

Update Cluster Properties

Update an existing Cluster definition based on the fields actually present in the request message body.

Synopsis: PUT { URI of Cluster }

Request Headers: Accept, Authorization, Content-Length, Content-Type, X-Cloud-Client-Specification-Version.

Request Parameters: N/A.

Request Message Body: Cluster containing fields to update properties.

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-Cluster".

Status "target_uri" identifies: The cluster receiving the PUT.

Example Request: Add a tag on an existing Cluster named Production Web Tier.

 PUT /clusters/654321
 Host: example.com
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Accept: application/vnd.com.sun.cloud.Cluster+json
 Content-Length: nnn
 Content-Type: application/vnd.com.sun.cloud.Cluster+json
 X-Cloud-Client-Specification-Version: 0.1
 
 {
   tags : [ "production", "monitoring" ]
 }

Example 1 Response:

 HTTP/1.1 202 Accepted
 Content-Type: application/vnd.com.sun.cloud.Status+json
 Content-Length: nnn
 
 {
   "op": "update-Cluster",
   "progress": 100,
   "target_uri": "/clusters/654321",
   "status_uri": "/statuses?op=update-cluster&seq=3552354232",
   "status" : 200
 }

Delete Cluster

Delete an existing cluster and all of its subordinate resources.

Synopsis: DELETE { URI of Cluster }

Request Headers: Authorization, X-Cloud-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-Cluster".

Status "target_uri" identifies: The cluster being deleted.

Example Request: Delete an existing cluster named Staging Web Tier.

 DELETE /clusters/123456
 Host: example.com
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 X-Cloud-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-Cluster",
   "progress": 100,
   "target_uri": "/clusters/123456",
   "status_uri": "/statuses?op=delete-cluster&cluster=123456",
   "status" : 200
 }

Create VM

Create a new VM associated with this Cluster. You can optionally specify the URI of a VM template or an existing VM as a basis of default values. The request is a POST of a VM representation, whose Media-Type MUST be "application/vnd.com.sun.cloud.VM+json".

Synopsis: POST { URI of Cluster }

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 VM creation progress.

Response Status: 202, 400, 401, 403, 404.

Status "op" Value: "new-VM".

Status "target_uri" identifies: The URI of the new VM once it is created.

Example 1 Request: Create a new VM named "web01".

 POST /clusters/cluster=123456
 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
 
 {
   "name" : "web01"
   "description" : "This is the old description"
   ... all the characteristics of a VM ...
 }

Example 1 Response:

 HTTP/1.1 202 Accepted
 Content-Type: application/vnd.com.sun.cloud.Status+json
 Content-Length: nnn
 
 {
   "op": "new-VM",
   "progress": 0,
   "target_uri": "/vms?cluster=123456&vm=web01",
   "status_uri": "/statuses?op=new-VM&cluster=123456&name=web01",
 }

Example 2 Request: Create a new VM named "web02" based on a VM Template but set the data disk size to 100gb.

 POST /clusters/cluster=123456
 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
 
 {
   "name" : "web02"
   "from_template": "http://example.com/templates/xyz",
   "data_disk" : 100
 }

Example 2 Response:

 HTTP/1.1 202 Accepted
 Content-Type: application/vnd.com.sun.cloud.Status+json
 Content-Length: nnn
 
 {
   "op": "new-VM",
   "progress": 100,
   "target_uri": "/vms?cluster=123456&vm=web02",
   "status_uri": "/statuses?op=new-VM&cluster=123456&name=web02",
   "status": 201
 }

Example 3 Request: Create a new VM named "web03" based on existing VM "web01".

 POST /clusters/cluster=123456
 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
 
 {
   "name" : "web03"
   "from_vm": "http://example.com/vms/33333"
 }

Example 3 Response:

 HTTP/1.1 202 Accepted
 Content-Type: application/vnd.com.sun.cloud.Status+json
 Content-Length: nnn
 
 {
   "op": "new-VM",
   "progress": 0,
   "target_uri": "/vms?cluster=123456&vm=web03",
   "status_uri": "/statuses?op=new-VM&cluster=123456&name=web03",
 }

Create VNet

Request the creation of a new VNet for use in this Cluster. Most of the fields of a VNet resource are automatically set in the course of its use; the only field required at creation time is its logical name. The request is a POST to the URI of the Cluster; the Content-Type MUST be "application/vnd.com.sun.cloud.VNet+json"

Synopsis: POST { URI of Cluster }

Request Headers: Accept, Authorization, Content-Length, Content-Type, X-Cloud-Client-Specification-Version.

Request Parameters: N/A.

Request Message Body: VNet.

Response Headers: Content-Length, Content-Type.

Response Message Body: Status for use in tracking VNet-creation progress.

Response Status: 202, 400, 401, 403, 404.

Status "op" Value: "new-VNet".

Status "target_uri" identifies: The URI of the new VNet once it is created.

Example 2 Request: Create a new VNet named Front End which will be used to connect the web tier and application tier clusters.

 POST /clusters/c~32425tt6231
 Host: example.com
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Accept: application/vnd.com.sun.cloud.VNet+json
 Content-Length: nnn
 Content-Type: application/vnd.com.sun.cloud.VNet+json
 X-Cloud-Client-Specification-Version: 0.1
 
 {
   "name" : "Front End",
   "tags" : [ "webtier", "apptier" ]
 }

Example Response:

 HTTP/1.1 202 Accepted
 Content-Type: application/vnd.com.sun.cloud.Status+json
 Content-Length: nnn
 
 {
   "op": "new-VNet",
   "progress": 0,
   "target_uri": "/vnets/SFMCO**x",
   "status_uri": "/statuses?op=new-vnet&seq=9983711",
 }

Create Cluster

Create a new cluster, within this cluster, based on the request message body representation. There are two options for defining the complete configuration of the new cluster:

Specify only the name of the new cluster, and any related values.
Specify the name of the new cluster, the name of an existing cluster (in the from_cluster field) from which to clone the current set of related resources, and any additional values to override those copied from the original cluster.

The request is a POST to the URI of the Cluster; the Content-Type MUST be "application/vnd.com.sun.cloud.Cluster+json"

Synopsis: POST { URI of Cluster }

Request Headers: Accept, Authorization, Content-Length, Content-Type, X-Cloud-Client-Specification-Version.

Request Parameters: N/A.

Request Message Body: A Cluster resource model representing all of the required values, or only those that override an existing cluster as a source of default values.

Response Headers: Content-Length, Content-Type.

Response Message Body: Status for use in tracking cluster-creation progress.

Response Status: 202, 400, 401, 403, 404.

Status "op" Value: "new-Cluster".

Status "target_uri" identifies: The URI of the new Cluster once it is created.

Example 1 Request: Create a new empty cluster named Staging Web Tier.

 POST /vdcs/clusters?id=13589fj92h92f
 Host: example.com
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Accept: application/vnd.com.sun.cloud.Cluster+json
 Content-Length: nnn
 Content-Type: application/vnd.com.sun.cloud.Cluster+json
 X-Cloud-Client-Specification-Version: 0.1
 
 {
   "name" : "Staging Web Tier",
   "tags" : [ "staging" ]
 }

Example 1 Response:

 HTTP/1.1 202 Accepted
 Content-Type: application/vnd.com.sun.cloud.Status+json
 Content-Length: nnn
 
 {
   "op": "new-Cluster",
   "progress": 0,
   "target_uri": "http://example.com/clusters/123456",
   "status_uri": "/statuses?op=new-cluster&parent=13589fj92h92f",
 }

Example 2 Request: Create a new cluster named Production Web Tier, cloned from "Staging Web Tier" after the resources for that tier had been built up and tested.

 POST /clusters?id=03AB3FF
 Host: example.com
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Accept: application/vnd.com.sun.cloud.Cluster+json
 Content-Length: nnn
 Content-Type: application/vnd.com.sun.cloud.Cluster+json
 X-Cloud-Client-Specification-Version: 0.1
 
 {
   "name" : "Production Web Tier",
   "from_cluster" : "Staging Web Tier",
   "tags" : [ "production" ]
 }

Example 2 Response:

 HTTP/1.1 202 Accepted
 Content-Type: application/vnd.com.sun.cloud.Status+json
 Content-Length: nnn
 
 {
   "op": "new-Cluster",
   "progress": 0,
   "target_uri": "http://example.com/clusters/654321",
   "status_uri": "/statuses/209382tuy2-3t942"
 }

Control Cluster

A Cluster 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 Cluster will be included. A client application requests a state change by doing a POST to the correponding 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 Cluster 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-Cluster" or "stop-Cluster".

Status "target_uri" identifies: The cluster receiving the request.

Example Request: Start all VMs in Cluster.

 POST /cluster/start?name=123456
 Host: example.com
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Content-Length: nnn
 Content-Type: application/json
 X-Cloud-Client-Specification-Version: 0.1
 
 {
   "note": "Start testbed per Friday meeting"
 }

Example Response:

 HTTP/1.1 202 Accepted
 Content-Type: application/vnd.com.sun.cloud.Status+json
 Content-Length: nnn
 
 {
   "op": "start-Cluster",
   "progress": 38,
   "target_uri": "/cluster/name=123456",
   "status_uri": "/statuses?op=start-cluster&cluster=123456"
 }