Kubernetes volumes

A persistent volume claim in your cluster becomes a disk that follows your pod from worker to worker with its data. Volumes are created the first time a pod uses the claim, are mounted as ext4, and appear in the cluster's Storage section and in your workspace's Volumes page.

Each volume there shows its claim, its PersistentVolume name, its size and how much of it is used on disk. A volume created for a claim is named pvc- followed by the claim's UID, the name kubectl get pvc shows in its VOLUME column. A kept volume you attach again with your own manifest keeps the name you gave its PersistentVolume; the console shows it once the cluster reports it.

Storage classes

Every cluster has two:

Both give ReadWriteOnce volumes, which one worker mounts at a time, and both can grow.

Request a volume

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: data
spec:
  accessModes: [ReadWriteOnce]
  storageClassName: sahabti-retain
  resources:
    requests:
      storage: 5Gi

Leave out storageClassName to get sahabti-delete. In a StatefulSet, put the same spec under volumeClaimTemplates and each replica gets its own volume.

Grow a volume

From the console: in Volumes or in the cluster's Storage section, open the volume's menu, choose Grow volume and enter the new size in GB. The size must be larger than the volume is now, at most your plan's largest volume, and within your workspace's disk quota. Editors and admins of the volume's cluster can grow it; viewers cannot.

The console raises the claim's storage request inside the cluster as you, with your role on the cluster, exactly as this command does:

kubectl patch pvc data -p '{"spec":{"resources":{"requests":{"storage":"10Gi"}}}}'

A volume a pod is using grows while it runs, filesystem included, usually within a minute or two; the volume shows Growing until its disk has grown. A claim no pod is using grows the next time a pod mounts it. Volumes cannot shrink, and a request above your plan's largest volume is refused with an event on the claim.

The console cannot grow two kinds of volume:

• A kept volume belongs to no cluster, so it has no claim to raise. Use it in a cluster again, then grow it there.
• A volume you attached again with your own manifest: raise the request of the claim you wrote for it with kubectl, and it grows the same way.

Used on disk

Used on disk is how much space the volume's data takes on our storage, measured every few minutes, kept volumes included. It is an approximation, not the filesystem's own figure:

• Space freed by deleting files is given back when the node trims the filesystem, which it does once a week. Until then, deleted files still count.
• Data that compresses well takes less space on disk than inside the volume, so df in a pod can show more than the console.

A volume that has not been measured yet shows a dash. To see exactly how full the filesystem is, run df -h on the volume's mount path inside a pod that uses it.

Keep data with sahabti-retain

When you delete a claim of the sahabti-retain class — or the whole cluster — its volume leaves the cluster and stays in your workspace's Volumes page, marked Kept, with a volume ID such as kv_0123456789abcdef0123. It keeps counting against your disk quota until you delete it.

Use a kept volume again

In Volumes, open the volume's menu and choose Use in a cluster. You get a manifest like this one to apply in any cluster of the same workspace:

apiVersion: v1
kind: PersistentVolume
metadata:
  name: data-postgres-0-restored
spec:
  capacity:
    storage: 10Gi
  accessModes: [ReadWriteOnce]
  persistentVolumeReclaimPolicy: Retain
  storageClassName: sahabti-retain
  csi:
    driver: disk.sahabti.com
    volumeHandle: kv_0123456789abcdef0123
    fsType: ext4
  nodeAffinity:
    required:
      nodeSelectorTerms:
        - matchExpressions:
            - key: topology.disk.sahabti.com/zone
              operator: In
              values: [zone-1a2b3c4d]
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: data-postgres-0-restored
  namespace: shop
spec:
  storageClassName: sahabti-retain
  volumeName: data-postgres-0-restored
  accessModes: [ReadWriteOnce]
  resources:
    requests:
      storage: 10Gi

Point your workload at the claim and the volume attaches with its data. It belongs to that cluster again until you delete the claim, which keeps it once more.

Each volume lives in one zone, and the manifest pins pods that use it to workers in that zone. When you remove workers, the cluster keeps one in every zone that holds a volume as long as your count allows it, and a new worker goes first to a zone that holds a volume but has no worker.

Delete a kept volume

In Volumes, choose Delete volume. Its data is gone for good. A volume a cluster still holds cannot be deleted from that page: delete its claim in the cluster instead.

Limits

Your plan sets how many volumes a cluster may have and how large each may be — see Plans and limits. Every volume, kept or in use, counts against your workspace's disk quota, and a workspace can keep up to twice its per-cluster count of volumes it is not using.