Spheron ES: mounting shared storage

Mount persistent shared filesystems on Spheron ES (Extra Supply) instances using the virtiofs protocol.

Overview

Spheron ES shared filesystems attach directly to the VM and expose a virtiofs device identified by a unique mount tag. Volumes can be mounted to multiple instances simultaneously, resized in place, and persist independently of the instance.

Protocol: virtiofs Connection: Directly attached virtio filesystem Identifier: Mount tag from the volume card Maximum size: 256 TiB per volume (sizeInGb: 262144 on the API) Regions: EU North 1 (Finland), EU West 1 (France), ME West 1 (Middle East), US Central 1 (US) Multi-volume support: Attach multiple volumes to a single instance

Volume behavior:

Volumes selected at deploy time are mounted before the instance boots, so there is no restart.
Hot-attach or hot-detach on a running instance stops the VM, applies the change, and starts it back up. Data is preserved across the restart.
The same volume can be mounted on multiple instances at once, read-write or read-only.
Volumes can be grown in place after creation without recreating them or migrating data. Shrinking is not supported.
A volume's name is fixed at creation. To use a different name, create a new volume.

Prerequisites

Before starting, ensure you have:

Created a volume with provider: spheron-es via the Spheron dashboard (Create Volume page)
Attached the shared filesystem to your Spheron ES instance, either during deployment or via the volume details page
Retrieved the mount tag from the volume card in the Spheron AI dashboard
SSH access to your Spheron ES instance

Mounting process

Connect to your instance

SSH into your Spheron ES 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.

Verify the device is visible

Confirm the virtiofs device is present after the instance boots:

sudo dmesg | grep virtiofs

You should see a line similar to:

virtiofs virtio3: virtio_fs_setup_dax: No cache capability

If no virtiofs device appears, the filesystem is not attached. Attach it from the volume details page in the Spheron AI dashboard, then retry.

Create a mount point

Create a directory where you'll mount the shared filesystem. Replace <SFS_NAME> with your preferred directory name:

sudo mkdir -p /mnt/<SFS_NAME>

Common choices include:

/mnt/shared: standard mount location
/mnt/datasets: for ML/AI datasets
/mnt/models: for model checkpoints

Mount the filesystem

Mount the shared filesystem using its mount tag. Replace the placeholders with your values:

<MOUNT_TAG>: the mount tag shown on the volume card (e.g., hkjhkh)
<SFS_NAME>: your mount directory name

sudo mount -t virtiofs <MOUNT_TAG> /mnt/<SFS_NAME>

Example:

sudo mount -t virtiofs hkjhkh /mnt/shared

Set permissions

Grant all users write access to the mounted directory:

sudo chmod a+w /mnt/<SFS_NAME>

To restrict ownership to a specific user instead, use chown:

sudo chown ubuntu:ubuntu /mnt/<SFS_NAME>

Verify the mount

Confirm the filesystem mounted successfully:

df -h /mnt/<SFS_NAME>

Expected output:

Filesystem      Size  Used Avail Use% Mounted on
hkjhkh           50G     0   50G   0% /mnt/shared

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

Add the filesystem to /etc/fstab so it remounts automatically on reboot. The nofail option is critical: without it, the VM will not boot if the filesystem is ever detached.

echo "<MOUNT_TAG> /mnt/<SFS_NAME> virtiofs rw,nofail 0 0" | sudo tee -a /etc/fstab

Example:

echo "hkjhkh /mnt/shared virtiofs rw,nofail 0 0" | sudo tee -a /etc/fstab

Find the mount tag

The mount tag is shown on the volume card in the Spheron AI dashboard:

Open the Volumes page in the Spheron AI dashboard.
Select your volume from the list.
The Mount Tag is displayed on the volume card and can be copied with the copy icon.

The mount tag is unique per volume and used directly as the source argument to mount -t virtiofs.

Use your mounted volume

Access the storage

Once mounted, use the shared filesystem like any local directory:

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

Check storage usage

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

Work with large datasets

Download datasets and checkpoints to the mounted volume. Data persists across instance restarts and is accessible from other instances in the same region that share this volume.

# Example: download a dataset to shared storage
cd /mnt/shared
wget https://example.com/large-dataset.tar.gz
tar -xzf large-dataset.tar.gz

Mount to every node in a cluster

To mount the shared filesystem across all nodes in a cluster at once, use pdsh. Replace the placeholders as above:

pdsh -a "sudo mkdir -vp /mnt/<SFS_NAME> && echo '<MOUNT_TAG> /mnt/<SFS_NAME> virtiofs rw,nofail 0 0' | sudo tee -a /etc/fstab && sudo mount /mnt/<SFS_NAME>"

Unmount shared storage

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

Unmount the filesystem

sudo umount /mnt/<SFS_NAME>

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

# Check what's using the storage
lsof /mnt/<SFS_NAME>
 
# Or use fuser
fuser -m /mnt/<SFS_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 the line by mount tag
sudo sed -i '/<MOUNT_TAG>.*virtiofs/d' /etc/fstab

Troubleshooting

Mount fails with "wrong fs type, bad option, bad superblock"

Cause: The mount tag is incorrect.

Solution:

Open the Volumes page in the Spheron AI dashboard.
Select the volume and copy the Mount Tag from the volume card.
Retry the mount with the exact tag value.

No virtiofs device in `dmesg`

Cause: The filesystem is not attached to the VM.

Solution:

Open the volume details page in the Spheron AI dashboard.
Attach the volume to the instance. Hot-attach restarts the VM.
After the instance boots, rerun sudo dmesg | grep virtiofs.

Filesystem not mounting on boot

Cause: The fstab entry is missing the nofail option, or the device is not ready when fstab mounts are processed.

Solution: Ensure the fstab entry includes nofail. With nofail, the system continues to boot even if the filesystem is unavailable:

<MOUNT_TAG> /mnt/<SFS_NAME> virtiofs rw,nofail 0 0

Check mount status

# List all virtiofs mounts
mount | grep virtiofs
 
# Verify fstab syntax without mounting
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

Deployment:

Select volumes at deploy time to avoid the hot-attach restart
Plan ahead for the volume name, since renaming is not supported after creation

Data safety:

Maintain backups of critical data
Filesystems persist independently of instances, but data can still be lost due to accidental deletion
Test backup and restore procedures

Security:

Restrict access using filesystem permissions
Only mount filesystems shared explicitly with your instance
Audit who has access to shared 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

For questions, use chat support in the Spheron AI dashboard or contact Spheron support for infrastructure issues.