Kubernetes CSI Volume Snapshots and Restore Explained

Kubernetes CSI volume snapshots give platform teams a declarative way to capture a persistent volume and provision a new volume from that point in time. They are useful before upgrades, data migrations, and recovery tests, but they depend on the storage driver and do not automatically make an application-consistent backup. This guide explains the Kubernetes APIs, the controller and CSI driver flow, and how to create and restore a snapshot without confusing it with a complete backup plan.

What Are Kubernetes CSI Volume Snapshots?

A Kubernetes volume snapshot is a control-plane object representing a point-in-time copy of a persistent volume on a storage system. The feature uses the Container Storage Interface (CSI), a standard that lets storage systems expose operations such as volume creation and snapshotting to container orchestrators. The Kubernetes project provides the orchestration platform; the storage provider’s CSI driver performs the backend-specific work.

The official Volume Snapshot documentation defines three API resources:

• VolumeSnapshot is a namespaced request for a snapshot, much like a PersistentVolumeClaim (PVC) requests storage.
• VolumeSnapshotContent is a cluster-scoped representation of the snapshot on the storage system, comparable to a PersistentVolume.
• VolumeSnapshotClass selects the CSI driver and its snapshot parameters, including what happens to the backing snapshot when the Kubernetes object is deleted.

The Container Storage Interface specification defines the driver protocol, including the operations needed to create and delete snapshots and provision a volume from one. Kubernetes provides the API and coordination; it does not store or copy the volume’s data itself.

Why the Snapshot API Exists

Before a common API, operators often needed storage-vendor commands or scripts that were tightly coupled to one backend. Those tools can still be useful, but they are difficult to coordinate consistently with Kubernetes claims, namespaces, and workload automation.

The snapshot API makes the request declarative. A user creates a VolumeSnapshot; Kubernetes controllers reconcile that request with a content object and the storage driver. The same object model can be used with different CSI implementations, although supported features and performance remain driver-specific. This is especially valuable for repeatable pre-change checkpoints and restore drills.

How Snapshot Creation and Restore Work

The snapshot controller and a driver-side helper split the work. The snapshot controller watches VolumeSnapshot and VolumeSnapshotContent objects, creates and binds the matching content object, and reports lifecycle status. The CSI external-snapshotter sidecar runs with the CSI driver, watches relevant content objects, and asks the driver to create or remove the snapshot in the backend. The CSI snapshotter project documents this controller and sidecar architecture.

The flow is asynchronous: a snapshot request may exist before the backend operation is complete. Check the readyToUse status rather than treating object creation as proof that the data is ready. The controller and snapshot CRDs are cluster-level components generally installed by a Kubernetes distribution; a CSI driver must also support snapshots and run the compatible sidecar. The Kubernetes CSI documentation explains the boundary between the standard and individual driver implementations.

A snapshot is a fast recovery point, not automatically a second independent copy. Retention, isolation, export, and application consistency need their own design.

Key Resources and Behaviors

The source PVC must be in the same namespace as its VolumeSnapshot. A VolumeSnapshotClass is cluster-scoped and names the CSI driver, so the driver name must exactly match a driver installed in the cluster. Its deletion policy is consequential: Delete permits deletion of the backing snapshot when the Kubernetes snapshot is deleted, while Retain keeps the backend copy for administrator-managed cleanup.

The snapshot becomes usable when the backend operation completes and the controller reports it ready. To restore, create a new PVC with dataSource pointing to the snapshot. Kubernetes then asks the storage provisioner to create a volume populated from that snapshot. The selected storage class and driver must support this operation, and the requested capacity must be large enough for the source data. Topology restrictions can also affect where the restored volume can be provisioned.

Snapshots are not necessarily application-consistent. A storage-level copy may preserve a crash-recoverable disk state without coordinating with a database transaction or flushing application buffers. Quiesce writes or use the application’s backup procedure when that distinction matters. For multi-volume applications, separate snapshots may capture different moments; use application coordination or a supported group-snapshot workflow if the data must be captured together.

Real-World Uses

• Before a risky change: Capture a PVC before a schema migration or application upgrade, then restore to a new claim if the change fails.
• Recovery exercises: Provision a separate volume from a snapshot and test the actual application recovery process without overwriting production data.
• Development and analysis: Create a temporary copy of a persistent dataset for debugging or validation, subject to privacy and access controls.
• Storage operations: Use snapshots as one step in a planned migration or recovery process, after confirming the driver, topology, and backend support the intended path.

These are only safe when access, encryption, retention, and cleanup are accounted for. A retained snapshot can preserve sensitive data after its source PVC has been removed.

Getting Started: Create and Restore a Snapshot

First confirm that the cluster has installed the snapshot API and a compatible CSI driver and class:

kubectl api-resources --api-group=snapshot.storage.k8s.io
kubectl get volumesnapshotclass
kubectl get storageclass
kubectl get pvc -n production

If the snapshot resources are missing, ask the cluster administrator to install the distribution-supported snapshot CRDs and controller. Do not assume that installing a CSI driver alone installs those cluster-level components. Check the driver vendor’s compatibility and installation instructions before applying manifests.

The following example assumes an AWS EBS CSI driver is installed and the source claim app-data exists in the production namespace. Adapt the driver, claim, and class for your backend. Save as volume-snapshot.yaml:

apiVersion: snapshot.storage.k8s.io/v1
kind: VolumeSnapshotClass
metadata:
  name: ebs-snapshot-retain
driver: ebs.csi.aws.com
deletionPolicy: Retain
---
apiVersion: snapshot.storage.k8s.io/v1
kind: VolumeSnapshot
metadata:
  name: app-data-before-change
  namespace: production
spec:
  volumeSnapshotClassName: ebs-snapshot-retain
  source:
    persistentVolumeClaimName: app-data

Apply the manifest, then wait for the snapshot to become ready:

kubectl apply -f volume-snapshot.yaml
kubectl get volumesnapshot app-data-before-change -n production
kubectl describe volumesnapshot app-data-before-change -n production

The VolumeSnapshot should show READYTOUSE as true. If it remains pending, inspect the object events and the snapshot-controller and CSI sidecar logs before retrying. Do not delete the source PVC to troubleshoot a snapshot request.

To restore, create a different PVC and point its dataSource at the snapshot. This example assumes a compatible gp3 StorageClass is available and the source claim is 20 GiB; choose a class and capacity supported by your own driver:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: app-data-restore
  namespace: production
spec:
  storageClassName: gp3
  dataSource:
    name: app-data-before-change
    kind: VolumeSnapshot
    apiGroup: snapshot.storage.k8s.io
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 20Gi

Create the claim and check provisioning:

kubectl apply -f restored-pvc.yaml
kubectl get pvc app-data-restore -n production
kubectl describe pvc app-data-restore -n production
kubectl get events -n production --sort-by=.lastTimestamp

Once the claim is Bound, mount it in a controlled workload and verify the filesystem and application data. A bound PVC only confirms that storage was provisioned; it does not prove that the application can recover correctly. Keep the original data untouched until that test succeeds.

Common causes of a stuck snapshot or restore include missing snapshot CRDs or controller, a driver without snapshot support, a mismatched driver name in the VolumeSnapshotClass, unavailable storage capacity, an unsupported topology, or an undersized restore claim. Inspect kubectl describe events first, then consult the distribution and CSI driver logs and compatibility matrix. Avoid changing deletion policies or removing content objects as a blind retry.

For general background on PVCs, StorageClasses, and CSI, see the container storage guide. For how stateful workloads use persistent claims, see Kubernetes StatefulSets and persistent workloads. Snapshots should also fit into an independent retention and recovery plan; the backup strategy guide explains those broader safeguards.

Common Misconceptions

“A snapshot is a backup.” A snapshot can accelerate recovery, but it may share the source’s failure domain and can be deleted by the same credentials or policy. Keep independent, appropriately isolated backups for disaster recovery.

“Kubernetes snapshots are application-consistent.” The API requests a storage snapshot; it does not automatically pause every process or flush database transactions. Use application-level coordination when crash consistency is insufficient.

“Every CSI driver can restore every snapshot.” CSI standardizes the interface, not the underlying storage features or portability. A snapshot generally depends on compatible driver and backend support, and topology may constrain where a restored volume can run.

Related Articles

• Container storage guide
• Kubernetes StatefulSets and persistent workloads
• Backup strategy best practices

Changelog

• 2026-10-27: Published the canonical explainer for Kubernetes CSI volume snapshots and restore.