SlipStream Python API documentation

Python wrapper of the SlipStream API (http://ssapi.sixsq.com).

Install

Latest release from pypi

$ pip install slipstream-api

Most recent version from source code

$ pip install 'https://github.com/slipstream/SlipStreamPythonAPI/archive/master.zip'

Usage

To use this library, import it and instanciate it. Then use one of the method to login.:

from slipstream.api import Api

api = Api()

api.login_internal('username', 'password')

Examples

Login on Nuvla with username and password

api.login_internal('username', 'password')

Login on Nuvla with key and secret

api.login_apikey('credential/ce02ef40-1342-4e68-838d-e1b2a75adb1e', 
                 'the-secret-key')

List applications from the App Store

from pprint import pprint as pp
pp(list(api.list_applications()))

List base images

from pprint import pprint as pp
pp(list(api.list_project_content('examples/images')))

Simple component deployment (WordPress server)

# Deploy the WordPress component
deployment_id = api.deploy('apps/WordPress/wordpress')

Complete application deployment (WordPress server)

# Cloud
cloud = 'exoscale-ch-gva'

# WordPress Title
wordpress_title = 'WordPress deployed by SlipStream through SlipStreamPythonAPI'

# Create the dict of parameters to (re)define
parameters = dict(wordpress_title=wordpress_title)

# Deploy the WordPress component
deployment_id = api.deploy('apps/WordPress/wordpress', cloud, parameters)

# Wait the deployment to be ready
while api.get_deployment(deployment_id).status != 'ready': time.sleep(10)

# Print the WordPress URL
print api.get_deployment(deployment_id).service_url

# Print the WordPress admin username and password
print api.get_deployment_parameter(deployment_id, 'machine:admin_email')
print api.get_deployment_parameter(deployment_id, 'machine:admin_password')

Terminate a deployment

api.terminate(deployment_id)

API documentation

class api.api.Api(endpoint=’https://nuv.la’, cookie_file=None, insecure=False, reauthenticate=False)[source]

This class is a Python wrapper&helper of the native SlipStream REST API

add_node_instances(deployment_id, node_name, quantity=None)[source]

Add new instance(s) of a deployment’s node (horizontal scale up).

Warning: The targeted deployment has to be “scalable”.

Parameters:
  • deployment_id (str|UUID) – The deployment UUID of the deployment on which to add new instances of a node.
  • node_name (str) – Name of the node where to add instances.
  • quantity (int) – Amount of node instances to add. If not provided it’s server dependent (usually add one instance)
Returns:

The list of new node instance names.
Return type:

list
build_component(path, cloud=None)[source]
Parameters:
  • path (str) – The path to a component
  • cloud (str) – The Cloud on which to build the component. If None, the user default Cloud will be used.
cimi_add(resource_type, data)[source]

Add a CIMI resource to the specified resource_type (Collection)

Parameters:
  • resource_type (str) – Type of the resource (Collection name)
  • data (dict) – The data to serialize into JSON
Returns:

A CimiResponse object which should contain the attributes ‘status’, ‘resource-id’ and ‘message’
Return type:

CimiResponse
cimi_delete(resource_id)[source]

Delete a CIMI resource by it’s resource id

Parameters:resource_id (str) – The id of the resource to delete
Returns:A CimiResponse object which should contain the attributes ‘status’, ‘resource-id’ and ‘message’
Return type:CimiResponse
cimi_edit(resource_id, data)[source]

Edit a CIMI resource by it’s resource id

Parameters:
  • resource_id (str) – The id of the resource to edit
  • data (dict) – The data to serialize into JSON
Returns:

A CimiResponse object which should contain the attributes ‘status’, ‘resource-id’ and ‘message’
Return type:

CimiResponse
cimi_get(resource_id)[source]

Retreive a CIMI resource by it’s resource id

Parameters:resource_id (str) – The id of the resource to retrieve
Returns:A CimiResource object corresponding to the resource
cimi_operation(resource_id, operation, data=None)[source]

Execute an operation on a CIMI resource

Parameters:
  • resource_id (str) – The id of the resource to execute operation on
  • operation (str) – Operation name (e.g. describe)
  • data (dict) – The data to serialize into JSON
Returns:

A CimiResponse object which should contain the attributes ‘status’, ‘resource-id’ and ‘message’
Return type:

CimiResponse

Search for CIMI resources of the given type (Collection).

Parameters:
  • resource_type (str) – Type of the resource (Collection name)
  • first (int) – Start from the ‘first’ element (1-based)
  • last (int) – Stop at the ‘last’ element (1-based)
  • filter (str) – CIMI filter
  • select (str or list of str) – Select attributes to return. (resourceURI always returned)
  • expand (str or list of str) – Expand linked resources (not implemented yet)
  • orderby (str or list of str) – Sort by the specified attribute
  • aggregation (str (operator:field)) – CIMI aggregation
Returns:

A CimiCollection object with the list of found resources available as a generator with the method ‘resources()’ or with the attribute ‘resources_list’
Return type:

CimiCollection
create_user(username, password, email, first_name, last_name, organization=None, roles=None, privileged=False, default_cloud=None, default_keep_running=’never’, ssh_public_keys=None, log_verbosity=1, execution_timeout=30, usage_email=’never’, cloud_parameters=None)[source]

Create a new user into SlipStream.

Parameters:
  • username (str) – The user’s username (need to be unique)
  • password (str) – The user’s password
  • email (str) – The user’s email address
  • first_name (str) – The user’s first name
  • last_name (str) – The user’s last name
  • organization (str|None) – The user’s organization/company
  • roles (list) – The user’s roles
  • privileged (bool) – true to create a privileged user, false otherwise
  • default_cloud (str|None) – The user’s default Cloud
  • default_keep_running (‘always’ or ‘never’ or ‘on-success’ or ‘on-error’) – The user’s default setting for keep-running.
  • ssh_public_keys (str|None) – The SSH public keys to inject into deployed instances. One key per line.
  • log_verbosity (0 or 1 or 2 or 3) – The verbosity level of the logging inside instances. 0: Actions, 1: Steps, 2: Details, 3: Debugging
  • execution_timeout (int) – If a deployment stays in a transitionnal state for more than this value (in minutes) it will be forcefully terminated.
  • usage_email (‘never’ or ‘daily’) – Set it to ‘daily’ if you want to receive daily email with a summary of your Cloud usage of the previous day.
  • cloud_parameters (dict|None) – To add Cloud specific parameters (like credentials). A dict with the cloud name as the key and a dict of parameter as the value.
current_session()[source]

Returns current user session or None.

Returns:Current user session.
Return type:str
delete_element(path)[source]

Delete a project, a component or an application

Parameters:path – The path to a component or an application
deploy(path, cloud=None, parameters=None, tags=None, keep_running=None, scalable=False, multiplicity=None, tolerate_failures=None, check_ssh_key=False, raw_params=None)[source]

Run a component or an application

Parameters:
  • path (str) – The path of the component/application to deploy
  • cloud (str or dict) – A string or a dict to specify on which Cloud(s) to deploy the component/application. To deploy a component simply specify the Cloud name as a string. To deploy a deployment specify a dict with the nodenames as keys and Cloud names as values. If not specified the user default cloud will be used.
  • parameters (dict) – A dict of parameters to redefine for this deployment. To redefine a parameter of a node use “<nodename>” as keys and dict of parameters as values. To redefine a parameter of a component or a global parameter use “<parametername>” as the key.
  • tags (str or list) – List of tags that can be used to identify or annotate a deployment
  • keep_running (‘always’ or ‘never’ or ‘on-success’ or ‘on-error’) – [Only applies to applications] Define when to terminate or not a deployment when it reach the ‘Ready’ state. Possibles values: ‘always’, ‘never’, ‘on-success’, ‘on-error’. If scalable is set to True, this value is ignored and it will behave as if it was set to ‘always’. If not specified the user default will be used.
  • scalable (bool) – [Only applies to applications] True to start a scalable deployment. Default: False
  • multiplicity (dict) – [Only applies to applications] A dict to specify how many instances to start per node. Nodenames as keys and number of instances to start as values.
  • tolerate_failures (dict) – [Only applies to applications] A dict to specify how many failures to tolerate per node. Nodenames as keys and number of failure to tolerate as values.
  • check_ssh_key (bool) – Set it to True if you want the SlipStream server to check if you have a public ssh key defined in your user profile. Useful if you want to ensure you will have access to VMs.
  • raw_params (dict) – This allows you to pass parameters directly in the request to the SlipStream server. Keys must be formatted in the format understood by the SlipStream server.
Returns:

The deployment UUID of the newly created deployment
Return type:

uuid.UUID
get_application_nodes(path)[source]

Get nodes of an application :param path: The path of an application :type path: str

get_cloud_image_identifiers(path)[source]

Get all image identifiers associated to a native component

Parameters:path (str) – The path of an component
get_deployment(deployment_id)[source]

Get a deployment

Parameters:deployment_id (str or UUID) – The deployment UUID of the deployment to get
get_deployment_parameter(deployment_id, parameter_name, ignore_abort=False)[source]

Get a parameter of a deployment

Parameters:
  • deployment_id (str or UUID) – The deployment UUID of the deployment to get
  • parameter_name (str) – The parameter name (eg: ss:state)
  • ignore_abort (bool) – If False, raise an exception if the deployment has failed
get_element(path)[source]

Get details about a project, a component or an application

Parameters:path (str) – The path of an element (project/component/application)
get_parameters(path, parameter_name=None, parameter_names=None)[source]

Get all or a subset of the parameters associated to a project, a component or an application

Parameters:
  • path (str) – The path of an element (project/component/application)
  • parameter_name (str|None) – The parameter name (eg: ‘cpu.nb’)
  • parameter_names (list|None) – The list of parameter names (eg: [‘cpu.nb’, ‘ram.GB’, ])
Returns:

A list containing all the parameters, or at most the one requested
Return type:

list
get_user(username=None)[source]

Get informations for a given user, if permitted

Parameters:username – The username of the user. Default to the user logged in if not provided or None.
list_applications()[source]

List apps in the appstore

list_deployments(inactive=False, cloud=None, offset=0, limit=20)[source]

List deployments

Parameters:
  • inactive – Include inactive deployments. Default to False
  • cloud (str) – Retrieve only deployments for the specified Cloud
  • offset (int) – Retrieve deployments starting by the offset<exp>th</exp> one. Default to 0
  • limit (int) – Retrieve at most ‘limit’ deployments. Default to 20
list_project_content(path=None, recurse=False)[source]

List the content of a project

Parameters:
  • path (str) – The path of a project. If None, list the root project.
  • recurse (bool) – Get project content recursively
list_users()[source]

List users (requires privileged access)

list_virtualmachines(deployment_id=None, cloud=None, offset=0, limit=20)[source]

List virtual machines

Parameters:
  • deployment_id (str or UUID) – Retrieve only virtual machines about the specified run_id. Default to None
  • cloud (str) – Retrieve only virtual machines for the specified Cloud
  • offset (int) – Retrieve virtual machines starting by the offset<exp>th</exp> one. Default to 0
  • limit (int) – Retrieve at most ‘limit’ virtual machines. Default to 20
login(login_params)[source]

Uses given ‘login_params’ to log into the SlipStream server. The ‘login_params’ must be a map containing an “href” element giving the id of the sessionTemplate resource and any other attributes required for the login method. E.g.:

{“href” : “session-template/internal”,
“username” : “username”, “password” : “password”} or
{“href” : “session-template/api-key”,
“key” : “key”, “secret” : “secret”}

Returns server response as dict. Successful responses will contain a status code of 201 and the resource-id of the created session.

Parameters:login_params (dict) – {“href”: “session-template/…”, <creds>}
Returns:Server response.
Return type:dict
login_apikey(key, secret)[source]

Login to the server using API key/secret pair.

Parameters:
  • key – The Key ID (resource id). (example: credential/ce02ef40-1342-4e68-838d-e1b2a75adb1e)
  • secret – The Secret Key corresponding to the Key ID
Returns:

see login()
login_internal(username, password)[source]

Login to the server using username and password.

Parameters:
  • username –
  • password –
Returns:

see login()
logout()[source]

Logs user out by deleting session.

publish(path)[source]

Publish a component or an application to the appstore

Parameters:path – The path to a component or an application
remove_node_instances(deployment_id, node_name, ids)[source]

Remove a list of node instances from a deployment.

Warning: The targeted deployment has to be “scalable”.

Parameters:
  • deployment_id (str|UUID) – The deployment UUID of the deployment on which to remove instances of a node.
  • node_name (str) – Name of the node where to remove instances.
  • ids (list|str) – List of node instance ids to remove. Ids can also be provided as a CSV list.
Returns:

True on success
Return type:

bool
terminate(deployment_id)[source]

Terminate a deployment

Parameters:deployment_id (str or uuid.UUID) – The UUID of the deployment to terminate
unpublish(path)[source]

Unpublish a component or an application from the appstore

Parameters:path – The path to a component or an application
update_component(path, description=None, module_reference_uri=None, cloud_identifiers=None, keep_ref_uri_and_cloud_ids=False, logo_link=None)[source]

Update a component, when a parameter is not provided in parameter it is unchanged.

Parameters:
  • path (str) – The path of a component
  • description (str) – Description of the component
  • module_reference_uri (str) – URI of the parent component
  • cloud_identifiers (dict) – A dict where keys are cloud names and values are identifier of the image in the cloud
  • keep_ref_uri_and_cloud_ids (bool) – Don’t remove module_reference_uri if any cloud identifier are provided, or don’t remove cloud identifiers if a module_reference_uri is provided
  • logo_link (str) – URL to an image that should be used as logo
update_user(username=None, password=None, email=None, first_name=None, last_name=None, organization=None, roles=None, privileged=None, default_cloud=None, default_keep_running=None, ssh_public_keys=None, log_verbosity=None, execution_timeout=None, usage_email=None, cloud_parameters=None)[source]

Update an existing user in SlipStream. Any parameter provided will be updated, others parameters will not be touched.

Parameters are identical to the ones of the method ‘create_user’ except that they can all be None.

Username cannot be updated. This parameter define which user to update. If not provided or None the current user will be used

usage()[source]

Get current usage and quota by cloud service.

class api.api.SessionStore(endpoint, reauthenticate, cookie_file=None)[source]

A requests.Session subclass implementing a file-based session store.

clear(domain)[source]

Clear cookies for the specified domain.

Indices and tables