Last updated January 12, 2010 13:24, by Jens_Geiregat
Feedicon  

Cloud API Specification - Resource Models


This section specifies the representations of the resources which this API operates on. The representations are made up of fields, each with a name and value, encoded using a JSON dictionary. The values may be numeric or string literals, lists, or dictionaries, each of which are represented in the obvious way in JSON.

These representations typically nest. For example, the representation of a VDC will include representations of the Clusters which inhabit it, which in turn include representations of the VMs within each cluster. Two points follow from this:

  • Retrieving the representation of a VDC gives a comprehensive snapshot of the current state of everything in it using a single GET request. The size of these representations seems, in practice, not excessive.
  • Many of the models specify that the representation includes a uri field whose value is the URI of the resource being represented. This is present to support URI discovery in nested representations.

Each type of cloud resource has its own Internet Media Type. The media type SHALL conform to the pattern application/vnd.com.sun.cloud.Xxxxxxxx+json, and the specific media type for each resource model is included in square brackets in the corresponding section header.

In the resource model descriptions, fields annotated with [POST] may be included in a POST request, which is normally used to create new resources. Likewise, fields annotated with [PUT] may be included in a PUT request, which is normally used to update properties of existing resources. Fields not so annotated SHOULD NOT be included in the request body of PUT and POST requests, and will be ignored by the server if they are included.

Cloud [application/vnd.com.sun.cloud.Cloud+json]

A Cloud represents a user's view of all accessible resources in the cloud.

A "Cloud" resource model contains the following fields:

Field Name Type Occurs Description
uri URI 1 A GET against this URI refreshes the client representation of the resources accessible to this user.
locations Location[] 0..1 The set of locations for VDC deployment that are supported by this service provider.
vdcs VDC[] 0..1 Virtual data center(s) accessible to this user. Only the name and uri fields MUST be populated by the server.
specification_version String[] 1 Which version(s) of this specification this server implementation supports.
implementation_version String 1 Version of the server implementation.

Location [application/vnd.com.sun.cloud.Location+json]

A Location represents a particular geographic or other physical location. VDCs are provisioned within a particular location such that the various included elements may have high bandwidth and secure connectivity.

A "Location" resource model contains the following fields:

Field Name Type Occurs Description
name String 1 Logical name for this location.
uri URI 1 A GET against this URI refreshes the client representation of this Location resource.
description String 0..1 Human friendly description of this Location. [POST][PUT]

Virtual Data Center (VDC) [application/vnd.com.sun.cloud.VDC+json]

A VDC represents a user's view of available resources in a single virtual data center. It also provides URIs for acquiring related resource representations, as well as URIs for creating new resources of various types.

A "VDC" resource model contains the following fields:

Field Name Type Occurs Description
name String 1 Logical name of this virtual data center. [POST][PUT]
uri URI 1 A GET against this URI refreshes the client representation of this virtual data center.
description String 0..1 Human friendly description of this VDC. [POST][PUT]
location URI 0..1 URI of the Location within which resources for this VDC are physically deployed. [POST]
addresses PublicAddress[] 1 The static public IP addresses which are allocated for use in this VDC. PublicAddress resources that are currently attached will have a URI value in the "vm" field describing to which VM that address is currently attached.
cluster Cluster 1 The root cluster associated with this VDC.
tags [ ] 0..1 Arbitrary values assigned by the user. These values have no semantic impact on the operation of the cloud. [POST][PUT]
volumes Volume[] 1 The WebDAV volumes (in the storage service) owned by this user.
vm_templates URI 1 A GET request against this URI returns an array of available templates (type=application/vnd.com.sun.cloud.VMTemplates+json).

Request Status [application/vnd.com.sun.cloud.Status+json]

A status represents a report on the progress of a request for a change in the state of the cloud. Such requests receive an HTTP status code of "202 Accepted", with the response body being a Status representation.

This is designed to be used by applications to poll the server to track the progress of a request; thus, server implementations SHOULD anticipate this activity and make such polling reasonably lightweight.

A status resource model contains the following fields:

Field Name Type Occurs Description
op String 1 Identifies the nature of the request whose status this represents. The possible values are described in the specifications of the individual requests.
progress Integer in the range 0-100, inclusive 1 Represents the progress towards completion of the request. A value of 100 indicates that the request has completed. There is no requirement that implementations be able to predict the latency of requests; it should not be surprising if, during the lifetime of a request, the progress value remains at 0 until it changes to 100 upon request completion.
target_uri URI 1 Identifies the resource upon which the request is acting. Specific semantics depend on the details of the request, and are described fully in the specifications of the individual requests.
status_uri URI 1 Identifies this status resource and may be used to retrieve an up-to-date status report.
status Integer 1 HTTP status code describing the result of the completed operation. Typical values would be 200, 201, and various error codes. This value is only meaningful if the value of the "progress" field is 100.
message String 1 Brief message describing the completed operation (if successful) or an error message (if not successful). This value is only meaningful if the value of the "progress" field is 100.

Public Address [application/vnd.com.sun.cloud.PublicAddress+json]

A public address represents a static, publicly accessible Internet Protocol (IP) address, which can be attached to a particular VM via an interface. The fact that this address is static means it is suitable for registration with the Domain Name Service (DNS) environment for your application domain. Typically, the VM that a public address is attached to will be a firewall appliance, but this is not required by the Cloud API itself.

A public address resource model contains the following fields:

Field Name Type Occurs Description
name String 1 Logical name of this Public Address (unique within owning VDC). [POST][PUT]
uri URI 1 URI by which this public address may be addressed as a standalone resource.
description String 0..1 Human friendly description of this Public Address. [POST][PUT]
vdc URI 1 URI of the VDC this PublicAddress belongs to.
dns String[] 1 List of DNS server IP addresses to be used for connecting out through this Internet connection. [POST][PUT]
domain_names String[] 0..1 Optional list of domain names associated with this public IP address (informational only). [POST][PUT]
gateway String 1 Gateway for this Internet connection.
ip_address String 1 Physical IP address represented by this public address instance.
netmask String 1 Netmask for this Internet connection.
tags [ ] 0..1 Arbitrary values assigned by the user. These values have no semantic impact on the operation of the cloud. [POST][PUT]
vm URI 0..1 URI of the VM to which this address is attached, if any.

Cluster [application/vnd.com.sun.cloud.Cluster+json]

A cluster represents a grouping of VM and VNet resources, segregated for purposes of grouping by common functionality, shared access control, or other purposes. Each VDC contains, by definition, one root cluster, which may in turn contain other clusters; the effect is that of a filesystem-like hierarchy of clusters.

A cluster resource model contains the following fields:

Field Name Type Occurs Description
name String 1 Logical name of this cluster, unique within the owning VDC. [POST][PUT]
uri URI 1 URI by which this cluster may be addressed as a standalone resource.
description String 0..1 Human friendly description of this Cluster. [POST][PUT]
vdc URI 1 URI of the VDC this Cluster belongs to.
parent URI 0..1 URI of the parent Cluster for this Cluster (if this is not the root cluster of a VDC).
from_cluster URI 0..1 On a Create Cluster request type, the URI of an existing cluster to initialize default values from. [POST]
tags [ ] 0..1 Arbitrary values assigned by the user. These values have no semantic impact on the operation of the cloud. [POST][PUT]
vnets VNet[] 0..1 The collection of virtual private networks associated with this Cluster.
vms VM[] 0..1 The collection of virtual machines associated with this cluster.
controllers {} 0..1 Hash of URIs which may be used to request state changes in the cluster via POST requests (see next table), keyed by the type of state change being requested.
clusters Cluster[] 0..1 Collection of Clusters which are logically contained in this cluster.

Some of the "control" URIs may or may not be accessible based on the state of the cluster, and may not appear in representations of it when not usable. For convenience, these are grouped into the "controllers" list field, in which zero or more of the following URIs (keyed by the change type) will be included in a representation provided by the server.

Change Type Operation Requested
start Start up all the VMs in this cluster, in ascending order based on the boot_order value of each VM.
stop Shut down all the VMs this cluster, in descending order based on the boot_order value of each VM.

Volume [application/vnd.com.sun.cloud.Volume+json]

A Volume represents a remote WebDAV volume that may be accessed by the same credentials used to access this information. Such volumes are global to the calling user, and are therefore enumerated in the containing VDC.

A Volume resource model contains the following fields:

Field Name Type Occurs Description
name String 1 Logical name of this volume (unique within the owning VDC). [POST][PUT]
uri URI 1 GET, PUT, and DELETE operations may be used to retrieve, update, or delete this volume.
description String 0..1 Human friendly description of this Volume. [POST][PUT]
vdc URI 1 URI of the VDC this Volume belongs to.
webdav URI 1 The URI for use in any WebDAV operations.
created Timestamp 1 Date and time when this volume was created.
snapshots Snapshot[] 0..1 Collection of snapshots associated with this volume.
tags [ ] 0..1 Arbitrary values assigned by the user. These values have no semantic impact on the operation of the cloud. [POST][PUT]

Snapshot [application/vnd.com.sun.cloud.Snapshot+json]

A Snapshot represents a point-in-time representation of the contents of a Volume.

A Snapshot resource model contains the following fields:

Field Name Type Occurs Description
name String 1 Logical name of this snapshot, unique within the owning Volume. [POST]
uri URI 1 GET, PUT, and DELETE operations may be used to retrieve, update, or delete this snapshot.
description String 0..1 Human friendly description of this Snapshot. [POST][PUT]
volume URI 1 URI of the Volume this Snapshot belongs to.
created Timestamp 1 Date and time when this snapshot was created.
clone URI 0..1 A POST to this URI is a request to clone this snapshot into a new volume with a name included in the request body.
rollback URI 0..1 A POST to ths URI is a request to revert the owning volume to the contents as of when this snapshot was created.

Virtual Machine (VM) [application/vnd.com.sun.cloud.VM+json]

A VM represents a virtual computer that is associated with a cluster.

A VM data model contains the following fields:

Field Name Type Occurs Description
name String 1 Logical name of this VM, unique within the owning Cluster. [POST][PUT]
uri URI 1 GET, PUT, and DELETE may be used to retrieve representations of the VM, to update it, and to delete it, respectively.
description String 0..1 Human friendly description of this VM. [POST][PUT]
cluster URI 1 URI of the Cluster this VM belongs to.
run_status String 0..1 Current running status of this virtual machine (read only). Valid values for this field are "STOPPED", "STARTING", "STARTED", "SLEEPING", "ASLEEP", "WAKING", and "STOPPING". Initial run_status of a newly created VM is "STOPPED".
updated Boolean 1 A value of true means that a change has been made to the VM resource, which will not take effect until the VM has been rebooted.
last_boot Timestamp 1 Date when this VM was most recently booted.
from_template String 0..1 On a Create VM request type, the URI of an existing VM template to initialize default values from. [POST]
from_vm String 0..1 On a Create VM request type, the URI of an existing VM to initialize default values from. [POST]
hostname String 0..1 Fully qualified (?) host name of this virtual machine.
os String 0..1 Operating system running on the VM. FIXME - enumerate the legal values. [POST]
cpu Integer 0..1 CPU speed in Mhz. [POST]
memory Integer 0..1 Main memory size in MB. [POST]
boot_disk Integer 0..1 Boot disk space to allocate in GB. [POST]
data_disk Integer 0..1 Data disk space to allocate in GB. [POST]
temp_disk Integer 0..1 Temporary disk space to allocate in GB. [POST]
boot_order Integer 0..1 Sort ordering value for start cluster and stop cluster operations. When a cluster is started, VMs with the same boot_order value will be started in an undefined sequence, but the service will ensure that all VMs with a particular boot_order value will have been started before starting VMs with a higher boot_order value. The sequence is reversed for a stop cluster operation. VMs with no boot_order value will be assumed to have a boot_order of the maximum integer value, so they will be started last and stopped first. [POST][PUT]
params { } 0..1 Configuration parameters for this VM, keyed by parameter name. The list of system defined configuration parameters is TBD, but one of them will be "user_params", whose value is a hash of arbitrary user defined configuration parameters. [POST][PUT]
tags [ ] 0..1 Arbitrary values assigned by the user. These values have no semantic impact on the operation of the cloud. [POST][PUT]
back_up URI 1 A POST of a Backup representation to this URI requests creation of a new Backup.
attach URI 1 A POST of a PublicAddress representation to this URI requests connection to a Public Address. Or, a POST of a VNet representation to this URI requests connection to a VNet.
detach URI 1 A POST of a PublicAddress representation to this URI requests disconnection from a Public Address. Or, a POST of a VNet representation to this URI reequests disconnection from a VNet.
backups Backup[] 0..1 Backup snapshots from this virtual machine.
interfaces Interface[] 1 Network interfaces associated with this virtual machine. These are created automatically when VNets or Public Addresses are associated with VM.[POST]
controllers {} 0..1 Hash of URIs which may be used to request state changes in the VM via POST requests (see next table), keyed by the type of state change being requested.

Some of the "control" URIs, such as those identified in the "attach" and "detach" fields, are in principle always accessible and thus appear as first-class values in the representation of a VM. Others may or may not be accessible based on the state of the VM, and may not appear in representations of it when not accessible. For convenience, these are grouped into the "controllers" list field, in which zero or more of the following URIs (keyed by the change type) will be included in a representation provided by the server.

Change Type Operation Requested Initial State Intermediate State Final State
start Start up a VM. STOPPED STARTING STARTED
stop Shut down a running VM. STARTED STOPPING STOPPED
reboot Reboot a running VM. STARTED STOPPING -> STOPPED -> STARTING STARTED
hibernate Put a running VM to sleep. STARTED SLEEPING ASLEEP
resume Wake up a hibernated VM. ASLEEP WAKING STARTED

Backup [application/vnd.com.sun.cloud.Backup+json]

A backup represents a snapshot that was taken of a specific virtual machine.

A backup resource model contains the following fields:

Field Name Type Occurs Description
name String 1 Logical name of this backup, unique within owning VM. [POST][PUT]
uri URI 1 GET, PUT, and DELETE may be used to retrieve representations of the Backup, to update it, and to delete it, respectively.
description String 0..1 Human friendly description of this Backup. [POST][PUT]
type String 0..1 Type of this backup (service provider default if not specified). [POST]
created DateTime 1 Timestamp when this backup was created.
restore URI 1 URI that will accept a POST to restore the state of the associated VM to this Backup.
vm URI 1 URI of the VM that this Backup was captured for.
tags [ ] 0..1 Arbitrary values assigned by the user. These values have no semantic impact on the operation of the cloud. [POST][PUT]

Virtual Network (VNet) [application/vnd.com.sun.cloud.VNet+json]

A VNet represents a virtual private network to which an interface associated with a VM may be attached. VNets may connect VMs within a Cluster, or they may connect VMs from different clusters together to provide a private communications path.

A VNet is logically contained within a cluster, but this relationship only exists for administrative purposes and does not affect the operations available on it.

A VNet resource model contains the following fields:

Field Name Type Occurs Description
name String 1 Logical name of this VNet, unique within the owning Cluster. [POST][PUT]
uri URI 1 URI that may be used to access this VNet as a standalone resource.
description String 0..1 Human friendly description of this 'VNet. [POST][PUT]
cluster URI 1 URI of the Cluster this VNet belongs to.
netmask String 1 Default network mask for interfaces connected to this VNet.
tags [ ] 0..1 Arbitrary values assigned by the user. These values have no semantic impact on the operation of the cloud. [POST][PUT]

Interface [application/vnd.com.sun.cloud.Interface+json]

An interface represents a network interface card (nic), associated with a specific VM, that documents an IP connection (from this VM) either to a VNet (virtual private network) or to a public address (a static public IP address accessible from the Internet). For the latter scenario, the VM will typically implement firewall and/or load balancing functionality, but this is not required by the API.

Interface instances are created, modified, and removed as a side effect of other operations. Therefore, they do not possess a URI of their own, and support no operations against themselves directly.

A interface resource model contains the following fields:

Field Name Type Occurs Description
vnet URI 0..1 The URI of the VNet instance, if this interface is attached to one. At most one of vnet or public address must be defined.
public_address URI 0..1 The URI of the public address instance, if this interface is attached to one. At most one of vnet or public address must be defined.
nic String 1 Name of the network interface connector as seen by the host operating system.
mac_address String 1 MAC address of this network interface.
ip_address String 1 IP address of this network interface. If the interface is connected to a Public Address, will be a duplicate of its ip_address field.

Virtual Machine Template (VMTemplate) [application/vnd.com.sun.cloud.VMTemplate+json]

A VMTemplate represents a preconfigured virtual machine image that may be "cloned" in a Create Virtual Machine request, by specifying the URI of a particular template as the value of the from_template field.

A VMTemplate data model contains the following fields:

Field Name Type Occurs Description
name String 1 Logical name of this VMTemplate.
uri URI 1 URI to reference this template in a Create Virtual Machine request.
description String 0..1 Human friendly description of this virtual machine template.
os String 0..1 Operating system running on the VM. FIXME - enumerate the legal values.
cpu Integer 0..1 CPU speed in Mhz.
memory Integer 0..1 Main memory size in MB.
boot_disk Integer 0..1 Boot disk space to allocate in GB.
data_disk Integer 0..1 Data disk space to allocate in GB.
temp_disk Integer 0..1 Temporary disk space to allocate in GB.
params { } 0..1 Configuration parameters for this VM, keyed by parameter name. The list of system defined configuration parameters is TBD, but one of them will be "user_params", whose value is a hash of arbitrary user defined configuration parameters.
tags [ ] 0..1 Arbitrary values assigned by the user. These values have no semantic impact on the operation of the cloud.

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 20140418.2d69abc)
 
 
Close
loading
Please Confirm
Close