Attach a persistent disk

4 min readUpdated April 2026

By default, everything written to a container’s filesystem is ephemeral, it disappears when the pod is replaced. Persistent disks give your service a durable filesystem path backed by network block storage. Files written there survive restarts, redeployments, and even node failures.

Under the hood, each disk is a Kubernetes PersistentVolumeClaim (PVC). StackBlaze manages the provisioning and binding lifecycle, you never write a PVC manifest. Data is encrypted at rest and kept on durable, replicated block storage.

Storage architecture

volumeMountbound PV
App Pod

writes to /data

survives restarts

PVC

PersistentVolumeClaim

ReadWriteOnce

Network Block Storage

encrypted at rest

durable, replicated

survives pod restart & redeploy

Reading & writing from your app

Node.js, accessing /data

import { readFileSync, writeFileSync } from 'fs'

import { join } from 'path'

 

// The mount path you configured in the dashboard

const DATA_DIR = process.env.DATA_DIR ?? '/data'

 

// Write a file that persists across deploys

writeFileSync(join(DATA_DIR, 'state.json'), JSON.stringify(state))

 

// Read it back on startup

const saved = JSON.parse(readFileSync(join(DATA_DIR, 'state.json'), 'utf8'))

Horizontal scaling and shared disks

By default, persistent disks use the ReadWriteOnce access mode, only a single pod can mount the disk at a time. If you scale your service horizontally to multiple replicas, each replica gets its own separate disk. To share a single disk across all replicas, you need ReadWriteMany storage, a distributed filesystem available on higher plans.

Under the hood

When you add a disk, StackBlaze provisions a PersistentVolumeClaim and mounts it into your app at the path you chose:

  • Storage class: pick the performance tier that fits, from higher-throughput classes (fast, smart) to cost-optimised ones (slow, lite). StackBlaze dynamically provisions a volume on the block-storage backend.
  • Mounted into your app: the volume is attached at your mount path. The directory is created with appropriate permissions on first mount.
  • Encryption at rest: data is encrypted before being written to the physical storage medium, with managed encryption keys.
  • Online resize: increasing a disk’s size expands the volume live, without a pod restart on supported kernels. Shrinking is not supported.

Step by step

01

Open the Storage tab on your service

Navigate to your service in the StackBlaze dashboard and click the "Storage" tab in the left sidebar. If you have no disks yet, the tab shows a single "Add Disk" button. A service can have multiple disks mounted at different paths.

02

Configure mount path and size

Click "Add Disk" and enter a mount path (e.g. /data, /uploads, /var/lib/app) and a size in gigabytes. The path must be an absolute path and cannot conflict with paths used by your application or the base image. You can resize the disk upward at any time without downtime, shrinking is not supported.

03

Redeploy - disk is mounted at the specified path

Save the disk configuration and click "Redeploy". StackBlaze provisions a PersistentVolumeClaim, binds it to a PersistentVolume on network-attached block storage, and injects a volumeMount into your pod spec at the path you specified. The directory is created automatically if it does not exist.

04

Data persists across all future deploys

The PVC is independent of the pod lifecycle. When StackBlaze performs a rolling update, the new pod receives the same PVC. Your data, uploaded files, SQLite databases, application state, remains intact across deploys, restarts, node failures, and pod rescheduling.