Spheron AI: mounting shared storage

Mount persistent block storage volumes on Spheron AI instances using raw block devices and your choice of filesystem.

Overview

Spheron AI persistent volumes attach as raw block devices (e.g., /dev/vdb). You choose the filesystem when formatting the volume. A stable UUID identifies each volume, referenced in /etc/fstab for persistent mounting.

Protocol: Block device (ext4, xfs, or ntfs) Connection: Directly attached block device Performance: Local disk throughput Multi-volume support: Attach up to 10 volumes to a single instance

Prerequisites

Before starting, ensure you have:

Created a volume with provider: spheron-ai via the Spheron dashboard (Create Volume page)
Attached the volume to your Spheron AI instance
SSH access to your Spheron AI instance (credentials in the instance's Details drawer)

Mounting process

Connect to your instance

SSH into your Spheron AI GPU instance using the connection details from the instance's Details drawer:

ssh ubuntu@<your-instance-ip>

See SSH Connection Setup for detailed connection instructions.

Identify the new disk

List all block devices to confirm the volume is visible and unmounted:

lsblk -o NAME,SIZE,TYPE,FSTYPE,MOUNTPOINT

Expected output:

NAME     SIZE TYPE FSTYPE   MOUNTPOINT
vda      100G disk
├─vda1  99.9G part ext4     /
vdb       50G disk                   # new disk, no MOUNTPOINT

If the disk has no FSTYPE and no MOUNTPOINT, it is raw and ready to format.

Format the disk

Format the volume with your preferred filesystem. Replace [file-system-format] with your desired type:

sudo mkfs.[file-system-format] /dev/vdb

Common filesystem choices:

Filesystem	Best for
`ext4`	General-purpose workloads on Linux. Robust, journaling, widely compatible.
`xfs`	Large files and large filesystems. Strong performance in data center workloads.
`ntfs`	Drives shared with Windows systems. Supports large files with journaling.

Example using ext4:

sudo mkfs.ext4 /dev/vdb

Create mount directory

Create a directory where you'll mount the volume. Replace <VOLUME_NAME> with the name of your volume as listed in the Spheron dashboard:

sudo mkdir -p /mnt/<VOLUME_NAME>

Common choices include:

/mnt/data: simple and clear
/mnt/storage: standard mount location
/mnt/datasets: for ML/AI datasets
/mnt/models: for model checkpoints

Mount the disk

Mount the formatted disk to the mount point:

sudo mount /dev/vdb /mnt/<VOLUME_NAME>

Verify it is now visible:

df -h

Look for your volume in the output:

Filesystem       Size  Used Avail Use% Mounted on
...
/dev/vdb          49G   24K   47G   1% /mnt/data

Verify the mount

Confirm the volume is mounted correctly:

mount | grep "<VOLUME_NAME>"

Or inspect all block devices with filesystem details:

lsblk -o NAME,SIZE,FSTYPE,MOUNTPOINT,LABEL | grep "<VOLUME_NAME>"

Persist the mount in `/etc/fstab` (recommended)

Device names like /dev/vdb can change across reboots or VM restores. Use the disk's UUID for a stable reference.

Get the UUID:

sudo blkid /dev/vdb

Example output:

/dev/vdb: UUID="a1b2c3d4-e5f6-7890-abcd-ef1234567890" TYPE="ext4"

Add the entry to /etc/fstab (replace the UUID and filesystem type with your own):

echo 'UUID=<your-uuid>  /mnt/<VOLUME_NAME>  ext4  defaults,nofail  0  2' | sudo tee -a /etc/fstab

Field explanation:

Field	Value	Meaning
device	`UUID=...`	Identifies the disk by UUID
mount point	`/mnt/<VOLUME_NAME>`	Where the disk is accessible
type	`ext4`	Filesystem type
options	`defaults,nofail`	Standard mount options with boot-safety fallback
dump	`0`	Disable backup via `dump`
pass	`2`	fsck order (2 = non-root disk)

Verify the fstab entry works:

sudo mount -a

No errors confirms the entry is correct.

Set permissions (optional)

Make the mounted storage writable by your user:

sudo chown ubuntu:ubuntu /mnt/<VOLUME_NAME>

Replace ubuntu:ubuntu with your username if different.

Use your mounted volume

Access the storage

Once mounted, use the volume like any local directory:

# Navigate to the storage
cd /mnt/data
 
# Create files and directories
mkdir my-project
echo "Hello, storage!" > my-project/readme.txt
 
# List contents
ls -lh /mnt/data/

Check storage usage

# Check space on the mounted volume
df -h /mnt/data
 
# Check detailed disk usage
du -sh /mnt/data/*

Work with large datasets

Download datasets and checkpoints to the mounted volume. Data persists across instance restarts.

# Example: Download dataset to storage
cd /mnt/data
wget https://example.com/large-dataset.tar.gz
tar -xzf large-dataset.tar.gz

Unmount shared storage

Unmount when swapping volumes, detaching the volume, or terminating the instance.

Unmount the volume

sudo umount /mnt/<VOLUME_NAME>

If you get a "target is busy" error, check for active processes:

# Check what's using the storage
lsof /mnt/<VOLUME_NAME>
 
# Or use fuser
fuser -m /mnt/<VOLUME_NAME>

Remove from file system table

Remove the entry from /etc/fstab to prevent auto-mount on next boot:

# Edit fstab manually
sudo nano /etc/fstab
 
# Or remove automatically with sed
sudo sed -i '/UUID=<your-uuid>/d' /etc/fstab

Troubleshooting

Disk not visible in `lsblk`

Cause: Volume not attached by the cloud provider.

Solution:

Check the Spheron AI dashboard and confirm the volume is attached to your instance
Re-attach the volume if needed and reconnect to the instance

`mkfs` fails

Cause: Disk is already mounted.

Solution:

sudo umount /dev/vdb
sudo mkfs.ext4 /dev/vdb

Volume not mounting on boot

Cause: Missing or incorrect /etc/fstab entry.

Solution: Verify the fstab entry exists and the UUID matches:

sudo blkid /dev/vdb
cat /etc/fstab
sudo mount -fav

VM fails to boot after adding fstab entry

Cause: Volume is not attached and the fstab entry lacks the nofail option.

Solution: Boot into recovery mode and add nofail to the mount options:

UUID=<your-uuid>  /mnt/<VOLUME_NAME>  ext4  defaults,nofail  0  2

Permission denied when writing to disk

Cause: Mount point ownership is root.

Solution:

sudo chown ubuntu:ubuntu /mnt/<VOLUME_NAME>

Check mount status

# List all mounted filesystems
mount | grep /mnt
 
# Check filesystem integrity (disk must be unmounted)
sudo fsck /dev/vdb
 
# Verify fstab syntax
sudo mount -fav

Best practices

Organization:

Use descriptive mount points: /mnt/data, /mnt/models, /mnt/datasets
Create subdirectories for different projects
Document what data is stored where

Performance:

Block storage provides local disk throughput; no network overhead
Use ext4 for general workloads; consider xfs for large file performance

Data safety:

Maintain backups of critical data
Volumes persist independently of instances, but data can still be lost due to accidental deletion
Always include nofail in /etc/fstab entries to prevent boot failures when volumes are detached
Test backup and restore procedures

Security:

Restrict access using filesystem permissions
Audit who has access to mounted storage

What's next

Volume Mounting Overview: Multi-provider volume mounting guide
Volume API Reference: Create and manage volumes programmatically
SSH Connection Setup: Secure instance access

Overview

Prerequisites

Mounting process

Connect to your instance

Identify the new disk

Format the disk

Create mount directory

Mount the disk

Verify the mount

Persist the mount in /etc/fstab (recommended)

Set permissions (optional)

Use your mounted volume

Access the storage

Check storage usage

Work with large datasets

Unmount shared storage

Unmount the volume

Remove from file system table

Troubleshooting

Disk not visible in lsblk

mkfs fails

Volume not mounting on boot

VM fails to boot after adding fstab entry

Permission denied when writing to disk

Check mount status

Best practices

What's next

Persist the mount in `/etc/fstab` (recommended)

Disk not visible in `lsblk`

`mkfs` fails