Snapshots

A snapshot is a copy of a Persistent Volume (PVC) at a point in time without creating a new volume. Snapshots are created by the storage backend through compatible CSI drivers and are used for fast rollback, volume cloning, and restore points before risky operations (for example, before a database upgrade).

In the Shturval platform, snapshot support is provided by the shturval-snapshotter operator (CSI Snapshotter). The operator is critical for the platform (it cannot be disabled). By default it is installed and enabled in client clusters and in the management cluster. For details, see shturval-snapshotter.

What snapshots are for #

• Restore point — before an application upgrade, database migration, or bulk data change, create a snapshot and roll back if needed.
• Volume cloning — create a new PVC with the same data from a snapshot (without exporting data out of the storage system).
• Short-term protection — a quick snapshot on the same storage platform without copying to external storage.

Snapshots do not replace a full backup of the cluster and data to external storage. For the differences, see What is the difference between backups and snapshots.

Kubernetes objects for snapshots #

The snapshotter operator installs the following CRDs (Custom Resource Definitions):

Typical flow: the user creates a VolumeSnapshot, specifying the source PVC and a VolumeSnapshotClass. The snapshotter controller creates the snapshot through the CSI driver and, on success, creates or updates VolumeSnapshotContent. When the snapshot is ready, you can create a new PVC from it (restore or clone).

CSI driver support #

Snapshots require a compatible CSI driver. Behavior depends on the driver: some create a snapshot without stopping the workload, others only after stopping the workload (pods must not use the PVC).

¹ For VMware vSphere, enable the snapshotter sidecar in the CSI customvalues and grant the vCenter account permissions for volume snapshots (CNS Searchable, Datastore.FileManagement). See VMware vSphere account requirements, the vSphere tab in step 1 and step 2.

Before using snapshots, make sure snapshotter CRDs (shturval-snapshotter-crds) and the snapshotter operator (shturval-snapshotter) are enabled, along with the CSI module for your volume type. Deploy the CRDs first, then the operator. VolumeSnapshotClass must reference a driver compatible with your StorageClass.

Where to manage snapshots #

• Operator status: Services and Repositories → Installed Services → find Snapshotter operator (shturval-snapshotter) → Manage.
• Snapshot objects (CR): select the cluster → Administration → Custom Resources. In the search field, enter snap to filter CRDs related to volume snapshots.

The Custom Resources table shows the API group, custom resource, and number of resources in the cluster. Individual volume snapshots use the snapshot.storage.k8s.io group — VolumeSnapshot, VolumeSnapshotClass, VolumeSnapshotContent. The groupsnapshot.storage.k8s.io group contains types for group snapshots: VolumeGroupSnapshot, VolumeGroupSnapshotClass, VolumeGroupSnapshotContent. Click a resource name to open its instances and create or view objects. Sorting, API-group filters, and Clear all filters are available.

You can also apply manifests through manifest import or kubectl apply -f.

How to create, restore, and clone a volume #

Commands in each step are the same for all drivers. VolumeSnapshotClass, VolumeSnapshot, and PVC manifests are on the tab for your driver.

Step 1. Check VolumeSnapshotClass #

kubectl get VolumeSnapshotClass

If the class for your driver is missing, create it as shown below for each CSI provider. Upload the VolumeSnapshotClass manifest through manifest import: import icon to the left of your username → paste or upload YAML → Check → Save.

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

apiVersion: snapshot.storage.k8s.io/v1
kind: VolumeSnapshotClass
metadata:
  name: cephfs
driver: cephfs.csi.ceph.com
deletionPolicy: Delete
parameters:
  clusterID: <clusterID>
  fsName: <filesystem-name>
  csi.storage.k8s.io/snapshotter-secret-name: <secret-name>
  csi.storage.k8s.io/snapshotter-secret-namespace: ceph-csi-operator

apiVersion: snapshot.storage.k8s.io/v1
kind: VolumeSnapshotClass
metadata:
  name: cephrbd
driver: rbd.csi.ceph.com
deletionPolicy: Delete
parameters:
  clusterID: <clusterID>
  pool: <pool-name>
  csi.storage.k8s.io/snapshotter-secret-name: <secret-name>
  csi.storage.k8s.io/snapshotter-secret-namespace: ceph-csi-operator

apiVersion: ops.shturval.tech/v1beta2
kind: ShturvalServicePatch
metadata:
  name: capvs-csi-volume-snapshots
spec:
  shturvalServiceConfigName: shturval-capvs-csi
  customvalues:
    controller:
      config:
        block-volume-snapshot: true

apiVersion: snapshot.storage.k8s.io/v1
kind: VolumeSnapshotClass
metadata:
  name: vspherecsi
driver: csi.vsphere.vmware.com
deletionPolicy: Delete
parameters: {}

apiVersion: snapshot.storage.k8s.io/v1
kind: VolumeSnapshotClass
metadata:
  name: cinder
driver: cinder.csi.openstack.org
deletionPolicy: Delete
parameters:
  force-create: "true"

apiVersion: snapshot.storage.k8s.io/v1
kind: VolumeSnapshotClass
metadata:
  name: nfs
driver: nfs.csi.k8s.io
deletionPolicy: Delete
parameters: {}

Step 2. Create a VolumeSnapshot #

Select the driver tab, set the source PVC, and apply the manifest:

kubectl apply -f volumesnapshot.yaml

kubectl scale statefulset <statefulset-name> -n <namespace> --replicas=0

apiVersion: snapshot.storage.k8s.io/v1
kind: VolumeSnapshot
metadata:
  name: <snapshot-name>
  namespace: <namespace>
spec:
  volumeSnapshotClassName: rawfile-localpv
  source:
    persistentVolumeClaimName: <pvc-name>

apiVersion: snapshot.storage.k8s.io/v1
kind: VolumeSnapshot
metadata:
  name: <snapshot-name>
  namespace: <namespace>
spec:
  volumeSnapshotClassName: cephfs
  source:
    persistentVolumeClaimName: <pvc-name>

apiVersion: snapshot.storage.k8s.io/v1
kind: VolumeSnapshot
metadata:
  name: <snapshot-name>
  namespace: <namespace>
spec:
  volumeSnapshotClassName: cephrbd
  source:
    persistentVolumeClaimName: <pvc-name>

apiVersion: snapshot.storage.k8s.io/v1
kind: VolumeSnapshot
metadata:
  name: <snapshot-name>
  namespace: <namespace>
spec:
  volumeSnapshotClassName: vspherecsi
  source:
    persistentVolumeClaimName: <pvc-name>

apiVersion: snapshot.storage.k8s.io/v1
kind: VolumeSnapshot
metadata:
  name: <snapshot-name>
  namespace: <namespace>
spec:
  volumeSnapshotClassName: cinder
  source:
    persistentVolumeClaimName: <pvc-name>

apiVersion: snapshot.storage.k8s.io/v1
kind: VolumeSnapshot
metadata:
  name: <snapshot-name>
  namespace: <namespace>
spec:
  volumeSnapshotClassName: nfs
  source:
    persistentVolumeClaimName: <pvc-name>

Step 3. Wait until the snapshot is ready #

kubectl get VolumeSnapshot -n <namespace>

Confirm that the READYTOUSE column is true.

Step 4. Restore or clone the PVC #

Set the snapshot in dataSource and apply the PersistentVolumeClaim manifest. The requested volume size must be at least the original size.

• Restore the same volume (for example, a StatefulSet PVC): stop the workload, delete the original PVC, create a PVC with the same name from the snapshot, then start the workload again.

Example of restoring a StatefulSet PVC:

kubectl scale statefulset <statefulset-name> -n <namespace> --replicas=0
kubectl delete pvc -n <namespace> <pvc-name>
kubectl apply -f pvc-from-snapshot.yaml
kubectl scale statefulset <statefulset-name> -n <namespace> --replicas=1

• Clone: create a PVC with a new name. You do not have to delete the original volume:

kubectl apply -f pvc-from-snapshot.yaml

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: <pvc-name>
  namespace: <namespace>
spec:
  storageClassName: local-path
  dataSource:
    name: <snapshot-name>
    kind: VolumeSnapshot
    apiGroup: snapshot.storage.k8s.io
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: <size>

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: <pvc-name>
  namespace: <namespace>
spec:
  storageClassName: csi-cephfs-sc
  dataSource:
    name: <snapshot-name>
    kind: VolumeSnapshot
    apiGroup: snapshot.storage.k8s.io
  accessModes:
    - ReadWriteMany
  resources:
    requests:
      storage: <size>

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: <pvc-name>
  namespace: <namespace>
spec:
  storageClassName: csi-cephrbd-sc
  dataSource:
    name: <snapshot-name>
    kind: VolumeSnapshot
    apiGroup: snapshot.storage.k8s.io
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: <size>

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: <pvc-name>
  namespace: <namespace>
spec:
  storageClassName: vsphere-csi
  dataSource:
    name: <snapshot-name>
    kind: VolumeSnapshot
    apiGroup: snapshot.storage.k8s.io
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: <size>

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: <pvc-name>
  namespace: <namespace>
spec:
  storageClassName: csi-cinder-sc-delete
  dataSource:
    name: <snapshot-name>
    kind: VolumeSnapshot
    apiGroup: snapshot.storage.k8s.io
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: <size>

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: <pvc-name>
  namespace: <namespace>
spec:
  storageClassName: nfs-csi
  dataSource:
    name: <snapshot-name>
    kind: VolumeSnapshot
    apiGroup: snapshot.storage.k8s.io
  accessModes:
    - ReadWriteMany
  resources:
    requests:
      storage: <size>

apiVersion: v1
kind: Pod
metadata:
  name: pvc-init
  namespace: <namespace>
spec:
  containers:
  - name: pause
    image: r.shturval.tech/pause:3.10.1
    volumeMounts:
    - mountPath: /data
      name: data
  volumes:
  - name: data
    persistentVolumeClaim:
      claimName: <pvc-name>

Backing up snapshot objects #

You can include VolumeSnapshot and VolumeSnapshotContent resources in a backup, but that does not copy snapshot data.

After you restore those resources, snapshots are in READYTOUSE=false. The field may later become true, but that is a new snapshot state, not the restored original snapshot data.

A PV backup also does not restore snapshot data. To keep the data, use a backup to external storage.

Limits and recommendations #

• A snapshot captures the volume at creation time. Data written after that is not in the snapshot.
• For application-consistent data (for example, a database), stop writes or use application mechanisms (flush, freeze) before creating the snapshot. For RawFile, stopping the workload is required.
• Snapshots consume space in the same storage system; keeping a large number of snapshots for a long time may be limited by quotas and provider policies.
• Deleting a PVC that still has snapshots may be blocked or may require deleting the snapshots first, depending on the reclaim policy and driver.
• VolumeSnapshotClass deletionPolicy: Delete removes snapshot contents with the object; Retain keeps the contents in the storage system.