clustoapi.server: Server main module¶

clustoapi.util: Miscellaneous util module¶

clustoapi.util.dumps(obj, code=200, headers={})[source]¶

Dumps a given object as a JSON string in an HTTP Response object. Will circumvent pretty-printing if Clusto-Minify header is True.

clustoapi.util.get(name, driver=None)[source]¶

Tries to fetch a clusto object from a given name, optionally validating the driver given. Returns:

• HTTP Error 404 if the object could not be found
• HTTP Error 409 if the object does not match the expected driver
• Clusto object otherwise

clustoapi.util.page(ents, current=1, per=50)[source]¶

Takes a list of entities and drops all from a list but the current page. Returns a tuple that has the entities and also a page total so it may be returned to the client.

clustoapi.util.show(obj, mode='')[source]¶

Will return the expanded or compact representation of a given object

clustoapi.util.typecast(value, datatype, mask='%Y-%m-%dT%H:%M:%S.%f')[source]¶

Takes a string and a valid clusto datatype and attempts to cast the value to the specified datatype. Will error out if a ValueError is incurred or a relation does not exist. Will aslo take a strptime format as mask because typcasting datetimes is hard.

clustoapi.util.unclusto(obj)[source]¶

Convert an object to a representation that can be safely serialized into JSON.

clustoapi.apps.attribute: Attribute Application¶

The attribute application handles all attribute specific operations like querying, adding, deleting and updating attributes.

clustoapi.apps.attribute.add_attr(name, **kwargs)[source]¶

Add an attribute to this object.

• Requires parameters name, key, and value
• Optional parameters are subkey`,` ``number, and datatype
• Additionally, mask can be provided for a datetime attribute.
• These parameters can be either be passed with a querystring
• or a json body. If json is supplied, multiple attributes may be
• added at the same time.

Example:

$ ${post} -d 'name=addattrserver' ${server_url}/entity/basicserver
[
    "/basicserver/addattrserver"
]
HTTP: 201
Content-type: application/json

$ ${post} -d 'key=group' -d 'value=web' ${server_url}/attribute/addattrserver
[
    {
        "datatype": "string",
        "key": "group",
        "number": null,
        "subkey": null,
        "value": "web"
    }
]
HTTP: 201
Content-type: application/json

Will:

1. Create an entity called addattrserver
2. Add the attribute with key=group and value=web to it

Example:

$ ${post} -d 'key=group' -d 'subkey=owner' -d 'value=web' ${server_url}/attribute/addattrserver
[
    {
        "datatype": "string",
        "key": "group",
        "number": null,
        "subkey": null,
        "value": "web"
    },
    {
        "datatype": "string",
        "key": "group",
        "number": null,
        "subkey": "owner",
        "value": "web"
    }
]
HTTP: 201
Content-type: application/json

Will add the attribute with key group and subkey owner and value joe to the previously created entity addattrserver

$ ${post} -d 'key=group' -d 'subkey=id' -d 'value=6' -d 'datatype=int' ${server_url}/attribute/addattrserver
[
...
    {
        "datatype": "int",
        "key": "group",
        "number": null,
        "subkey": "id",
        "value": 6
    }
]
HTTP: 201
Content-type: application/json

Will add the attribute with key group and subkey id and value 1 with the correct datatype to the previously created entity addattrserver

$ ${post} -d 'key=inception' -d 'value=/basicserver/addattrserver' -d 'datatype=relation' ${server_url}/attribute/addattrserver
[
...
    {
        "datatype": "relation",
        "key": "inception",
        "number": null,
        "subkey": null,
        "value": "/basicserver/addattrserver"
    }
]
HTTP: 201
Content-type: application/json

Will add the attribute with key inception and itself as a relation using the relation datatype.

$ ${post} -d 'key=birthday' -d 'subkey=jtcunning' -d 'value=1991-07-09T14:46:51.321435' -d 'datatype=datetime' ${server_url}/attribute/addattrserver
[
    {
        "datatype": "datetime",
        "key": "birthday",
        "number": null,
        "subkey": "jtcunning",
        "value": "1991-07-09T14:46:51.321435"
    },
...
]
HTTP: 201
Content-type: application/json

Will add the attribute with key birthday and subkey jtcunning with the datetime python object as the datatype.

$ ${post} -H 'Content-Type: application/json' -d '${sample_json_attrs}' ${server_url}/attribute/addattrserver
[
    ...
    {
        "datatype": "string",
        "key": "group",
        "number": null,
        "subkey": "admin",
        "value": "apache"
    },
    {
        "datatype": "string",
        "key": "group",
        "number": null,
        "subkey": "member",
        "value": "webapp"
    },
    ...
]
HTTP: 201
Content-type: application/json

Will add two attributes in bulk by stating that the content type is application/json.

clustoapi.apps.attribute.attrs(name, key=None, subkey=None, number=None)[source]¶

Query attributes from this object.

Example:

$ ${post} -d 'name=attrpool1' ${server_url}/entity/pool
[
    "/pool/attrpool1"
]
HTTP: 201
Content-type: application/json

$ ${get} ${server_url}/attribute/attrpool1
[]
HTTP: 200
Content-type: application/json

Will show all the attributes from the object attrpool1:

$ ${get} -d 'driver=pool' ${server_url}/attribute/attrpool1
[]
HTTP: 200
Content-type: application/json

Will show all the attributes from the object attrpool1 if the driver for attrpool1 is pool. In the same vein this code:

$ ${get} -d 'driver=basicserver' ${server_url}/attribute/attrpool1
...
HTTP: 409
...

Should fail, because the attrpool1 object is of type pool, not basicserver

Example:

$ ${get} ${server_url}/attribute/attrpool1/owner
[]
HTTP: 200
Content-type: application/json

Will show the attributes for server1 if their key is owner.

clustoapi.apps.attribute.del_attrs(name, key, subkey=None, number=None)[source]¶

Deletes an attribute from this object

• Requires HTTP path key
• Optional parameters are subkey, value, and number

Examples:

$ ${post} -d 'name=deleteserver1' ${server_url}/entity/basicserver
[
    "/basicserver/deleteserver1"
]
HTTP: 201
Content-type: application/json

$ ${put} -d 'value=joe' ${server_url}/attribute/deleteserver1/group/owner
[
    {
        "datatype": "string",
        "key": "group",
        "number": null,
        "subkey": "owner",
        "value": "joe"
    }
]
HTTP: 200
Content-type: application/json

$ ${delete} ${server_url}/attribute/deleteserver1/group/owner
[]
HTTP: 200
Content-type: application/json

Will create a basicserver object called deleteserver1, then it will add an attribute (the only attribute so far), then it will delete it.

$ ${post} -d 'name=deleteserver2' ${server_url}/entity/basicserver
[
    "/basicserver/deleteserver2"
]
HTTP: 201
Content-type: application/json

$ ${put} -d 'value=engineering' ${server_url}/attribute/deleteserver2/group
[
    {
        "datatype": "string",
        "key": "group",
        "number": null,
        "subkey": null,
        "value": "engineering"
    }
]
HTTP: 200
Content-type: application/json

$ ${put} -d 'value=joe' ${server_url}/attribute/deleteserver2/group/owner
[
    {
        "datatype": "string",
        "key": "group",
        "number": null,
        "subkey": null,
        "value": "engineering"
    },
    {
        "datatype": "string",
        "key": "group",
        "number": null,
        "subkey": "owner",
        "value": "joe"
    }
]
HTTP: 200
Content-type: application/json

$ ${delete} ${server_url}/attribute/deleteserver2/group/owner
[
    {
        "datatype": "string",
        "key": "group",
        "number": null,
        "subkey": null,
        "value": "engineering"
    }
]
HTTP: 200
Content-type: application/json

This example should add two attributes with the same key, but different subkey, then it will delete only the second value.

clustoapi.apps.attribute.set_attr(name, **kwargs)[source]¶

Sets an attribute from this object. If the attribute doesn’t exist it will be added, if the attribute already exists then it will be updated.

• Requires HTTP parameters key and value
• Optional parameters are subkey`,` ``number, and datatype
• Additionally, mask can be provided for a datetime attribute.

Example:

$ ${post} -d 'name=setattrserver' ${server_url}/entity/basicserver
[
    "/basicserver/setattrserver"
]
HTTP: 201
Content-type: application/json

$ ${post} -d 'key=group' -d 'value=web' ${server_url}/attribute/setattrserver
[
    {
        "datatype": "string",
        "key": "group",
        "number": null,
        "subkey": null,
        "value": "web"
    }
]
HTTP: 201
Content-type: application/json

$ ${put} -d 'value=db' ${server_url}/attribute/setattrserver/group
[
    {
        "datatype": "string",
        "key": "group",
        "number": null,
        "subkey": null,
        "value": "db"
    }
]
HTTP: 200
Content-type: application/json

Will:

1. Create the entity setattrserver
2. Add the attribute with key=group and value=web
3. Update the attribute to value=db

Example:

$ ${post} -d 'name=setattrserver2' ${server_url}/entity/basicserver
[
    "/basicserver/setattrserver2"
]
HTTP: 201
Content-type: application/json

$ ${put} -d 'value=joe' ${server_url}/attribute/setattrserver2/group/owner
[
    {
        "datatype": "string",
        "key": "group",
        "number": null,
        "subkey": "owner",
        "value": "joe"
    }
]
HTTP: 200
Content-type: application/json

$ ${put} -d 'value=bob' ${server_url}/attribute/setattrserver2/group/owner
[
    {
        "datatype": "string",
        "key": "group",
        "number": null,
        "subkey": "owner",
        "value": "bob"
    }
]
HTTP: 200
Content-type: application/json

Will:

1. Create a new object setattrserver2 of type basicserver
2. Set the attribute with key group and subkey owner with value joe to the object setattrserver1. Since this is the only attribute so far, this operation works just like add_attr()
3. Update the attribute we set above, now the value will read bob

clustoapi.apps.entity: Entity Application¶

The entity application will hold all methods related to entity management in clusto. That is: creation, querying, modification and overall entity manipulation.

clustoapi.apps.entity.action(driver, name)[source]¶

Inserts/removes the given device from the request parameters into/from the object

Example:

$ ${post} -d 'name=pool1' ${server_url}/entity/pool
[
    "/pool/pool1"
]
HTTP: 201
Content-type: application/json

$ ${post} -d 'name=server1' ${server_url}/entity/basicserver
[
    "/basicserver/server1"
]
HTTP: 201
Content-type: application/json

$ ${post} -d 'device=server1' -d 'action=insert' ${server_url}/entity/pool/pool1
{
    "attrs": [],
    "contents": [
        "/basicserver/server1"
    ],
    "driver": "pool",
    "name": "pool1",
    "parents": [],
    "type": "pool"
}
HTTP: 200
Content-type: application/json

$ ${post} -d 'device=server1' -d 'action=remove' ${server_url}/entity/pool/pool1
{
    "attrs": [],
    "contents": [],
    "driver": "pool",
    "name": "pool1",
    "parents": [],
    "type": "pool"
}
HTTP: 200
Content-type: application/json

Will:

1. Create a pool entity called pool1
2. Create a basicserver entity called server1
3. Insert the entity server1 into the entity pool1
4. Remove the entity server1 from the entity pool1

Examples:

$ ${post} -d 'name=pool2' ${server_url}/entity/pool
[
    "/pool/pool2"
]
HTTP: 201
Content-type: application/json

$ ${post} -d 'name=server2' -d 'name=server3' ${server_url}/entity/basicserver
[
    "/basicserver/server2",
    "/basicserver/server3"
]
HTTP: 201
Content-type: application/json

$ ${post} -d 'device=server2' -d 'device=server3' -d 'action=insert' ${server_url}/entity/pool/pool2
{
    "attrs": [],
    "contents": [
        "/basicserver/server2",
        "/basicserver/server3"
    ],
    "driver": "pool",
    "name": "pool2",
    "parents": [],
    "type": "pool"
}
HTTP: 200
Content-type: application/json

$ ${post} -d 'device=server2' -d 'device=server3' -d 'action=remove' ${server_url}/entity/pool/pool2
{
    "attrs": [],
    "contents": [],
    "driver": "pool",
    "name": "pool2",
    "parents": [],
    "type": "pool"
}
HTTP: 200
Content-type: application/json

The above will:

1. Create a pool entity called pool2
2. Create two basicserver entities called server2 and server3
3. Insert both basicserver entities into the pool entity
4. Remove both basicserver entities from the pool entity

clustoapi.apps.entity.create(driver)[source]¶

Creates a new object of the given driver.

• Requires HTTP parameters name

Example:

$ ${post} -d 'name=createpool1' ${server_url}/entity/pool
[
    "/pool/createpool1"
]
HTTP: 201
Content-type: application/json

Will create a new pool1 object with a pool driver. If the pool1 object already exists, the status code returned will be 202, and you will see whatever warnings in the Warnings header:

$ ${post_i} -d 'name=createpool1' ${server_url}/entity/pool
HTTP/1.0 202 Accepted
...
Warnings: Entity(s) /pool/createpool1 already exist(s)...
[
    "/pool/createpool1"
]

If you try to create a server of an unknown driver, you should receive a 412 status code back:

$ ${post} -d 'name=createobject' ${server_url}/entity/nondriver
"Requested driver "nondriver" does not exist"
HTTP: 412
Content-type: application/json

The following example:

$ ${post_i} -d 'name=createpool1' -d 'name=createpool2' ${server_url}/entity/pool
HTTP/1.0 202 Accepted
...
Warnings: Entity(s) /pool/createpool1 already exist(s)...
[
    "/pool/createpool1",
    "/pool/createpool2"
]

Will attempt to create new objects createpool1 and createpool2 with a pool driver. As all objects are validated prior to creation, if any of them already exists the return code will be 202 (Accepted) and you will get an extra header Warnings with the message.

clustoapi.apps.entity.delete(driver, name)[source]¶

Deletes an object if it matches the given driver

• Requires HTTP parameters name

Examples:

$ ${post} -d 'name=servercreated' ${server_url}/entity/basicserver
[
    "/basicserver/servercreated"
]
HTTP: 201
Content-type: application/json

$ ${delete} ${server_url}/entity/nondriver/servercreated
"Requested driver "nondriver" does not exist"
HTTP: 412
Content-type: application/json

$ ${delete} ${server_url}/entity/basicserver/servercreated
HTTP: 204
Content-type:

$ ${delete} ${server_url}/entity/basicserver/servercreated
HTTP: 404
Content-type: None

Will create a new servercreated object with a basicserver driver. Then it will proceed to delete it. If the operation succeeded, it will return a 200, if the object doesn’t exist, it will return a 404.

clustoapi.apps.entity.list(driver=None)[source]¶

Returns all entities, or (optionally) all entities of the given driver

Example:

$ ${get} ${server_url}/entity/
[
    ...
]
HTTP: 200
Content-type: application/json

Will list all entities

Example:

$ ${get} ${server_url}/entity/clustometa
[
    "/clustometa/clustometa"
]
HTTP: 200
Content-type: application/json

Will list all entities that match the driver clustometa

The following example should fail because there is no driver nondriver:

$ ${get} ${server_url}/entity/nondriver
"The requested driver "nondriver" does not exist"
HTTP: 412
Content-type: application/json

clustoapi.apps.entity.show(driver, name)[source]¶

Returns a json representation of the given object

Example:

$ ${post} -d 'name=showpool' ${server_url}/entity/pool
[
    "/pool/showpool"
]
HTTP: 201
Content-type: application/json

$ ${get} ${server_url}/entity/pool/showpool
{
    "attrs": [],
    "contents": [],
    "driver": "pool",
    "name": "showpool",
    "parents": [],
    "type": "pool"
}
HTTP: 200
Content-type: application/json

Will return a JSON representation of the previously created showpool.

$ ${get} ${server_url}/entity/basicserver/showpool
"The driver for object "showpool" is not "basicserver""
HTTP: 409
Content-type: application/json

Will yield a 409 (Conflict) because the object showpool is not a basicserver object.

clustoapi.apps.resourcemanager: Resource Manager Application¶

The resourcemanager application will hold all methods related to resource management in clusto. Pretty much allocating and deallocating resources.

clustoapi.apps.resourcemanager.allocate(driver, manager)[source]¶

This allocates a new resource to a given thing. Said thing can be either a driver (and the result will be a newly created object subclasses from this driver) or an object, and the resource manager will allocate (bind) a resource to it.

Examples:

$ ${post} -d 'name=allocator' ${server_url}/resourcemanager/simpleentitynamemanager
{
    "attrs": [
        ...
    ],
    "contents": [],
    "count": 0,
    "driver": "simpleentitynamemanager",
    "name": "allocator",
    "parents": [],
    "type": "resourcemanager"
}
HTTP: 201
Content-type: application/json

$ ${post} -d 'driver=basicserver' ${server_url}/resourcemanager/simpleentitynamemanager/allocator
"/basicserver/01"
HTTP: 201
Content-type: application/json

Will request a new name from the object allocator (which is an object of SimpleEntityManager that we just created with default values) and then it will create a new BasicServer object.

$ ${post} -d 'driver=basicserver' -d 'resource=99' ${server_url}/resourcemanager/simpleentitynamemanager/allocator
"/basicserver/99"
HTTP: 201
Content-type: application/json

Will create a new BasicServer object from the testnames resource manager with the specific name of s99.

clustoapi.apps.resourcemanager.create(driver)[source]¶

This differs from the standard way of creating entities is that resource managers can have a number of extra parameters added to them that not necessarily match any of the other entities. These parameters are defined by each resource manager driver and are pretty much arbitrary. Seems like a good idea to separate these crucial differences.

Examples:

$ ${post} -d 'name=nameman1' ${server_url}/resourcemanager/simplenamemanager
{
    "attrs": [
        ...
    ],
    "contents": [],
    "count": 0,
    "driver": "simplenamemanager",
    "name": "nameman1",
    "parents": [],
    "type": "resourcemanager"
}
HTTP: 201
Content-type: application/json

Will create a SimpleNameManager resource manager named namemgr1 with all default values set.

$ ${post} -d 'name=ipman1' -d 'gateway=192.168.1.1' -d 'netmask=255.255.255.0' -d 'baseip=192.168.1.10' ${server_url}/resourcemanager/ipmanager
{
    "attrs": [
        {
            "datatype": "string",
            "key": "baseip",
            "number": null,
            "subkey": "property",
            "value": "192.168.1.10"
        },
        {
            "datatype": "string",
            "key": "gateway",
            "number": null,
            "subkey": "property",
            "value": "192.168.1.1"
        },
        {
            "datatype": "string",
            "key": "netmask",
            "number": null,
            "subkey": "property",
            "value": "255.255.255.0"
        }
    ],
    "contents": [],
    "count": 0,
    "driver": "ipmanager",
    "name": "ipman1",
    "parents": [],
    "type": "resourcemanager"
}
HTTP: 201
Content-type: application/json

Will create a IPManager resource manager named ipman1 with some additional arguments such as netmask, gateway and baseip

clustoapi.apps.resourcemanager.deallocate(driver, manager)[source]¶

Resource managers should allow you to deallocate things just the same as allocating things.

Examples:

$ ${post} -d 'name=ipman2' -d 'gateway=192.168.1.1' -d 'netmask=255.255.255.0' -d 'baseip=192.168.1.10' ${server_url}/resourcemanager/ipmanager
{
    "attrs": [
        {
            "datatype": "string",
            "key": "baseip",
            "number": null,
            "subkey": "property",
            "value": "192.168.1.10"
        },
        {
            "datatype": "string",
            "key": "gateway",
            "number": null,
            "subkey": "property",
            "value": "192.168.1.1"
        },
        {
            "datatype": "string",
            "key": "netmask",
            "number": null,
            "subkey": "property",
            "value": "255.255.255.0"
        }
    ],
    "contents": [],
    "count": 0,
    "driver": "ipmanager",
    "name": "ipman2",
    "parents": [],
    "type": "resourcemanager"
}
HTTP: 201
Content-type: application/json

$ ${post} -d 'name=names2' -d 'basename=a' ${server_url}/resourcemanager/simpleentitynamemanager
{
    "attrs": [
        ...
    ],
    "contents": [],
    "count": 0,
    "driver": "simpleentitynamemanager",
    "name": "names2",
    "parents": [],
    "type": "resourcemanager"
}
HTTP: 201
Content-type: application/json

$ ${post} -d 'driver=basicserver' ${server_url}/resourcemanager/simpleentitynamemanager/names2
"/basicserver/a01"
HTTP: 201
Content-type: application/json

$ ${post} -d 'object=a01' ${server_url}/resourcemanager/ipmanager/ipman2
{
    "datatype": "int",
    "key": "ip",
    "number": 0,
    "subkey": null,
    "value": 1084752130
}
HTTP: 201
Content-type: application/json

$ ${delete} -d 'object=a01' ${server_url}/resourcemanager/ipmanager/ipman2
HTTP: 204
Content-type:

clustoapi.apps.resourcemanager.list(driver=None)[source]¶

Lists all resource managers found in the clusto database. Optionally you can list all resource managers that match the given driver

Examples:

$ ${post} -d 'name=zmanager' ${server_url}/resourcemanager/simplenamemanager
{
    "attrs": [
        ...
    ],
    "contents": [],
    "count": 0,
    "driver": "simplenamemanager",
    "name": "zmanager",
    "parents": [],
    "type": "resourcemanager"
}
HTTP: 201
Content-type: application/json

The above will create a simple name manager called “zmanager”

$ ${get} ${server_url}/resourcemanager/
[
    "/simpleentitynamemanager/testnames",
    "/simplenamemanager/zmanager"
]
HTTP: 200
Content-type: application/json

The above will list all resource managers in clusto, which should have “zmanager”

$ ${get} ${server_url}/resourcemanager/simpleentitynamemanager
[
    "/simpleentitynamemanager/testnames"
]
HTTP: 200
Content-type: application/json

Will list all resource managers of driver SimpleNameManager

$ ${get} ${server_url}/resourcemanager/notadriver
"Not a valid driver "notadriver" (driver name notadriver doesn't exist.)"
HTTP: 404
Content-type: application/json

Will return a 404 error because that resource manager driver doesn’t exist

clustoapi.apps.resourcemanager.show(driver, manager)[source]¶

Shows the details of the given resource manager, if it is a resource manager

Examples:

$ ${post} -d 'name=nameman2' ${server_url}/resourcemanager/simplenamemanager
{
    "attrs": [
        ...
    ],
    "contents": [],
    "count": 0,
    "driver": "simplenamemanager",
    "name": "nameman2",
    "parents": [],
    "type": "resourcemanager"
}
HTTP: 201
Content-type: application/json

$ ${get} ${server_url}/resourcemanager/simplenamemanager/nameman1
{
    "attrs": [
        ...
    ],
    "contents": [],
    "count": 0,
    "driver": "simplenamemanager",
    "name": "nameman1",
    "parents": [],
    "type": "resourcemanager"
}
HTTP: 200
Content-type: application/json

Will create the nameman2 resource manager, then show its details. In this case both operations yield the same data.

$ ${get} ${server_url}/resourcemanager/simpleentitynamemanager/nonames
"Object "nonames" not found (nonames does not exist.)"
HTTP: 404
Content-type: application/json

Will return a 404 error since the resource manager wasn’t found

$ ${get} ${server_url}/resourcemanager/nomanager/testnames
"The driver "nomanager" is not a valid driver"
HTTP: 412
Content-type: application/json

Will return a 412 because the driver nomanager doesn’t exist

$ ${get} ${server_url}/resourcemanager/basicserver/testserver1
"The object "testserver1" is not a resource manager"
HTTP: 409
Content-type: application/json

Will return a 412 instead because even though the driver basicserver exists, it is not a resource manager driver