Skip to content

Dev: Python Client API

Jump to bottom
Nils Philippsen edited this page Jun 23, 2022 · 1 revision

Installation

In order to use the Duffy client from Python, install the duffy Python package with the client extra, e.g.:

pip --user install 'duffy[client]'

Usage

The DuffyClient Class

The DuffyClient class encapsulates common client operations on the Duffy API.

Example

Set it up once like this (Set the url, auth_name and auth_tenant parameters appropriately):

>>> from duffy.client import DuffyClient
>>> client = DuffyClient(url="http://localhost:8080/api/v1", auth_name="tenant", auth_key="00000000-0000-0000-0000-00000000")

The remotely executed methods return validated pydantic model objects which expose the validated contents as object properties. They contain additional methods to convert results to plain dict objects or JSON strings.

List Available Pools – DuffyClient.list_pools()

Listing pools returns information about the names of pools and their configured fill levels (i.e. how many should be kept in a ready state to be handed out).

Example 
...
>>> client.list_pools()
PoolResultCollection(action=<APIResultAction.get: 'get'>, pools=[PoolConciseModel(name='physical-centos8Stream-x86_64', fill_level=5), PoolConciseModel(name='physical-centos9Stream-x86_64', fill_level=5)])
>>> client.list_pools().pools[0].name
'physical-centos8Stream-x86_64'

Show Details of a Single Pool – DuffyClient.show_pool()

Additional dynamic information can be queried about single pools.

Example 
...
>>> client.show_pool("physical-centos8Stream-x86_64").dict()
{'action': <APIResultAction.get: 'get'>, 'pool': {'name': 'physical-centos8Stream-x86_64', 'fill_level': 5, 'levels': {'provisioning': 0, 'ready': 0, 'contextualizing': 0, 'deployed': 0, 'deprovisioning': 0}}}

Request a Session – DuffyClient.request_session()

Nodes of different kinds can be requested in a session. The argument to DuffyClient.request_session() is a list of node specifications which are dictionaries specifying the pool and the quantity of nodes from that pool which are needed.

Example 
...
>>> client.request_session([{"pool": "physical-centos8Stream-x86_64", "quantity": 1}])
SessionResult(action=<APIResultAction.post: 'post'>, session=SessionModel(retired_at=None, active=True, created_at=datetime.datetime(2022, 6, 20, 16, 54, 30, 315713, tzinfo=datetime.timezone.utc), id=42, expires_at=datetime.datetime(2022, 6, 20, 22, 54, 30, 515861, tzinfo=datetime.timezone.utc), tenant=TenantModel(retired_at=None, active=True, created_at=datetime.datetime(2022, 3, 8, 9, 52, 48, 863742, tzinfo=datetime.timezone.utc), name='tenant', is_admin=False, ssh_key=SecretStr('**********'), node_quota=None, session_lifetime=None, session_lifetime_max=None, id=1, effective_node_quota=10, effective_session_lifetime=datetime.timedelta(seconds=21600), effective_session_lifetime_max=datetime.timedelta(seconds=43200)), data={'nodes_specs': [{'quantity': 1, 'pool': 'physical-centos8Stream-x86_64'}]}, nodes=[SessionNodeModel(hostname='wombat.tiptoe.de', ipaddr=IPv4Address('10.0.0.2'), comment=None, pool='physical-centos8Stream-x86_64', reusable=True, data={'architecture': 'x86_64', 'nodes_spec': {'quantity': 1, 'pool': 'physical-centos8Stream-x86_64'}}, id=77, state='deployed')]))

Retire a Session – DuffyClient.retire_session()

After a session has run its course, retire it. This frees up allocated resources, i.e. lets reusable nodes (e.g. physical machines) be reinstalled or virtual machines be terminated.

Example 
...
>>> client.retire_session(session_id=42)
SessionResult(action=<APIResultAction.put: 'put'>, session=SessionModel(retired_at=datetime.datetime(2022, 6, 20, 17, 0, 58, 368673, tzinfo=datetime.timezone.utc), active=False, created_at=datetime.datetime(2022, 6, 20, 16, 54, 30, 315713, tzinfo=datetime.timezone.utc), id=42, expires_at=datetime.datetime(2022, 6, 20, 22, 54, 30, 515861, tzinfo=datetime.timezone.utc), tenant=TenantModel(retired_at=None, active=True, created_at=datetime.datetime(2022, 3, 8, 9, 52, 48, 863742, tzinfo=datetime.timezone.utc), name='tenant', is_admin=False, ssh_key=SecretStr('**********'), node_quota=None, session_lifetime=None, session_lifetime_max=None, id=1, effective_node_quota=10, effective_session_lifetime=datetime.timedelta(seconds=21600), effective_session_lifetime_max=datetime.timedelta(seconds=43200)), data={'nodes_specs': [{'quantity': 1, 'pool': 'physical-centos8Stream-x86_64'}]}, nodes=[SessionNodeModel(hostname='wombat.tiptoe.de', ipaddr=IPv4Address('10.0.0.2'), comment=None, pool='physical-centos8Stream-x86_64', reusable=True, data={'architecture': 'x86_64', 'nodes_spec': {'quantity': 1, 'pool': 'physical-centos8Stream-x86_64'}}, id=77, state=None)]))
Clone this wiki locally