Programmatic instance management

The Python and TypeScript scripts on this page demonstrates how the FluidStack API can be used to manage instances programmatically, with or without using one of our SDKs.

Prerequisites

An API key
A public/private key pair
(for Python) Basic familiarity with Python; Python 3+ installed
(for TypeScript) Basic familiarity with TypeScript; Node 18+ installed; a way to run TypeScript code locally

Overview of example scripts

Without SDK

With SDK

Create an SSH key

The script reads the public key located at ~/.ssh/id_rsa.pub, then sends a request to the Create an SSH key endpoint to create an SSH key. This key will be named either python_ssh_key or typescript_ssh_key and is a copy of the public key that was read.

Warning

If you already have an SSH key on your FluidStack account named python_ssh_key or typescript_ssh_key, change the script to use a different, unique name. Alternatively, delete the existing key.
If your public key is in a different location or filename, make sure to update that part of the script.

Create an instance

The script creates an instance by sending a request to the Create a new instance endpoint.

The API key is sent in the request as a header. A custom name for the instance, the GPU type, and the name of the SSH key to use for accessing the instance are sent in the JSON body of the request.

Check the instance status

Initially, the instance’s status is pending. The script repeatedly checks this status until it is running by sending requests to the Fetch a single user instances endpoint and parsing the response.

This status-checking loop stops once the instance’s status returns as running, or if its status indicates that it has been terminated or is otherwise unable to run.

Print the instance IP

Once the instance’s status is running, the script prints the instance’s IP address.

Terminate the instance

The script uses the Terminate an instance endpoint to delete the instance.

Delete the SSH key on the account

Finally, the script also deletes the public SSH key that was added to the account.

Example scripts

Warning

Avoid placing your API key in any file that might be shared with others. For information on using a .env file instead of adding the API key directly into a file, see: API Overview - Secure use of your API key.

Python

Python SDK

TypeScript

TypeScript SDK

Before you run this script, replace the api_key value on line 7 with your own. You must also install the requests library into your environment.

1 import requests
2 from pathlib import Path
3 import time
4 import json
5 
6 base_url = 'https://platform.fluidstack.io/'
7 api_key = 'api_key_j123My_FakeAPIKey'
8 
9 # Set the API key in a header
10 headers = {
11     'api-key': api_key,
12     'Content-Type': 'application/json'
13 }
14 
15 # 1: Create an SSH key
16 print('Creating SSH key')
17 
18 # Read the public key from ~/.ssh/id_rsa.pub
19 public_key = Path.home().joinpath('.ssh', 'id_rsa.pub').read_text().strip() 
20 
21 ssh_key_name = 'python_ssh_key'
22 
23 # Send POST request to /ssh_keys
24 response = requests.post(
25     base_url + 'ssh_keys',
26     headers=headers,
27     json={
28         'name': ssh_key_name,
29         'public_key': public_key
30     },
31 )
32 
33 # Print response body if the response status code is not OK
34 if not response.ok:
35     raise Exception('Could not create SSH key')
36 
37 # 2: Create an instance 
38 print('Creating instance')
39 
40 # Send POST request to /instances
41 created_instance = requests.post(
42     base_url + 'instances',
43     headers=headers,
44     json={
45         'name': 'python_test_instance',
46         'gpu_type': 'RTX_A6000_48GB',
47         'ssh_key': ssh_key_name,
48     },
49 )
50 
51 print('Response: ' + json.dumps(created_instance.json(), indent=2))
52 if not created_instance.ok:
53     raise Exception('Could not create instance')
54 
55 instance_id = created_instance.json()['id']
56 
57 status = 'pending'
58 print('Waiting for instance to start')
59 
60 # 3: Check the instance status using GET /instances/{instance_id}
61 # Check status every 10 seconds, exit when status is 'running'
62 count = 1
63 while status != 'running':
64     if status != 'pending':
65         print('Could not create instance')
66         raise Exception('Could not create instance')
67     try:
68         # Send GET request to /instances/{instance_id}
69         response = requests.get(base_url + f'instances/{instance_id}', headers=headers)
70         instance = response.json()
71         status = instance['status']
72     except Exception as e:
73         print(e)
74     print(f'\t [{count}] Status: {status}')
75     time.sleep(10)
76     count += 1
77 
78 # 4: Print the instance IP
79 print('Instance IP address: ' + instance['ip_address'])
80 
81 # 5: Terminate the instance
82 print('Terminating instance')
83 
84 # Send DELETE request to /instances/{instance_id}
85 response = requests.delete(base_url + f'instances/{instance_id}', headers=headers)
86 if not response.ok:
87     print('Response: ' + json.dumps(response.json(), indent=2))
88     raise Exception('Could not delete instance')
89 print('Instance deleted')
90 
91 # 6: Delete the public SSH key that was added to the account
92 response = requests.delete(base_url + f'ssh_keys/{ssh_key_name}', headers=headers)
93 if not response.ok:
94     print('Response: ' + json.dumps(response.json(), indent=2))
95     raise Exception('Could not delete the SSH key')
96 print('SSH key deleted')

Cleanup

The script creates and deletes an SSH key and instance on the account associated with the provided API key.

In case you ran into any issues with the script, confirm that the instance was deleted. If it was not deleted, stop or delete it manually to avoid incurring charges.

If the SSH key on the account created by the script was not deleted, you must remove it manually before you can run the script again.

What’s next?

Learn more about how to use the Python SDK.
View the full API reference.
Find out more about how to use SSH, including how to log into an instance.

1	import requests
2	from pathlib import Path
3	import time
4	import json
5
6	base_url = 'https://platform.fluidstack.io/'
7	api_key = 'api_key_j123My_FakeAPIKey'
8
9	# Set the API key in a header
10	headers = {
11	'api-key': api_key,
12	'Content-Type': 'application/json'
13	}
14
15	# 1: Create an SSH key
16	print('Creating SSH key')
17
18	# Read the public key from ~/.ssh/id_rsa.pub
19	public_key = Path.home().joinpath('.ssh', 'id_rsa.pub').read_text().strip()
20
21	ssh_key_name = 'python_ssh_key'
22
23	# Send POST request to /ssh_keys
24	response = requests.post(
25	base_url + 'ssh_keys',
26	headers=headers,
27	json={
28	'name': ssh_key_name,
29	'public_key': public_key
30	},
31	)
32
33	# Print response body if the response status code is not OK
34	if not response.ok:
35	raise Exception('Could not create SSH key')
36
37	# 2: Create an instance
38	print('Creating instance')
39
40	# Send POST request to /instances
41	created_instance = requests.post(
42	base_url + 'instances',
43	headers=headers,
44	json={
45	'name': 'python_test_instance',
46	'gpu_type': 'RTX_A6000_48GB',
47	'ssh_key': ssh_key_name,
48	},
49	)
50
51	print('Response: ' + json.dumps(created_instance.json(), indent=2))
52	if not created_instance.ok:
53	raise Exception('Could not create instance')
54
55	instance_id = created_instance.json()['id']
56
57	status = 'pending'
58	print('Waiting for instance to start')
59
60	# 3: Check the instance status using GET /instances/{instance_id}
61	# Check status every 10 seconds, exit when status is 'running'
62	count = 1
63	while status != 'running':
64	if status != 'pending':
65	print('Could not create instance')
66	raise Exception('Could not create instance')
67	try:
68	# Send GET request to /instances/{instance_id}
69	response = requests.get(base_url + f'instances/{instance_id}', headers=headers)
70	instance = response.json()
71	status = instance['status']
72	except Exception as e:
73	print(e)
74	print(f'\t [{count}] Status: {status}')
75	time.sleep(10)
76	count += 1
77
78	# 4: Print the instance IP
79	print('Instance IP address: ' + instance['ip_address'])
80
81	# 5: Terminate the instance
82	print('Terminating instance')
83
84	# Send DELETE request to /instances/{instance_id}
85	response = requests.delete(base_url + f'instances/{instance_id}', headers=headers)
86	if not response.ok:
87	print('Response: ' + json.dumps(response.json(), indent=2))
88	raise Exception('Could not delete instance')
89	print('Instance deleted')
90
91	# 6: Delete the public SSH key that was added to the account
92	response = requests.delete(base_url + f'ssh_keys/{ssh_key_name}', headers=headers)
93	if not response.ok:
94	print('Response: ' + json.dumps(response.json(), indent=2))
95	raise Exception('Could not delete the SSH key')
96	print('SSH key deleted')