Quick start

Before you can use the client, you need to create yourself an API token. Use the web console to create one. Keep this API token safe and for your eyes only. Save this token in a file which is readable for your user. Now, let’s start.

You can create an instance of the client with:

>>> from genesiscloud.client import Client
>>> client = Client(os.getenv("GENESISCLOUD_API_KEY"))

The client has one public method, with it, you can verify that the API key is working:

>>> client.connect()
<Response [200]>

If the API key is invalid, you will get an HTTP error code. The client has property for each GenesisCloud resources which allows you to do CRUD operations on these resources. Note that currently not all resources support all CRUD operations via the API. Nevertheless, the methods exist for all resources.

Each resource has the following methods get, find, list, create, delete:: The get methods accept one parameter, the resource id:

>>> client.Instances.get('ee7a8707-33ef-49ae-9930-a4fb10c1b16a')
Instance({'id': '86d7b549-930e-44d1-8a42-a483292adf63', 'name': 'folding@home via API 2', 'hostname': 'folding-at-home-api-2', 'type': 'vcpu-4_memory-12g_disk-80g_nvidia1080ti-1', 'allowed_actions': ['start', 'shutoff', 'reset'], 'ssh_keys': [{'id': 'd57521aa-36fd-4cbf-a1a1-8344391a7893', 'name': 'cschmidbauer@gc'}], 'image': {'id': 'edba720a-ba6b-4552-81eb-16fb91460e31', 'name': 'folding@home 1 gpu image'}, 'security_groups': [{'id': '2472c0bb-1fa9-4dcc-a658-4268e78ad907', 'name': 'default'}, {'id': 'd3040f01-3b12-4712-9e8e-8ecb1ae7ba04', 'name': 'standard'}, {'id': '56370632-ceeb-4357-a5d3-f2c3acf9d69e', 'name': 'Folding@home'}], 'status': 'active', 'private_ip': '192.168.10.108', 'public_ip': '194.61.20.206', 'created_at': '2020-03-26T18:49:18.771Z', 'updated_at': '2020-03-26T18:50:12.957Z'})

The get method always returns an instance of ItemView, which is special dictionary like class, which allows the user to convinietly to access attribute via dot notation. Some Instance properties are themselves ItemViews:

>>> instance = client.Instances.get('ee7a8707-33ef-49ae-9930-a4fb10c1b16a')
>>> instance.ssh_keys
[SSHKey({'id': 'd57521aa-36fd-4cbf-a1a1-8344391a7893', 'name': 'cschmidbauer@gc'})]
>>> instance.security_groups
[SecurityGroup({'id': '2472c0bb-1fa9-4dcc-a658-4268e78ad907', 'name': 'default'}), SecurityGroup({'id': 'd3040f01-3b12-4712-9e8e-8ecb1ae7ba04', 'name': 'standard'}), SecurityGroup({'id': '56370632-ceeb-4357-a5d3-f2c3acf9d69e', 'name': 'Folding@home'})]
>>> instance.security_groups[0].name
'default'

The list method returns a lazy generator to list all the resources or filter some:

>>> client.SecurityGroups.list()
<generator object GenesisResource.__list at 0x7f97f9405b48>
>>> list(client.SecurityGroups.list())
[SecurityGroup({'id': 'd3040f01-3b12-4712-9e8e-8ecb1ae7ba04', 'name': 'standard', 'description': 'The recommended security group default applied by Genesis Cloud', 'created_at': '2019-11-21T13:43:22.824Z'}), SecurityGroup({'id': '258afd7b-fb40-439b-b146-b1dcdbfead8c', 'name': 'iperf', 'description': 'iperf default port settings', 'created_at': '2020-01-12T22:15:35.871Z'}), SecurityGroup({'id': 'f26a9bec-c254-4804-843e-d3d179464ec2', 'name': 'outbound-fully-opened', 'description': '', 'created_at': '2020-01-14T10:00:02.371Z'}), SecurityGroup({'id': '56370632-ceeb-4357-a5d3-f2c3acf9d69e', 'name': 'Folding@home', 'description': '', 'created_at': '2020-03-04T14:04:28.004Z'}), SecurityGroup({'id': '2781a739-bdd2-44b7-ac3a-9d1d38999738', 'name': 'VNC', 'description': '', 'created_at': '2020-05-03T17:23:00.822Z'}), SecurityGroup({'id': '8a8472a3-9af8-4f7e-a0fc-d8f7b40fa56c', 'name': 'cao-test', 'description': '', 'created_at': '2020-05-08T01:43:41.109Z'})]

The list method accepts paremters for page number and number of items per page:

>>> list(client.SecurityGroups.list(page=2, item=40))

The find method allows one to search for specific resources:

>>> list(client.SecurityGroups.find({'name': 'standard'}))
<generator object GenesisResource.find at 0x7f97f9405b48>
>>> list(client.SecurityGroups.find({'name': 'standard'}))
[SecurityGroup({'id': 'd3040f01-3b12-4712-9e8e-8ecb1ae7ba04', 'name': 'standard', 'description': 'The recommended security group default applied by Genesis Cloud', 'created_at': '2019-11-21T13:43:22.824Z'})]

The delete method allowed one to delete a specific resource using the id of the resource (currently only Snapshots and Instances):

>>> client.Instances.delete('ee7a8707-33ef-49ae-9930-a4fb10c1b16a')

These are the basics of using the client. In the next chapter, you can see a fully working example.