Volumes provide persistent block storage that can be attached to instances for storing data independently of the instance lifecycle. This makes them ideal for scenarios where you need to maintain critical data even after instances are deleted or replaced. Volumes can be reused and mounted across multiple instances, providing flexibility and durability for your storage needs. In this guide, we will cover how to create a volume, attach it to an instance, and verify that it is mounted via the Shadeform API. This process involves creating a volume first, launching an instance with the volume attached, and confirming the volume on the instance. Currently, volumes can only be attached to instances in the same cloud provider and region. Multi-cloud volumes are an upcoming feature.

​
Prerequisites

There are two pre-requisites for this guide:
  1. After you have created your account, you must top up your wallet here.
  2. After you have topped up your wallet, generate and retrieve your Shadeform API key here.

​
Step 1: Check Available Volume Types

To create a volume, you first need to know what volume types are available. Use the /volumes/types endpoint to fetch this information. 
# Retrieve available volume types
curl --location 'https://api.shadeform.ai/v1/volumes/types' \
--header 'x-api-key: <api-key>'
Example Response The response will list the supported volume types. Here is an example (this is example data and may not have correct values):
Response
{
  "volume_types": [
    {
      "cloud": "datacrunch",
      "region": "FIN-01",
      "supports_multiple_mounts": false,
      "fixed_size": true,
      "price_per_gb_per_hour": "0.00028"
    },
    {
      "cloud": "nebius",
      "region": "eu-north1",
      "supports_multiple_mounts": false,
      "fixed_size": true,
      "price_per_gb_per_hour": ".000097"
    },
    {
      "cloud": "digitalocean",
      "region": "tor1",
      "supports_multiple_mounts": false,
      "fixed_size": true,
      "price_per_gb_per_hour": ".000084"
    },
  ]
}
Take note of the cloud and region fields for the next step.

​
Step 2: Create a Volume

Now that you know the volume type and region, create the volume using the /volumes/create API.
Your volume and instance will need to have the same cloud provider, and be in the same region to work
Replace <api-key> with your API key, and customize the cloud, region, and size_in_gb fields to match your requirements. 
# Create a new volume
curl --location 'https://api.shadeform.ai/v1/volumes/create' \
--header 'x-api-key: <api-key>' \
--header 'Content-Type: application/json' \
--data '{
    "cloud": "digitalocean",
    "region": "tor1",
    "size_in_gb": 100,
    "name": "mystoragevolume"
}'
Example Response The response will include the id of the newly created volume, which will be used to attach it to an instance.
Response
{
  "id": "df5c952c-0567-4140-94d6-59cee96f8caa"
}
Save the id field as you will need it in the next step.

​
Step 3: Create an Instance with the Volume Attached

To attach the volume, pass its id in the volume_ids field while creating the instance using the /instances/create endpoint.
“volume_ids” must be an array of size one. This is because we only allow attaching one volume to one instance right now. Attaching multiple volumes to a single instance is a feature we will add in the future. 
# Create an instance with the volume attached
curl --location 'https://api.shadeform.ai/v1/instances/create' \
--header 'x-api-key: <api-key>' \
--header 'Content-Type: application/json' \
--data '{
  "cloud": "digitalocean",
  "region": "tor1",
  "shade_instance_type": "H100_sxm5",
  "shade_cloud": true,
  "name": "the-super-cool-digitalocean-server-volume",
  "volume_ids": ["b1f2c5d3-29ab-4e7b-9f7e-2c35a1e34d4e"] # be sure to include this line
}'
Example Response The response will include the id for the instance and a cloud_assigned_id. Save this for further operations.
Response
{
  "id": "cc9f6b74-9825-4854-9e9c-dd50c7e97c3a",
  "cloud_assigned_id": "720f2a6a-e4ee-488a-ade1-e7892f5d730a"
}

​
Step 4: Verify the Volume on the Instance

Once the instance is active, SSH into it to verify that the volume has been mounted. Learn how to SSH into a Shadeform instance using this guide. After connecting, run the following command: 
# List all block devices attached to the instance
lsblk
Your output should look something similar to this: 
NAME    MAJ:MIN RM   SIZE RO TYPE MOUNTPOINTS
loop0     7:0    0  63.9M  1 loop /snap/core20/2318
loop1     7:1    0    87M  1 loop /snap/lxd/28373
loop2     7:2    0  38.8M  1 loop /snap/snapd/21759
loop3     7:3    0  44.3M  1 loop /snap/snapd/23258
loop4     7:4    0  63.7M  1 loop /snap/core20/2434
vda     252:0    0   128G  0 disk 
├─vda1  252:1    0 127.9G  0 part /
├─vda14 252:14   0     4M  0 part 
└─vda15 252:15   0   106M  0 part /boot/efi
vdb     252:16   0    50G  0 disk # this is the volume I mounted
nvme0n1 259:0    0 894.3G  0 disk
This command will display all block devices attached to the instance. You should see your volume listed as a new device, such as vdb, sbd, or similar.

​
Step 5: Mount the volume to a file system

After verifying the volume is attached, you can mount it to a file system. Find your volume from the lsblk command (my volume is called vdb in this example) and mount it to a directory using the following commands: 
sudo mkdir /mnt/vdb
sudo mkfs.ext4 /dev/vdb
sudo mount -t ext4 /dev/vdb /mnt/vdb/
sudo chown -R shadeform:shadeform /mnt/vdb/
Now, the /mnt/vdb directory should be connected to your volume and fully accessible for you to write and read from.

​
Step 6: Deleting the Instance and Volume

Before you can delete a volume, you must delete the instance it is attached to. Delete the Instance Use the /instances/delete endpoint to remove the instance. 
# Delete the instance
curl --location 'https://api.shadeform.ai/v1/instances/<instance-id>/delete' \
--header 'x-api-key: <api-key>'
Replace <instance-id> with the id of your instance. Delete the Volume Once the instance has been deleted, you can safely delete the volume using the /volumes/delete endpoint. 
# Delete the volume
curl --location 'https://api.shadeform.ai/v1/volumes/<volume-id>/delete' \
--header 'x-api-key: <api-key>'
Replace <volume-id> with the id of the volume.

​
Summary

You have successfully created a volume, attached it to an instance, verified the attachment, and learned how to clean up resources. For more details, check out the Shadeform API reference.

Managing Instances

Learn more about managing GPU instances.

API Documentation

Full API reference for volumes and instances.