sixsq.slipstream.client.api.run

Purpose

The run namespace contains functions for interacting with SlipStream runs.

It allows users to

  • Scale the components of the running application up and down,
  • Query the state of the run,
  • Query and set parameters of the application components and their instances,
  • Query parameters from global namespace (ss:), and
  • Terminate the run.

Timeouts and intervals are in seconds.

SlipStraem run termininology

There are three types of parameters on a run

  • Global parameter - ss:tags
  • Application component parameter - webapp:ids
  • Application component instance parameter - webapp.1:hostname

where

  • ss is the global namespace of the run,
  • webapp is the name of the application component, which is referred to as comp in the API,
  • webapp.1 is the name of the instance 1 of the application component webapp.

Usage and examples

The namespace can be bootstrapped either from slipstream.context file (in .ini format) or by explicitly providing the configuration to contextualize!.

In the case of slipstream.context, the following structure and parameters are assumed

[contextualization]

# SlipStream endpoint.
serviceurl = https://nuv.la

# SlipStream user credentials
username = foo
password = bar

# preferred over username and password
cookie = key=val; Path:/

# run UUID
diid = 123

This file is usually available on SlipStream managed VMs and is used by orchestrator and node executors.

First call to any of the API functions searches and loads the contextualisation file. All successive calls use the locally bound configuration.

Explicitly calling contextualize! w/o parameters reload the contextualization and updates the configuration of the namespace.

contextualize! can be called with a context map

{:serviceurl "https://nuv.la"

 ;; run UUID
 :diid "123"

 :cookie "key=val; Path:/"

 :username "foo"
 :password "bar"}

where either :cookie or :username and :password are mandatory.

Examples

Implicit bootstrap – slipstream.context with the correct parameters should be in the search path.

(require '[sixsq.slipstream.client.api.run :as r])

(r/get-run-info)

Manually define configuration and contextualize the namespace.

(require '[sixsq.slipstream.client.api.run :as r])

(def conf {:serviceurl "https://nuv.la"
           :diid "123-456"
           :username "foo"
           :password "bar"})
(rw/contextualize! conf)

(r/get-run-info)

*context*

dynamic

aborted?

(aborted?)

Check if run is in ‘Aborted’ state.

action-scale-down-at

(action-scale-down-at comp ids & [& {:keys [timeout], :or {timeout wait-timeout-default}}])

Scale down application component ‘comp’ by terminating the component instances identified by IDs in ‘ids’. Wait for the completion of the action.

action-scale-down-by

(action-scale-down-by comp n & [& {:keys [timeout], :or {timeout wait-timeout-default}}])

Scale down application component ‘comp’ by ‘n’ instances. Wait for the completion of the action.

action-scale-up

(action-scale-up comp n & [& {:keys [params timeout], :or {params {}, timeout wait-timeout-default}}])

Scale application component ‘comp’ by ‘n’ instances up. Wait for the completion of the action. Optionally provide map of parameters as ‘params’.

action-success?

(action-success? result)

Given the ‘result’ returned by an action, check if it was successfull.

can-scale?

(can-scale?)

Check if it’s possible to scale the run.

cancel-abort

(cancel-abort)

Cancel abort on the run.

contextualize!

(contextualize!)(contextualize! context)

get-abort

(get-abort)

Get abort message.

get-comp-ids

(get-comp-ids comp)

Get list of instance IDs of application component ‘comp’.

get-multiplicity

(get-multiplicity comp)

Get multiplicity of application component ‘comp’.

get-param

(get-param comp id param)

Get parameter ‘param’ of application component instance ‘comp.id’ as ‘comp.id:param’. When ‘id’ is nil, gets parameter of the application component as ‘comp:param’.

get-run-info

(get-run-info)

get-scale-state

(get-scale-state comp id)

Get scale state of the component instance.

get-state

(get-state)

Get state of the run.

run-uuid

(run-uuid)

scalable?

(scalable?)

Check if run is scalable.

scale-down

(scale-down comp ids)

Scale down application component ‘comp’ by terminating instances defined by ‘ids’ vector.

scale-up

(scale-up comp n)(scale-up comp n params)

Scale up application component ‘comp’ by ‘n’ instances. Allow to set parameters from ‘params’ map on the new component instances. Returns list of added component instance names qualified with IDs.

set-param

(set-param comp id param value)

Set parameter ‘param’ to ‘value’ on application component instance ‘comp.id’.

set-params

(set-params comp id params)

Given a map of parameters ‘params’, set them on application component instance ‘comp.id’.

terminate

(terminate)

Terminate the run.

wait-ready

(wait-ready)(wait-ready timeout)

Waits for Ready state on the run. Returns true on success.

wait-timeout-default