Scyld Cloud Controller Documentation
Storage-Volume API
The storage-volume API presents an interface for creating, modifying, and deleting storage volumes. Only one type of storage volume is supported at this time, which serves as a user’s $HOME directory. All of a user’s data is written to their $HOME, including their SSH keys. As such, a storage volume is required in order to push SSH Keys to the user account in Scyld Cloud Controller, and in order to log in. The $HOME directory is automatically mounted in any server-instances the user has access to.
Storage-Volume Object
A storage-volume object has the following properties:
- volume-id – string. A UUID uniquely identifying this storage-volume object.
- cloudauth-id – string. A UUID identifying the Scyld Cloud Auth user ID associated with this user.
- volume-size – integer. The provisioned size of the volume in Gigabytes (GB).
- volume-type – object. Contains the type of volume, and additional details of the volume specific to the type.
- creation-date – string. Timestamp of when the volume was created.
- volume-name – string. Optional description of the volume.
API Methods
/storage-volume
The /storage-volume URI accept HTTP GET and HTTP POST.
GET
An HTTP GET on /storage-volume will return a list of storage-volume objects that the requester has permission to see.
A requester with the superuser role in Scyld Cloud Auth would see all storage-volume objects in the system. A requester with no special permissions, and who does not have any managed users will only see storage-volumes owned by themselves. A requester that has managed users will see their own storage-volumes, plus the storage-volumes belonging to their managed users.
The following querystring parameters can be specified to further limit the results:
- cloudauth-id – Search for accessible storage-volumes that are owned by the given cloudauth-id.
Storage-Volume Response Schema
The response from GET /storage-volume is governed by the following JSON-Schema:
{
"name": "storage-volume reponse data",
"description": "Response data for storage-volume requests. Contains details of storage volumes",
"type": "array",
"items": {
"title": "A storage-volume object",
"type": "object",
"properties": {
"volume-id": {
"description": "storage-volume id",
"type": "string",
"required": True
},
"cloudauth-id": {
"description": "CloudAuth User ID that owns this storage-volume",
"type": "string",
"required": True
},
"volume-size": {
"description": "provisioned size in GB",
"type": "integer",
"required": True
},
"volume-type": {
"description": "The type of volume",
"type": [
{
"type": "object",
"properties": {
"visibility": {
"description": "Where is this volume accessible",
"type": "string",
"enum": ["cluster"],
"required": True
},
"mount-point": {
"description": "Path where volume is mounted",
"type": "string",
"required": True
}
},
"additionalProperties": False
}
],
"required": True
},
"creation-date": {
"description": "Time stamp of when instance was created",
"type": "string",
"format": "date-time",
"required": True
},
"volume-name": {
"description": "volume description",
"type": "string",
"required": False
}
},
"additionalProperties": False,
"required": True
},
"additionalItems": False,
"minItems": 0
}
Examples
Query your storage volumes:
# curl -X GET -H "X-Auth-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" -H "X-Auth-Cloudauth-Id: 00000000000000000000000000000000" https://localhost/v1/storage-volume | python -m json.tool
{
"data": [
{
"cloudauth-id": "00000000000000000000000000000000",
"creation-date": "2013-03-21T21:06:51Z",
"volume-id": "ba82e13d544f4511b8eeeeaf67d5b998",
"volume-name": null,
"volume-size": 10,
"volume-type": {
"mount-point": "/home/tester",
"visibility": "cluster"
}
}
],
"msg": "",
"success": true
}
POST
An HTTP POST on /storage-volume will create a new storage-volume.
Since the only currently supported volume-type is “cluster”, and serves as a user’s $HOME, only one volume per Scyld Cloud Controller user is allowed. Future volume-types will remove this restriction.
When creating a storage volume, you must specify the size of the volume to create, and may optionally give it a descriptive name.
Storage-Volume POST Schema
The data format for POST /storage-volume is governed by the following JSON-Schema:
{
"name": "Storage-volume POST data",
"description": "Create a new storage-volume on the system",
"type": "object",
"properties": {
"volume-size": {
"description": "size of volume, in GB",
"type": "integer",
"required": True
},
"volume-name": {
"description": "Optional volume description",
"type": "string",
"required": False
},
"volume-type": {
"description": "The type of volume to create",
"type": [
{
"type": "object",
"properties": {
"visibility": {
"description": "Where will this volume be accessible",
"type": "string",
"enum": ["cluster"],
"required": True
}
},
"additionalProperties": False
}
],
"required": True
}
},
"additionalProperties": False
}
Examples
Create a 1GB volume for your home directory:
# curl -X POST -H "X-Auth-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" -H "X-Auth-Cloudauth-Id: 00000000000000000000000000000000" -d '{"volume-size": 1, "volume-type": {"visibility": "cluster"}}' https://localhost/v1/storage-volume | python -m json.tool
{
"data": [
{
"cloudauth-id": "00000000000000000000000000000000",
"creation-date": "2013-04-16T15:42:42Z",
"volume-id": "ba82e13d544f4511b8eeeeaf67d5b998",
"volume-name": null,
"volume-size": 1,
"volume-type": {
"mount-point": "/home/tester",
"visibility": "cluster"
}
}
],
"msg": "",
"success": true
}
/storage-volume/<ID>
The /storage-volume/<id> URI accepts HTTP GET and HTTP DELETE.
PUT is not supported at this time – volumes must be resized manually by an administrator.
The <id> field here is a UUID that uniquely identifies a specific storage-volume.
GET
An HTTP GET on /storage-volume/<id> will return data in the exact same format as /storage-volume (see Storage-Volume Response Schema), but will contain at most one item – the volume referenced by UUID.
DELETE
An HTTP DELETE on an existing storage-volume object will delete that volume from the system, removing all user data, and their ability to log in. A user’s storage volume must be deleted before the user can be deleted.
Warning! Deleting a storage-volume removes all data, and should be considered non-recoverable.
Examples
Delete your storage volume:
# curl -X DELETE -H "X-Auth-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" -H "X-Auth-Cloudauth-Id: 00000000000000000000000000000000" https://localhost/v1/storage-volume/ba82e13d544f4511b8eeeeaf67d5b998 | python -m json.tool
{
"data": [],
"msg": "",
"success": true
}