Skip to main content

Persistent Volumes

Store data that persists across container restarts and redeployments.

By default, containers on SailOps use ephemeral storage — data is lost when the container restarts. Persistent Volumes let you attach durable storage to a container so files are preserved across restarts, redeployments, and updates. You can attach up to 5 volumes per container, each with its own mount path, size, and storage class.

When to Use Persistent Volumes​

Use CaseRecommended Solution
SQLite databasesPersistent Volume
File uploadsPersistent Volume
Application cache on diskPersistent Volume
ML model filesPersistent Volume
Relational databasesManaged PostgreSQL or MariaDB
Key-value cacheManaged Valkey
Object storage (S3)External S3-compatible service
Shared storage across replicasShared Volumes (RWX)
When NOT to Use Volumes

If your application needs a proper database, use Managed PostgreSQL or MariaDB instead. Managed databases provide automated backups, high availability, and connection pooling.

Important Limitations​

Attaching one or more persistent volumes to a container enforces the following constraints:

ConstraintReason
Limited to 1 replicaVolumes can only be mounted by one pod at a time (ReadWriteOnce)
Autoscaling disabledHorizontal scaling is incompatible with single-instance volumes
Brief downtime during redeploymentsThe old instance must stop before the new one starts (Recreate strategy)
Volume size cannot be reducedKubernetes does not support shrinking PersistentVolumeClaims
Maximum 5 volumesPer container limit
No Zero-Downtime Updates

Unlike standard containers that use rolling updates, containers with persistent volumes experience a brief downtime (typically 10–30 seconds) during redeployments.

Configure Volumes​

During Container Creation​

  1. Navigate to Containers → Create Container
  2. In the Resources & Scaling section, click Add Volume
  3. Configure each volume:
    • Name: A unique identifier for the volume (lowercase, hyphens allowed, e.g., data, uploads, cache)
    • Mount Path: Absolute path inside the container (e.g., /data, /app/uploads)
    • Storage Class: Standard (5K IOPS) or Performance (15K IOPS)
    • Size: Volume size from 1 GB to 100 GB
  4. Add more volumes as needed (up to 5)
  5. Complete the rest of the form and create the container

On an Existing Container​

  1. Go to your container → Edit
  2. In the Resources & Scaling section, add, modify, or remove volumes
  3. Click Save
Detach, not delete

Removing a volume from the container form detaches it: the container stops mounting it, but the data is kept. The volume stays listed in the Volumes section as Detached and continues to be billed. To permanently delete a detached volume, open its detail page and click Delete.

Via the Public API​

Create a container with multiple volumes:

curl -X POST \
-H "X-Api-Key: $SAILOPS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "my-app",
"spec": {
"computeClass": "standard",
"image": "myapp:latest",
"resources": {"cpu": 500, "memory": 512},
"volumes": [
{
"name": "data",
"mountPath": "/data",
"sizeInMB": 2048,
"storageClass": "standard"
},
{
"name": "uploads",
"mountPath": "/app/uploads",
"sizeInMB": 10240,
"storageClass": "performance"
}
]
}
}' \
https://app.sailops.io/api/public/api/v1/containers

For shared volumes, see the Shared Volumes section for API examples.

Volume Specification​

FieldTypeRequiredDescription
namestringYesUnique volume name (lowercase alphanumeric + hyphens, max 63 chars)
mountPathstringYesAbsolute path inside the container (e.g., /data)
sizeInMBintegerYesVolume size in megabytes. Min: 1024 (1 GB), Max: 102400
storageClassstringNostandard (5K IOPS) or performance (15K IOPS). Defaults to standard

Storage Classes​

Storage ClassIOPSBest For
Standard5KGeneral workloads, file storage, caches
Performance15KDatabases (SQLite), high-throughput applications
Choosing a Storage Class

Start with Standard for most workloads. Use Performance for high disk I/O (embedded databases, heavy logging, frequent writes).

Managing Volumes​

Expanding a Volume​

You can increase the size of an existing volume at any time:

  1. Go to your container → Edit
  2. Increase the volume size slider
  3. Click Save

The volume is expanded without data loss. The container restarts to apply the change.

Size Cannot Be Reduced

Once a volume is created, its size can only be increased.

Adding a Volume to an Existing Container​

  1. Go to your container → Edit
  2. Click Add Volume in the Resources & Scaling section
  3. Configure the new volume (name, mount path, size, storage class)
  4. Click Save

Detaching a Volume​

  1. Go to your container → Edit
  2. Click the remove button on the volume you want to detach
  3. Confirm the detach
  4. Click Save

The volume is detached from the container but its data is preserved. It appears in the Volumes list with a Detached badge and remains billed. To re-attach it, add a volume with the same name in the container form.

Deleting a Detached Volume​

  1. Go to Volumes and click the detached volume
  2. Click Delete
  3. Confirm the deletion
Data Loss

Deleting a detached volume permanently removes it, its snapshot schedule, and all its snapshots from SailOps. A new volume with the same name starts empty.

Volume Lifecycle​

Key behaviors:

  • Stop/Start: All volumes persist when the container is stopped
  • Redeploy: Brief downtime — old pod stops, new pod starts with all volumes re-mounted
  • Detach: Data is preserved; the volume stays listed and billed until explicitly deleted
  • Delete detached volume: The volume, its snapshots, and its schedule are permanently removed
  • Delete container: All volumes and their data are permanently deleted
  • Suspend project: Volumes persist during project suspension

Example Configurations​

Web App with Database and Uploads​

{
"volumes": [
{ "name": "db", "mountPath": "/app/data", "sizeInMB": 1024, "storageClass": "performance" },
{ "name": "uploads", "mountPath": "/app/uploads", "sizeInMB": 10240, "storageClass": "standard" }
]
}

WordPress with Themes and Uploads​

{
"volumes": [
{ "name": "uploads", "mountPath": "/var/www/html/wp-content/uploads", "sizeInMB": 20480, "storageClass": "standard" },
{ "name": "themes", "mountPath": "/var/www/html/wp-content/themes", "sizeInMB": 1024, "storageClass": "standard" }
]
}

Best Practices​

Name Your Volumes Meaningfully​

Use descriptive names like data, uploads, cache, logs — they appear in the UI and are used in PVC naming.

Choose the Right Mount Path​

  • Use dedicated directories (e.g., /data, /app/storage)
  • Avoid system directories (/etc, /proc, /sys, /bin, etc.)
  • Ensure your application has write permissions to the mount path

Mix Storage Classes​

Use Performance for I/O-intensive volumes (databases) and Standard for bulk storage (uploads, caches) to optimize cost.

Back Up Important Data​

  • Use Volume Snapshots for point-in-time backups
  • Set up automated snapshot schedules for critical data
  • Before removing a volume, create a snapshot or export important data

Shared Volumes (RWX)​

Shared volumes provide ReadWriteMany (RWX) storage that multiple containers, jobs, and cronjobs can mount simultaneously. Unlike block volumes (which are tied to a single container), shared volumes are managed independently and persist regardless of any workload's lifecycle.

When to use shared volumes​

Use CaseSolution
Share data between multiple containersShared Volume
Share data between containers and jobsShared Volume
Persistent storage for a single containerBlock Volume
Database storageManaged PostgreSQL or MariaDB

Creating a shared volume​

  1. Navigate to Volumes in the project sidebar
  2. Click Create Shared Volume
  3. Configure the volume:
    • Name: Lowercase alphanumeric with hyphens (max 60 characters)
    • Size: From 1 GB to 1 TB
    • Description: Optional description
  4. Click Create

The volume is provisioned asynchronously. Its status changes from Pending to Ready once provisioning completes.

Mounting a shared volume​

Shared volumes can be mounted on containers, jobs, and cronjobs:

  1. Edit a container (or create a job/cronjob)
  2. In the Volumes section, click Add Shared Volume
  3. Select the volume name and set the Mount Path
  4. Optionally enable Read Only mode
  5. Save
Multiple mounts

A shared volume can be mounted by multiple workloads at the same time. All workloads see the same data.

Resizing a shared volume​

  1. Go to the shared volume detail page
  2. Click Resize
  3. Enter the new size (must be larger than the current size)
  4. Click Confirm
Grow only

Shared volumes can only be expanded, never reduced.

Deleting a shared volume​

  1. Go to the shared volume detail page
  2. Click Delete
  3. Confirm the deletion
Cannot delete mounted volumes

A shared volume cannot be deleted while it is still mounted by any container, job, or cronjob. Unmount it from all workloads first.

Backing up and restoring a shared volume​

Open the shared volume detail page and use its Snapshots tab to create a manual snapshot or configure an automatic schedule. Restoring a ready snapshot does not replace or stop the source volume: it creates a separate shared volume under the new name you choose.

The restored volume initially appears as Pending. Provisioning is recorded and retried automatically, so closing the page or losing the request connection does not cancel it. The target name remains reserved during this work, and the target cannot be deleted until restoration has either completed or been safely abandoned. Wait for Ready before mounting it in a workload.

Use a new name

The restore target must not already be used by another shared volume or by a restore in progress. SailOps never overwrites a same-name volume.

Via the Public API​

Create a shared volume:

curl -X POST \
-H "X-Api-Key: $SAILOPS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "shared-data",
"sizeInMB": 10240,
"description": "Shared data between workers"
}' \
https://app.sailops.io/api/public/api/v1/shared-volumes

Mount it on a container:

curl -X PATCH \
-H "X-Api-Key: $SAILOPS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image": "myapp:latest",
"sharedVolumeMounts": [
{
"volumeName": "shared-data",
"mountPath": "/mnt/shared"
}
]
}' \
https://app.sailops.io/api/public/api/v1/containers/my-worker

Shared volume specification​

FieldTypeRequiredDescription
namestringYesVolume name (lowercase alphanumeric + hyphens, max 60 chars)
sizeInMBintegerYesVolume size in megabytes. Min: 1024 (1 GB), Max: 1048576 (1 TB)
descriptionstringNoOptional description (max 256 chars)

SharedVolumeMount specification​

FieldTypeRequiredDescription
volumeNamestringYesName of an existing shared volume in the project
mountPathstringYesAbsolute mount path inside the container
readOnlybooleanNoMount as read-only. Defaults to false

Volume Snapshots​

Volume Snapshots let you create point-in-time backups of your persistent volumes. You can create snapshots manually, set up automated schedules, and restore a volume to a previous state.

Accessing volume snapshots​

  1. Go to the volume detail page (click the volume name in the Volumes list or in the container's Volumes tab)
  2. Open the Snapshots tab
Detached volumes

A detached block volume still lists its existing snapshots and lets you delete them, but you cannot create new snapshots or restore until the volume is re-attached to its container.

Creating a manual snapshot​

  1. Open the volume detail page → Snapshots tab
  2. Click Create Snapshot
  3. The snapshot appears in the list with a Pending status
  4. Once complete, the status changes to Ready

Snapshot statuses​

StatusDescription
PendingSnapshot is being created
ReadySnapshot is complete and available for restore
ErrorSnapshot creation failed

Snapshot types​

TypeDescription
ManualCreated on demand by a user
ScheduledCreated automatically by a snapshot schedule

Configuring a snapshot schedule​

Automate snapshot creation with a cron-based schedule:

  1. On the volume detail page → Snapshots tab, click Configure Schedule (or Configure if a schedule already exists)
  2. Set the Cron Expression (standard 5-field format, e.g., 0 2 * * * for daily at 2:00 AM UTC)
  3. Set Retention Count — maximum number of scheduled snapshots to keep (default: 10)
  4. Set Retention Days — maximum age of snapshots in days (default: 30)
  5. Click Save Schedule

The retention task removes snapshot entries from SailOps. The block-volume snapshot class currently uses the provider's Retain policy, so underlying provider snapshot content may remain until infrastructure cleanup.

Minimum interval

The schedule interval must be at least 1 hour between snapshots.

To disable an existing schedule, click Disable on the schedule card.

Restoring from a snapshot​

Downtime during restore

Restoring from a snapshot causes temporary downtime. A running container is stopped, the volume is replaced with the snapshot data, and the container is restarted only after the replacement claim is ready. A container that was already stopped remains stopped.

  1. Expand the volume and click the restore button on a Ready snapshot
  2. Review the warning about downtime
  3. Click Restore to confirm

The restore process:

  1. Stops the container (including autoscaling)
  2. Waits for all pods to terminate
  3. Deletes the current PersistentVolumeClaim
  4. Creates a new PVC from the snapshot while preserving its access mode, storage class, size contract and user metadata
  5. Waits for the new PVC to become Bound
  6. Restarts the container only if it was running before the restore

Deleting a snapshot​

  1. Click the delete button on the snapshot row
  2. Confirm the deletion
warning

Deleting a snapshot removes the restorable entry from SailOps and cannot be undone from the product. Because the provider class uses Retain, the underlying provider snapshot may still exist and require infrastructure cleanup.

Snapshot details​

Click the info button on any snapshot to view:

  • Snapshot ID — unique identifier
  • Status — current state (Pending, Ready, Error)
  • Type — Manual or Scheduled
  • Created / Ready At — request and CSI readiness timestamps
  • Size — restore size reported by the CSI driver
  • Description / Created By — metadata when supplied
  • Restorable / Error — whether restore is currently safe and the CSI error, if any
  • Volume — the volume name

Troubleshooting​

Container Stuck in Pending After Adding Volume​

  • The volume may be provisioning (30–60 seconds)
  • Check Events tab for storage-related errors
  • Verify size is within limits (1 GB – 100 GB per volume)

Permission Denied on Mount Path​

SailOps automatically sets a filesystem group (fsGroup 1000) on pods with persistent volumes so non-root images can write to their volumes regardless of the UID they run as. If you still encounter permission issues:

  • Verify your application writes to the configured mount path, not to a parent directory outside the volume
  • Check that the image does not override the group with an incompatible GID in its entrypoint

Data Not Persisting​

  • Verify your app writes to the configured mount path
  • Check volume is still attached in container details
  • Ensure writes go to the volume path, not /tmp (which is ephemeral)