Persistent volumes

Add a volume

When deploying, set Volume to /data:5Gi, or in the API:

{
  "name": "wiki",
  "image": "…",
  "port": 3000,
  "volumes": [{ "name": "data", "mount_path": "/data", "size": "5Gi" }]
}

Kuben creates a PersistentVolumeClaim named <app>-<volume> in the environment namespace with ReadWriteOnce access, using the cluster’s default StorageClass unless the app specifies one.

What a volume changes

• One pod. ReadWriteOnce volumes can be mounted by one node at a time, so an app with volumes runs a single process with at most one replica, and autoscaling is off.
• Recreate rollouts. Deploys stop the old pod before starting the new one, which means a few seconds of downtime per rollout. Stateless apps keep zero-downtime rolling updates.
• Growing. Change size to a larger value and the PVC is expanded if the StorageClass allows it (allowVolumeExpansion: true). A volume can never shrink.
• Non-root images. Images that run as a non-root user often cannot write to a freshly provisioned volume. Set fs_group (for example 1000) on the app so Kubernetes chowns the volume for that group.

Templates

The database templates (PostgreSQL, Redis, MariaDB) declare their volumes for you, with sensible sizes. See the template catalogue.

Deleting an app

Deleting an app keeps its volumes by default; the PVCs stay in the namespace with a kuben.dev/retain label, so a mistaken delete does not lose data. To remove them together with the app, tick Also delete the app’s volumes in the console or add ?delete_volumes=true:

curl -fsS -X DELETE "$KUBEN_URL/api/v1/projects/shop/environments/staging/apps/wiki?delete_volumes=true" \
  -H "Authorization: Bearer $KUBEN_TOKEN"

Deleting an environment deletes its namespace and therefore every volume in it. Environments are soft-deleted with a grace period, and deleting a production environment needs the separate env-delete-protected permission (owners only).

Backups

Volumes are ordinary PVCs. kuben backup does not include their contents; use VolumeSnapshots or a cluster backup tool such as Velero. See Backup and restore.