Programmatic instance management

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

Prerequisites

Overview of example scripts

1

Add an SSH key

The script reads the public key located at ~/.ssh/id_rsa.pub, then sends a request to the Add an SSH key endpoint to add 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.
2

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.

3

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.

5

Terminate the instance

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

6

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.

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.

1import requests
2from pathlib import Path
3import time
4import json
5
6base_url = 'https://platform.fluidstack.io/'
7api_key = 'api_key_j123My_FakeAPIKey'
8
9# Set the API key in a header
10headers = {
11 'api-key': api_key,
12 'Content-Type': 'application/json'
13}
14
15# 1: Add an SSH key
16print('Adding SSH key')
17
18# Read the public key from ~/.ssh/id_rsa.pub
19public_key = Path.home().joinpath('.ssh', 'id_rsa.pub').read_text().strip()
20
21ssh_key_name = 'python_ssh_key'
22
23# Send POST request to /ssh_keys
24response = 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
34if not response.ok:
35 raise Exception('Could not add SSH key')
36
37# 2: Create an instance
38print('Creating instance')
39
40# Send POST request to /instances
41created_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
51print('Response: ' + json.dumps(created_instance.json(), indent=2))
52if not created_instance.ok:
53 raise Exception('Could not create instance')
54
55instance_id = created_instance.json()['id']
56
57status = 'pending'
58print('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'
62count = 1
63while 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
79print('Instance IP address: ' + instance['ip_address'])
80
81# 5: Terminate the instance
82print('Terminating instance')
83
84# Send DELETE request to /instances/{instance_id}
85response = requests.delete(base_url + f'instances/{instance_id}', headers=headers)
86if not response.ok:
87 print('Response: ' + json.dumps(response.json(), indent=2))
88 raise Exception('Could not delete instance')
89print('Instance deleted')
90
91# 6: Delete the public SSH key that was added to the account
92response = requests.delete(base_url + f'ssh_keys/{ssh_key_name}', headers=headers)
93if not response.ok:
94 print('Response: ' + json.dumps(response.json(), indent=2))
95 raise Exception('Could not delete the SSH key')
96print('SSH key deleted')

Cleanup

The script adds 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?