Volumes

Files inside a container are ephemeral. A volume is block storage mounted into a service so data survives restarts and redeploys. Use it for SQLite, uploads, model caches, and similar.

A volume is attached to one service instance. It is not shared across replicas. For data every replica must see, use object storage or a database on the canvas.

Performance specifications

Metric	Value
Sequential throughput	~100 MB/s
Baseline IOPS	1,000 IOPS
Burst IOPS	3,000 IOPS
Minimum size	1 GB
Maximum size	1 TB
Type	Network block storage (NVMe-backed)
Billing	Per GB-month (provisioned size)

One disk per service instance, not shared across replicas

A volume is attached to one service instance. It is not shared across replicas. For data every replica must see, use object storage or a database on the canvas.

Disk configuration

When you add a disk, you set:

Field	Example	Notes
Disk name	uploads	Identifier for the volume
Mount path	/data/uploads	Absolute path where the disk appears inside the container
Size	20 GB	Minimum 1 GB — can be increased later

The disk is added on the next deploy.

Example: SQLite on a persistent disk

app.js (Node.js)

const Database = require('better-sqlite3');

// Mount path matches the disk configured in StackBlaze
const db = new Database('/data/app.db');

// Data persists across restarts and deploys
db.exec(`
  CREATE TABLE IF NOT EXISTS users (
    id    INTEGER PRIMARY KEY,
    email TEXT UNIQUE NOT NULL
  )
`);

Under the hood

• PersistentVolumeClaim: StackBlaze creates a Kubernetes PVC bound to a PersistentVolume provisioned by the cluster’s default StorageClass (network block storage). The PVC is owned by the service and is not deleted on redeploy.
• VolumeMount in the pod spec: the PVC is referenced in the pod spec as a volumeMount at the configured mount path. The volume is mounted with ReadWriteOnce access mode, one writer pod at a time.
• Online resize: increasing disk size triggers a PVC spec.resources.requests.storage update. The CSI driver handles filesystem expansion online, no pod restart or unmount is required for most filesystems (ext4, xfs).
• Rolling update constraint: because the PVC uses ReadWriteOnce, StackBlaze uses Recreate deployment strategy for single-replica services with a disk (old pod terminates before new pod starts). Multi-replica services with disks each get their own PVC via a StatefulSet.

Step by step

1. Add a disk to your service

   Navigate to Service → Settings → Disk → Add Disk. Enter a name for the disk (e.g. “uploads”), the mount path where it will appear inside the container (e.g. /data or /var/lib/uploads), and the size in GB. Click Save. A rolling deploy triggers automatically.

2. Write files to the mount path

   Inside your container, the disk is accessible at the configured mount path as a standard filesystem. You can read, write, and delete files normally. All writes are persisted to the underlying block storage volume immediately, no special API required.

3. Verify persistence

   Deploy a new version of your service. The disk remains mounted at the same path with the same contents, files written before the deploy are still there. Even if the underlying pod is rescheduled to a different node, the volume follows the pod.

4. Resize the disk

   Go to Service → Settings → Disk → Edit. You can increase the size at any time, the filesystem is automatically expanded without downtime. Shrinking a disk is not supported (the underlying block device cannot be safely reduced in size while mounted).

Next steps

• Health checks
• Environment variables
• Storage limits & quotas