The VolumeSnapshot CRD — schema, lifecycle, and the restore procedure

The VolumeSnapshot API is a set of three CRDs that together provide the snapshot lifecycle. This lesson walks the schema, the lifecycle, the restore procedure, and the production patterns.

The three CRDs

The snapshot API defines three CRDs:

flowchart LR
    A[VolumeSnapshotClass] -->|provisions| B[VolumeSnapshotContent]
    B -->|binds to| C[VolumeSnapshot]
    C -->|user request| D[User]

• VolumeSnapshotClass: the template that defines the CSI driver, the parameters, and the deletion policy. Like a StorageClass for snapshots.
• VolumeSnapshotContent: the cluster-side object that represents the actual snapshot on the storage backend. Like a PV for snapshots.
• VolumeSnapshot: the user-facing object that represents a request for a snapshot (or the binding to one). Like a PVC for snapshots.

VolumeSnapshotClass

apiVersion: snapshot.storage.k8s.io/v1
kind: VolumeSnapshotClass
metadata:
  name: postgres-snap
driver: ebs.csi.aws.com
deletionPolicy: Retain
parameters:
  type: snap

The fields:

• driver: the CSI driver that creates the snapshot.
• deletionPolicy: Retain (keep the snapshot on the backend when the VolumeSnapshot is deleted) or Delete (delete the snapshot when the VolumeSnapshot is deleted).
• parameters: CSI driver-specific parameters.

VolumeSnapshot

apiVersion: snapshot.storage.k8s.io/v1
kind: VolumeSnapshot
metadata:
  name: postgres-snap-20260816
spec:
  volumeSnapshotClassName: postgres-snap
  source:
    persistentVolumeClaimName: data-postgres-0

The fields:

• volumeSnapshotClassName: the VolumeSnapshotClass that defines the snapshot parameters.
• source.persistentVolumeClaimName: the PVC to snapshot.

When submitted, the snapshot controller calls the CSI driver’s CreateSnapshot, which calls the backend’s snapshot API.

VolumeSnapshotContent

The cluster-side object that represents the snapshot:

apiVersion: snapshot.storage.k8s.io/v1
kind: VolumeSnapshotContent
metadata:
  name: snapcontent-7c8f2d8e-...
spec:
  volumeSnapshotClassName: postgres-snap
  volumeSnapshotRef:
    name: postgres-snap-20260816
    namespace: default
  source:
    volumeHandle: snap-0123456789abcdef0
  driver: ebs.csi.aws.com

The user typically does not create this directly; it is created by the snapshot controller in response to a VolumeSnapshot.

The lifecycle

stateDiagram-v2
    [*] --> Pending: VolumeSnapshot created
    Pending --> Ready: snapshot created on backend
    Ready --> Pending: restoring
    Ready --> [*]: deletion policy triggered
    Pending --> Failed: snapshot creation failed

The states:

• Pending: the snapshot is being created; the snapshot controller is calling the CSI driver.
• Ready: the snapshot is created on the backend; status.readyToUse: true.
• Failed: the snapshot creation failed; check events.

The restore procedure

The restore creates a new PVC from the snapshot:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: data-postgres-restored
spec:
  accessModes: ["ReadWriteOnce"]
  storageClassName: db-ssd
  resources:
    requests:
      storage: 100Gi
  dataSource:
    name: postgres-snap-20260816
    kind: VolumeSnapshot
    apiGroup: snapshot.storage.k8s.io

The dataSource field references the VolumeSnapshot. The PVC is bound to a new PV that is restored from the snapshot.

# Verify the restore
kubectl get pvc data-postgres-restored
# STATUS: Bound
# CAPACITY: 100Gi

# Mount in a recovery Pod
kubectl apply -f postgres-recovery-pod.yaml

The deletion policy

The deletion policy determines what happens when the VolumeSnapshot is deleted:

For backup-grade snapshots, use Retain. The VolumeSnapshot is removed from the cluster, but the backend snapshot persists; the operator can re-create the VolumeSnapshot object pointing to the same backend snapshot.

Quiz

Production discipline

• VolumeSnapshotClass per workload. Like StorageClass per workload tier.
• Retain for backup-grade snapshots. The VolumeSnapshot can be deleted; the backend snapshot persists.
• Test the restore regularly. A snapshot that is never restored is not a backup.
• Document the restore procedure. Every snapshot policy has a documented restore.
• Monitor the snapshot controller. Its health affects every snapshot.