The distro installs them and one snapshot-controller; each driver runs a csi-snapshotter (v8.6.0, CSI Drivers). CEL rules in the CRDs replaced the webhook (gone in v8.2.0); VolumeSnapshotClass has none, so edits pass.
2.One dynamic snapshot
No class : the driver's one class with is-default-class: "true". Zero or two fail (unlike StorageClass).
Driver returns at the cut; readyToUse may lag hours.
Field
VolumeSnapshot
Content
link
boundVolumeSnapshotContentName
volumeSnapshotRef
handle
none
snapshotHandle
creationTime
date-time
int64 ns
restoreSize
quantity
int64 bytes
3.Pre-provisioned, deletionPolicy
Import : a content with snapshotHandle, deletionPolicy, volumeSnapshotRef, ideally sourceVolumeMode.
Trust it if both point at each other. Delete the VS, not the content (finalizers).
When
Delete
Retain
VS deleted
storage snapshot goes
both stay
namespace gone
storage snapshot goes
content orphaned
imported
set by hand
set by hand
Velero
once backup expires
while backup exists
4.Restore : always a new PVC
dataSourceRef names the VolumeSnapshot. No revert in place.
Mode guard (GA v1.30) : Block <-> Filesystem needs allow-volume-mode-change: "true" on the content, so content write access is powerful (RBAC).
Errors : ProvisioningFailed on the PVC.
Check, in order
Error says
CREATE_DELETE_SNAPSHOT
capability is not reported
snapshot not deleting
is being deleted
bound, content points back
bound to a different snapshot
content driver = provisioner
not handled by CSI driver of ...
readyToUse and a handle
is not Ready
size >= restoreSize
is less than the size
volume mode guard
does not have permission
5.Clone a PVC
Source PVC in dataSource : Bound, storageClassName on both, size >= source, same driver (any class, v3.2.0+), same volumeMode, CLONE_VOLUME.
Same namespace (cross-namespace is alpha). Errors say not bound or invalid : see the provisioner log.
6.Commands
Command
Shows
kubectl get vs -n <ns>
RESTORESIZE 1Gi
kubectl get vsc
in bytes
kubectl get vsclass -o custom-columns='NAME:.metadata.name,DEFAULT:.metadata.annotations.snapshot\.storage\.kubernetes\.io/is-default-class'
In short : A snapshot is a namespaced request plus a cluster-scoped content holding the storage handle, and they must point at each other. Restores and clones always make a new PVC.
1.dataSource vs dataSourceRef
A custom kind in dataSource is dropped on create, no warning : an empty volume. Use dataSourceRef.
AnyVolumeDataSource : GA v1.33, gate removed in v1.37. Passing it stops the component.
dataSource
dataSourceRef
kinds
PVC, snapshot
any non-core kind, PVC
other kind
dropped silently
rejected
sync
copied to the Ref
copied back if no namespace
both set
must match; both immutable
namespace
must stay empty
alpha gate only
2.Volume populators
Unknown kind : the provisioner assumes a populator, stops.
lib-volume-populator v3.4.0 : waits for selected-node (WFFC), fills prime-<uid>, moves the PV over.
A VolumePopulator (populator.storage.k8s.io/v1beta1) registers each kind. Populators rebind PVs : control-plane code (Operators).
3.Across namespaces (alpha, stalled)
CrossNamespaceVolumeDataSource : alpha, off since v1.26, KEP-3294 closed "not planned". Gate on kube-apiserver, controller-manager and csi-provisioner, plus the ReferenceGrant CRD and RBAC.
The grant sits in the source namespace; an empty to.name opens every object of that kind. Gate off : a namespaced ref is dropped silently.
4.Group snapshots : one cut
GA v1.36. Snapshotter v8.6.0 serves v1, stores v1beta2, gate Beta and off. Driver needs GroupController.
Label the PVCs. Members are owned by the group : none deleted alone, one driver.
Use v1 : conversion is None, so v1beta1 readers lose members and its writes skip CEL (CRDs).
Single
Group
stored
v1
v1beta2 (serves v1)
turn on
CRDs, controller
+ CSIVolumeGroupSnapshot gate
picks
one PVC name
label selector, resolved once
consistency
one volume
crash-consistent across all
restore
PVC from it
one PVC per member
CSI call
CreateSnapshot
CreateVolumeGroupSnapshot
5.Changed block tracking
KEP-3314, beta v1.36, out of tree : the driver advertises SNAPSHOT_METADATA_SERVICE and runs external-snapshot-metadata v1.1.0. Its SnapshotMetadataService gives address, audience, CA.
GetMetadataDelta (base = an older snapshotHandle) returns block ranges, not data. FAILED_PRECONDITION : full backup. Velero 1.18 skips it.
6.Commands
Command
Shows
kubectl get volumepopulators
Registered populator kinds
kubectl get crd volumegroupsnapshots.groupsnapshot.storage.k8s.io -o jsonpath='{range .spec.versions[*]}{.name} served={.served} storage={.storage}{"\n"}{end}'
v1 served, v1beta2 stored
kubectl get vs -n <ns> -o jsonpath='{range .items[?(@.metadata.ownerReferences[0].name=="<vgs>")]}{.metadata.name}{"\n"}{end}'
Members of a group
kubectl get sms
CBT drivers (cbt.storage.k8s.io/v1beta1)
Group snapshots ignored ? In v8.6.0 support is a flag on both snapshot components : check their args before the driver.
In short : Populators fill a PVC from any kind, group snapshots cut many volumes at one crash-consistent point, and changed block tracking makes backups incremental.
1.Why a snapshot is not a backup
It sits on the same storage as the volume and goes with its namespace under Delete. Record handles.
Failure
CSI snapshot
Velero, no data move
Velero data mover, fs-backup
namespace deleted
gone too under Delete
kept (Retain), YAML in bucket
data in the bucket
storage pool lost
lost if kept beside the volume
lost, only the YAML survives
survives if the bucket is elsewhere
whole cluster lost
re-import by snapshotHandle
re-imported, same driver name
any cluster with CSI and the bucket
ransomware, bad write
only if nobody deleted it
same
separate bucket; guard the key
2.Consistency and hooks
One snapshotcrash-consistent
Groupcrash-consistent, all volumes
+ fsfreeze hooksapp-consistent (frozen FS)
fs-backupnot point in time
KEP-3476 : quiesce weekly, group snapshot nightly.
3.Velero v1.18 : three ways
v1.18.4 (now velero-io/velero) needs --features=EnableCSI, though CSI is built in since v1.14. Hooks : no shell; first container, Fail, 30s.
Class pick : PVC annotation, Backup _<driver> annotation, class label velero.io/csi-volumesnapshot-class, the default, the only class.
CSI snapshot
CSI snapshot data movement
fs-backup (kopia)
turn on
--features=EnableCSI
+ --use-node-agent, --snapshot-move-data
--use-node-agent + pod annotation
data goes to
stays on the storage
kopia repo in the BackupStorageLocation
kopia repo
works for
CSI volumes
CSI volumes
mounted volumes, not hostPath
runs as
Velero server
data-mover Pods, root, BestEffort
node-agent, kubelet hostPath
one volume
snapshot or fs-backup, never both. Restic restores stop working in Velero 1.19
4.One backup with data movement
csiSnapshotTimeout (10m) waits for the handle (the cut); itemOperationTimeout (4h) cancels uploads.
All repos share one static key : set repository-password first. Groups : velero.io/volume-group label (1.18.x talks v1beta2).
In short : Snapshots guard against bad writes, not against losing the storage, namespace or cluster. Velero copies data to object storage and restores storage before workloads.