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 Case | Recommended Solution |
|---|---|
| SQLite databases | Persistent Volume |
| File uploads | Persistent Volume |
| Application cache on disk | Persistent Volume |
| ML model files | Persistent Volume |
| Relational databases | Managed PostgreSQL or MariaDB |
| Key-value cache | Managed Valkey |
| Object storage (S3) | External S3-compatible service |
| Shared storage across replicas | Shared Volumes (RWX) |
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:
| Constraint | Reason |
|---|---|
| Limited to 1 replica | Volumes can only be mounted by one pod at a time (ReadWriteOnce) |
| Autoscaling disabled | Horizontal scaling is incompatible with single-instance volumes |
| Brief downtime during redeployments | The old instance must stop before the new one starts (Recreate strategy) |
| Volume size cannot be reduced | Kubernetes does not support shrinking PersistentVolumeClaims |
| Maximum 5 volumes | Per container limit |
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
- Navigate to Containers → Create Container
- In the Resources & Scaling section, click Add Volume
- 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
- Name: A unique identifier for the volume (lowercase, hyphens allowed, e.g.,
- Add more volumes as needed (up to 5)
- Complete the rest of the form and create the container
On an Existing Container
- Go to your container → Edit
- In the Resources & Scaling section, add, modify, or remove volumes
- Click Save
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
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Unique volume name (lowercase alphanumeric + hyphens, max 63 chars) |
mountPath | string | Yes | Absolute path inside the container (e.g., /data) |
sizeInMB | integer | Yes | Volume size in megabytes. Min: 1024 (1 GB), Max: 102400 |
storageClass | string | No | standard (5K IOPS) or performance (15K IOPS). Defaults to standard |
Storage Classes
| Storage Class | IOPS | Best For |
|---|---|---|
| Standard | 5K | General workloads, file storage, caches |
| Performance | 15K | Databases (SQLite), high-throughput applications |
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:
- Go to your container → Edit
- Increase the volume size slider
- Click Save
The volume is expanded without data loss. The container restarts to apply the change.
Once a volume is created, its size can only be increased.
Adding a Volume to an Existing Container
- Go to your container → Edit
- Click Add Volume in the Resources & Scaling section
- Configure the new volume (name, mount path, size, storage class)
- Click Save
Detaching a Volume
- Go to your container → Edit
- Click the remove button on the volume you want to detach
- Confirm the detach
- 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
- Go to Volumes and click the detached volume
- Click Delete
- Confirm the deletion
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 Case | Solution |
|---|---|
| Share data between multiple containers | Shared Volume |
| Share data between containers and jobs | Shared Volume |
| Persistent storage for a single container | Block Volume |
| Database storage | Managed PostgreSQL or MariaDB |
Creating a shared volume
- Navigate to Volumes in the project sidebar
- Click Create Shared Volume
- Configure the volume:
- Name: Lowercase alphanumeric with hyphens (max 60 characters)
- Size: From 1 GB to 1 TB
- Description: Optional description
- 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:
- Edit a container (or create a job/cronjob)
- In the Volumes section, click Add Shared Volume
- Select the volume name and set the Mount Path
- Optionally enable Read Only mode
- Save
A shared volume can be mounted by multiple workloads at the same time. All workloads see the same data.
Resizing a shared volume
- Go to the shared volume detail page
- Click Resize
- Enter the new size (must be larger than the current size)
- Click Confirm
Shared volumes can only be expanded, never reduced.
Deleting a shared volume
- Go to the shared volume detail page
- Click Delete
- Confirm the deletion
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.
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
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Volume name (lowercase alphanumeric + hyphens, max 60 chars) |
sizeInMB | integer | Yes | Volume size in megabytes. Min: 1024 (1 GB), Max: 1048576 (1 TB) |
description | string | No | Optional description (max 256 chars) |
SharedVolumeMount specification
| Field | Type | Required | Description |
|---|---|---|---|
volumeName | string | Yes | Name of an existing shared volume in the project |
mountPath | string | Yes | Absolute mount path inside the container |
readOnly | boolean | No | Mount 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
- Go to the volume detail page (click the volume name in the Volumes list or in the container's Volumes tab)
- Open the Snapshots tab
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
- Open the volume detail page → Snapshots tab
- Click Create Snapshot
- The snapshot appears in the list with a Pending status
- Once complete, the status changes to Ready
Snapshot statuses
| Status | Description |
|---|---|
| Pending | Snapshot is being created |
| Ready | Snapshot is complete and available for restore |
| Error | Snapshot creation failed |
Snapshot types
| Type | Description |
|---|---|
| Manual | Created on demand by a user |
| Scheduled | Created automatically by a snapshot schedule |
Configuring a snapshot schedule
Automate snapshot creation with a cron-based schedule:
- On the volume detail page → Snapshots tab, click Configure Schedule (or Configure if a schedule already exists)
- Set the Cron Expression (standard 5-field format, e.g.,
0 2 * * *for daily at 2:00 AM UTC) - Set Retention Count — maximum number of scheduled snapshots to keep (default: 10)
- Set Retention Days — maximum age of snapshots in days (default: 30)
- 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.
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
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.
- Expand the volume and click the restore button on a Ready snapshot
- Review the warning about downtime
- Click Restore to confirm
The restore process:
- Stops the container (including autoscaling)
- Waits for all pods to terminate
- Deletes the current PersistentVolumeClaim
- Creates a new PVC from the snapshot while preserving its access mode, storage class, size contract and user metadata
- Waits for the new PVC to become Bound
- Restarts the container only if it was running before the restore
Deleting a snapshot
- Click the delete button on the snapshot row
- Confirm the deletion
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
GIDin 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)