Skip to main content
Version: main

Snapshots

Local PV Rawfile supports block-level volume snapshots using the standard Kubernetes VolumeSnapshot API. Snapshots are node-local and processed as persistent background tasks with automatic retry across driver restarts.

Requirements​

  • Snapshots must be enabled in the chart (default): capabilities.snapshots.enabled=true
  • Kubernetes VolumeSnapshot CRDs must be installed in the cluster
  • A VolumeSnapshotClass must exist for the rawfile driver

Create a VolumeSnapshotClass​

apiVersion: snapshot.storage.k8s.io/v1
kind: VolumeSnapshotClass
metadata:
  name: rawfile-snapshotclass
driver: rawfile.csi.openebs.io
deletionPolicy: Delete

Apply:

kubectl apply -f snapshotclass.yaml

deletionPolicy: Delete removes snapshot data when the VolumeSnapshot object is deleted. Use Retain to preserve the data after object deletion.

Create a Snapshot​

apiVersion: snapshot.storage.k8s.io/v1
kind: VolumeSnapshot
metadata:
  name: app-data-snap
spec:
  volumeSnapshotClassName: rawfile-snapshotclass
  source:
    persistentVolumeClaimName: rawfile-pvc
kubectl apply -f snapshot.yaml
kubectl get volumesnapshot app-data-snap -w

The snapshot is ReadyToUse: true when complete. The snapshot operation runs as a persistent background task on the node that hosts the volume - it survives driver restarts and retries automatically.

Snapshot Consistency​

Two approaches are available for snapshotting active volumes:

Storage pools backed by filesystems which support reflink (i.e. btrfs or XFS) produce space-efficient, nearly instant snapshots. No freeze is required.

freezeFs​

For pools without CoW support, add freezeFs: "true" to the StorageClass. The filesystem is frozen and the entire volume is copied to a new file before it is unfrozen:

parameters:
  csi.storage.k8s.io/fstype: ext4
  freezeFs: "true"
warning

With freezeFs: "true" on a non-CoW pool, the volume's filesystem stays frozen for the entire snapshot duration. All writes to the volume block until the snapshot completes. For large volumes this can take significant time. Prefer a CoW-capable pool filesystem where possible.

Restore a Snapshot to a New PVC​

Specify the snapshot as a dataSource in a new PVC:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: app-data-restored
spec:
  storageClassName: rawfile-localpv
  accessModes:
    - ReadWriteOnce
  dataSource:
    name: app-data-snap
    kind: VolumeSnapshot
    apiGroup: snapshot.storage.k8s.io
  resources:
    requests:
      storage: 10Gi
kubectl apply -f restore.yaml
note

Snapshots are node-local. The restored PVC will be provisioned on the same node that holds the snapshot data.

Roll Back an Application​

A common pattern for rolling back to a previous state:

  1. Scale down the workload to release the PVC:

    kubectl scale deployment my-app --replicas=0

  2. Create a restored PVC from the snapshot (see above).

  3. Update the Deployment to reference the restored PVC:

    kubectl patch deployment my-app \
      -p '{"spec":{"template":{"spec":{"volumes":[{"name":"data","persistentVolumeClaim":{"claimName":"app-data-restored"}}]}}}}'

  4. Scale the workload back up:

    kubectl scale deployment my-app --replicas=1

Delete a Snapshot​

kubectl delete volumesnapshot app-data-snap

With deletionPolicy: Delete, the snapshot data on the node is removed. With Retain, the backing data remains.

important

Delete all VolumeSnapshots before deleting the PVC or uninstalling the driver to avoid leaked data on nodes.

Capacity Considerations​

  • CoW-capable pools (filesystems with reflink enabled): snapshots consume only the changed blocks after the snapshot point.
  • Non-CoW pools: each snapshot is a full copy of the volume and consumes the same amount of space as the original.

Troubleshooting​

SymptomFix
Snapshot stuck in PendingCheck the node plugin logs: kubectl -n openebs logs ds/<release>-node -c csi-driver. Snapshot operations are retried on restart.
Snapshotting capabilities are disabledSet capabilities.snapshots.enabled=true and upgrade the Helm release.
No VolumeSnapshotClass foundCreate a VolumeSnapshotClass with driver: rawfile.csi.openebs.io.
Insufficient disk spaceNon-CoW snapshot requires a full copy - check pool free capacity: rawfile_pool_remaining_capacity_bytes.

Support​

If you encounter issues or have a question, file a Github issue, or talk to us on the #openebs channel on the Kubernetes Slack server.

See Also​