<h1>Cloud API Specification - Requests to Cluster Resources</h1> The requests documented in this section are directed to ''Cluster'' resources, which represent sets of virtual machines and private networks. __TOC__ = 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" } Copyright &copy; Sun Microsystems, 2009. This work is licensed under [http://creativecommons.org/licenses/by/3.0/ Creative Commons Attribution 3.0 Unported License]