Scyld Cloud Controller Documentation
Server Instance API
The Server-Instance API presents an interface for creating, modifying, and deleting server-instance objects. A server-instance object is a virtual machine, and is created by combining a server-flavor and a server-image. In order to create a server-instance object, one must have a system account and a storage volume.
Server-Instance Object
A server-instance object has the following properties:
- id – string. A UUID that uniquely identifies this server-instance object.
- cloudauth-id – string. A UUID that identifies the Scyld Cloud Auth user ID that owns the instance.
- users – list. A list of Scyld Cloud Controller User IDs that have access to the instance.
- server-image – string. The server-image ID that the instance was created from.
- server-flavor – string. The server-flavor ID that the instance was created with.
- creation-date – string. The timestamp the server-instance was created.
- status – string. A short text description of the current state of the instance.
- hostname – string. Optional hostname of the instance. Useful if the name is available in a DNS.
- public-ip – string. Optional text containing a public IP address where the instance can be reached.
- private-ip – string. Optional text containing the instances private IP address.
The optional properties may not be returned if they are empty or unset.
API Methods
/server-instance
The /server-instance URI accepts HTTP GET, HTTP POST, HTTP PUT, and HTTP DELETE.
GET
An HTTP GET on /server-instance will return a list of instances that the request has access to.
A requester with the superuser role in Scyld Cloud Auth would see all instance objects in the system. A requester with no special permissions, and who does not have any managed users will only see instances owned by themselves. A requester that has managed users will see their own instances, plus the instances belonging to their managed users.
The following querystring parameters can be specified to further limit the results:
- cloudauth-id – Search for accessible Users that are owned by the given cloudauth-id.
Server-Instance Response Schema
The response from the GET /server-instance is governed by the following JSON-Schema:
{
"name": "server-instance reponse data",
"description": "Response data for server-instance requests. Contains details of server-instances",
"type": "array",
"items": {
"title": "A server-instance object",
"type": "object",
"properties": {
"id": {
"description": "server-instance id",
"type": "string",
"required": True
},
"cloudauth-id": {
"description": "CloudAuth User ID that owns this server-instance",
"type": "string",
"required": True
},
"users": {
"description": "List of user UUIDs that have been granted access to this instance",
"type": "array",
"items": {
"type": "string",
},
"additionalItems": False,
"minItems": 0,
"required": True
},
"server-image": {
"description": "server image ID",
"type": "string",
"required": True
},
"server-flavor": {
"description": "server flavor ID",
"type": "string",
"required": True
},
"hostname": {
"description": "instance hostname",
"type": "string",
"format": "hostname",
"required": False
},
"creation-date": {
"description": "Time stamp of when instance was created",
"type": "string",
"format": "date-time",
"required": True
},
"public-ip": {
"description": "publically accessible IP address",
"type": "string",
"format": "ip-address",
"required": False
},
"private-ip": {
"description": "private netowrk IP address",
"type": "string",
"format": "ip-address",
"required": False
},
"status": {
"description": "status of instance",
"type": "string",
"required": True
}
},
"additionalProperties": False,
"required": True
},
"additionalItems": False,
"minItems": 0
}
Examples
Get a list of server-instances you have access to:
# curl -X GET -H "X-Auth-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" -H "X-Auth-Cloudauth-Id: 00000000000000000000000000000000" https://localhost/v1/server-instance | python -m json.tool
{
"data": [
{
"cloudauth-id": "00000000000000000000000000000000",
"creation-date": "2013-03-11T23:37:07Z",
"id": "57ea75def407447e821d45a6b3ee2ec4",
"server-flavor": "1",
"server-image": "b8bdda90-664b-4906-86d6-dd33735441f2",
"status": "SHUTOFF",
"users": [
"08ef9f4ed8734dbf8249cf6cb3f37d99"
]
},
{
"cloudauth-id": "00000000000000000000000000000000",
"creation-date": "2013-05-06T17:00:51Z",
"id": "aaedc7cf50574b479608de1f351429bd",
"private-ip": "10.10.100.254",
"public-ip": "192.41.74.254",
"server-flavor": "1",
"server-image": "e36256c9-93cb-4178-83b0-ead2243fc0e1",
"status": "ACTIVE",
"users": [
"08ef9f4ed8734dbf8249cf6cb3f37d99",
"0a67d547a1bd46be9f97f2cc12a4af15"
]
}
],
"msg": "",
"success": true
}
POST
An HTTP POST on /server-instance will create a new server instance.
When creating a new server-instance, you must specify its size (flavor) and the image to boot it from. Users can have multiple server-instances. You can optionally provide a list of Scyld Cloud Controller User UUIDs (user.user-id) that represent users to grant access to this created instance (provided you have authority to do so). The creating user will always be added to the VM automatically.
Server-Instance POST Schema
The data format for POST /server-instance is governed by the following JSON-Schema:
{
"name": "server-instance POST data",
"description": "Create a new server on the system",
"type": "object",
"properties": {
"server-image": {
"description": "server image ID",
"type": "string",
"required": True
},
"server-flavor": {
"description": "server flavor ID",
"type": "string",
"required": True
},
"users": {
"description": "List of user-ids granted access to this instance",
"type": "array",
"items": {
"type": "string",
},
"minItems": 0,
"required": False
}
},
"additionalProperties": False,
"required": True
}
/server-instance/<ID>
The /server-instance/<id> URI accepts HTTP GET, HTTP PUT, and HTTP DELETE.
The <id> field is a UUID that identifies a specific server-instance object.
GET
An HTTP GET on /server-instance/<id> will return data in the exact same format as /server-instance (see Server-Instance Response Schema), but will contain at most one item – the server referenced by UUID.
PUT
An HTTP PUT on /server-instance/<id> will attempt to modify the properties of the server.
There are two properties of a server that can be modified:
- users – The list of users allowed access to the VM.
- state – The VM can be rebooted, powered on, or powered off.
There are three “actions” that can be taken when modifying the list of users allowed on the VM:
- add – This will add the given users to the VM, leaving the existing users.
- delete – This will remove the given users from the VM, leaving any that are unreferenced.
- replace – This will delete all existing suers from the VM, and add the given ones.
Server-Instance PUT Schema
The data format for PUT /server-instance/<id> is governed by the following JSON-Schema:
{
"name": "server-instance PUT data",
"description": "Modify a server on the system",
"type": "object",
"properties": {
"task": {
"description": "The change to make on the server-instance",
"type": [
{
"type": "object",
"properties": {
"what": {
"description": "Modify user-access to server-instance",
"type": "string",
"enum": ["modify-users"],
"required": True
},
"how": {
"description": "what should be done with list in 'users'",
"type": "string",
"enum": ["add", "replace", "delete"],
"required": True
},
"users": {
"description": "List of user-ids granted access to this instance",
"type": "array",
"items": {
"type": "string",
},
"minItems": 0,
"required": True
}
},
"additionalProperties": False,
},
{
"type": "object",
"properties": {
"what": {
"description": "Change power-state of server-instance",
"type": "string",
"enum": ["reboot", "power-on", "power-off"],
"required": True
}
},
"additionalProperties": False,
}
],
"required": True
}
},
"additionalProperties": False
}
DELETE
An HTTP DELETE on an existing server instance will delete the VM entirely