Session API

The bread and butter of Skaha is the Session API. This API allows you to create, destroy, and get information about your sessions on the CANFAR Science Platform.

---

Bases: SkahaClient

Skaha Session Management Client.

This class provides methods to manage sessions in the Skaha system, including fetching session details, creating new sessions, retrieving logs, and destroying existing sessions.

Parameters:

Name	Type	Description	Default
SkahaClient	SkahaClient	Base HTTP client for making API requests.	required

Examples:

Python Console Session

>>> from skaha.session import Session
>>> session = Session(
        timeout=120,
        concurrency=100, # <--- Has no effect on the sync client
        loglevel=40,
    )

create(name, image, cores=2, ram=4, kind='headless', gpu=None, cmd=None, args=None, env=None, replicas=1)

Launch a skaha session.

Parameters:

Name	Type	Description	Default
name	str	A unique name for the session.	required
image	str	Container image to use for the session.	required
cores	int	Number of cores. Defaults to 2.	2
ram	int	Amount of RAM (GB). Defaults to 4.	4
kind	str	Type of skaha session. Defaults to "headless".	'headless'
gpu	Optional[int]	Number of GPUs. Defaults to None.	None
cmd	Optional[str]	Command to run. Defaults to None.	None
args	Optional[str]	Arguments to the command. Defaults to None.	None
env	Optional[Dict[str, Any]]	Environment variables to inject. Defaults to None.	None
replicas	int	Number of sessions to launch. Defaults to 1.	1

Notes

The name of the session suffixed with the replica number. eg. test-1, test-2 Each container will have the following environment variables injected: * REPLICA_ID - The replica number * REPLICA_COUNT - The total number of replicas

Returns:

Type	Description
List[str]	List[str]: A list of session IDs for the launched sessions.

Examples:

Python Console Session

>>> from skaha.session import Session
>>> session = Session()
>>> session.create(
        name="test",
        image='images.canfar.net/skaha/terminal:1.1.1',
        cores=2,
        ram=8,
        gpu=1,
        kind="headless",
        cmd="env",
        env={"TEST": "test"},
        replicas=2,
    )
>>> ["hjko98yghj", "ikvp1jtp"]

destroy(ids)

Destroy skaha session[s].

Parameters:

Name	Type	Description	Default
ids	Union[str, List[str]]	Session ID[s].	required

Returns:

Type	Description
Dict[str, bool]	Dict[str, bool]: A dictionary of session IDs
Dict[str, bool]	and a bool indicating if the session was destroyed.

Examples:

Python Console Session

>>> from skaha.session import Session
>>> session = Session()
>>> session.destroy(id="hjko98yghj")
>>> session.destroy(id=["hjko98yghj", "ikvp1jtp"])

destroy_with(prefix, kind='headless', status='Succeeded')

Destroy skaha session[s] matching search criteria.

Parameters:

Name	Type	Description	Default
prefix	str	Prefix to match in the session name.	required
kind	KINDS	Type of skaha session. Defaults to "headless".	'headless'
status	STATUS	Status of the session. Defaults to "Succeeded".	'Succeeded'

Returns:

Type	Description
Dict[str, bool]	Dict[str, bool]: A dictionary of session IDs
Dict[str, bool]	and a bool indicating if the session was destroyed.

Notes

The prefix is case-sensitive. This method is useful for destroying multiple sessions at once.

Examples:

Python Console Session

>>> from skaha.session import Session
>>> session = Session()
>>> session.destroy_with(prefix="test")
>>> session.destroy_with(prefix="test", kind="desktop")
>>> session.destroy_with(prefix="test", kind="headless", status="Running")

fetch(kind=None, status=None, view=None)

List open sessions for the user.

Parameters:

Name	Type	Description	Default
kind	Optional[KINDS]	Session kind. Defaults to None.	None
status	Optional[STATUS]	Session status. Defaults to None.	None
view	Optional[VIEW]	Session view level. Defaults to None.	None

Notes

By default, only the calling user's sessions are listed. If views is set to 'all', all user sessions are listed (with limited information).

Returns:

Name	Type	Description
list	List[Dict[str, str]]	Sessions information.

Examples:

Python Console Session

>>> from skaha.session import Session
>>> session = Session()
>>> session.fetch(kind="notebook")
[{'id': 'ikvp1jtp',
  'userid': 'username',
  'image': 'images.canfar.net/image/label:latest',
  'type': 'notebook',
  'status': 'Running',
  'name': 'example-notebook',
  'startTime': '2222-12-14T02:24:06Z',
  'connectURL': 'https://skaha.example.com/ikvp1jtp',
  'requestedRAM': '16G',
  'requestedCPUCores': '2',
  'requestedGPUCores': '<none>',
  'coresInUse': '0m',
  'ramInUse': '101Mi'}]

info(ids)

Get information about session[s].

Parameters:

Name	Type	Description	Default
id	Union[List[str], str]	Session ID[s].	required

Returns:

Type	Description
List[Dict[str, Any]]	Dict[str, Any]: Session information.

Examples:

Python Console Session

>>> session.info(session_id="hjko98yghj")
>>> session.info(id=["hjko98yghj", "ikvp1jtp"])

logs(ids, verbose=False)

Get logs from a session[s].

Parameters:

Name	Type	Description	Default
ids	Union[List[str], str]	Session ID[s].	required
verbose	bool	Print logs to stdout. Defaults to False.	False

Returns:

Type	Description
Optional[Dict[str, str]]	Dict[str, str]: Logs in text/plain format.

Examples:

Python Console Session

>>> session.logs(id="hjko98yghj")
>>> session.logs(id=["hjko98yghj", "ikvp1jtp"])

stats()

Get statistics for the entire skaha cluster.

Returns:

Type	Description
Dict[str, Any]	Dict[str, Any]: Cluster statistics.

Examples:

Python Console Session

>>> from skaha.session import Session
>>> session = Session()
>>> session.stats()
{'instances': {
 'session': 88, 'desktopApp': 30, 'headless': 0, 'total': 118},
 'cores': {'requestedCPUCores': 377,
 'coresAvailable': 960,
 'maxCores': {'cores': 32, 'withRam': '147Gi'}},
 'ram': {'maxRAM': {'ram': '226Gi', 'withCores': 32}}}