Edit This Page

Volume Snapshots

This document describes the current state of VolumeSnapshots in Kubernetes. Familiarity with persistent volumes is suggested.


Similar to how API resources PersistentVolume and PersistentVolumeClaim are used to provision volumes for users and administrators, VolumeSnapshotContent and VolumeSnapshot API resources are provided to create volume snapshots for users and administrators.

A VolumeSnapshotContent is a snapshot taken from a volume in the cluster that has been provisioned by an administrator. It is a resource in the cluster just like a PersistentVolume is a cluster resource.

A VolumeSnapshot is a request for snapshot of a volume by a user. It is similar to a PersistentVolumeClaim.

While VolumeSnapshots allow a user to consume abstract storage resources, cluster administrators need to be able to offer a variety of VolumeSnapshotContents without exposing users to the details of how those volume snapshots should be provisioned. For these needs there is the VolumeSnapshotClass resource.

Users need to be aware of the following when using this feature:

Lifecycle of a volume snapshot and volume snapshot content

VolumeSnapshotContents are resources in the cluster. VolumeSnapshots are requests for those resources. The interaction between VolumeSnapshotContents and VolumeSnapshots follow this lifecycle:

Provisioning Volume Snapshot

There are two ways snapshots may be provisioned: statically or dynamically.


A cluster administrator creates a number of VolumeSnapshotContents. They carry the details of the real storage which is available for use by cluster users. They exist in the Kubernetes API and are available for consumption.


When none of the static VolumeSnapshotContents the administrator created matches a user’s VolumeSnapshot, the cluster may try to dynamically provision a volume snapshot specially for the VolumeSnapshot object. This provisioning is based on VolumeSnapshotClasses: the VolumeSnapshot must request a volume snapshot class and the administrator must have created and configured that class in order for dynamic provisioning to occur.


A user creates, or has already created in the case of dynamic provisioning, a VolumeSnapshot with a specific amount of storage requested and with certain access modes. A control loop watches for new VolumeSnapshots, finds a matching VolumeSnapshotContent (if possible), and binds them together. If a VolumeSnapshotContent was dynamically provisioned for a new VolumeSnapshot, the loop will always bind that VolumeSnapshotContent to the VolumeSnapshot. Once bound, VolumeSnapshot binds are exclusive, regardless of how they were bound. A VolumeSnapshot to VolumeSnapshotContent binding is a one-to-one mapping.

VolumeSnapshots will remain unbound indefinitely if a matching VolumeSnapshotContent does not exist. VolumeSnapshots will be bound as matching VolumeSnapshotContents become available.


Deletion removes both the VolumeSnapshotContent object from the Kubernetes API, as well as the associated storage asset in the external infrastructure.

Volume Snapshot Contents

Each VolumeSnapshotContent contains a spec, which is the specification of the volume snapshot.

kind: VolumeSnapshotContent
  name: new-snapshot-content-test
  snapshotClassName: csi-hostpath-snapclass
    name: pvc-test
    kind: PersistentVolumeClaim
      creationTime:    1535478900692119403
      driver:          csi-hostpath
      restoreSize:     10Gi
      snapshotHandle:  7bdd0de3-aaeb-11e8-9aae-0242ac110002


A VolumeSnapshotContent can have a class, which is specified by setting the snapshotClassName attribute to the name of a VolumeSnapshotClass. A VolumeSnapshotContent of a particular class can only be bound to VolumeSnapshots requesting that class. A VolumeSnapshotContent with no snapshotClassName has no class and can only be bound to VolumeSnapshots that request no particular class.


Each VolumeSnapshot contains a spec and a status, which is the specification and status of the volume snapshot.

kind: VolumeSnapshot
  name: new-snapshot-test
  snapshotClassName: csi-hostpath-snapclass
    name: pvc-test
    kind: PersistentVolumeClaim


A volume snapshot can request a particular class by specifying the name of a VolumeSnapshotClass using the attribute snapshotClassName. Only VolumeSnapshotContents of the requested class, ones with the same snapshotClassName as the VolumeSnapshot, can be bound to the VolumeSnapshot.