1. Documentation
×

CSI volume group snapshots

Volume group snapshots capture point-in-time copies of multiple volumes simultaneously, gathering data across related volumes. This enables restoring multi-volume applications to a previous state or provisioning new volume sets with the same data for testing or development purposes.

Overview of CSI volume group snapshots

Volume group snapshots capture point-in-time copies of multiple persistent volume claims using label selectors. Three API objects manage snapshots: VolumeGroupSnapshot, VolumeGroupSnapshotContent, and VolumeGroupSnapshotClass.

Volume group snapshots need to be supported by the Container Storage Interface (CSI) driver. OpenShift Data Foundation supports volume group snapshots.

Snapshot

A snapshot represents the state of the storage volume in a cluster at a particular point in time. Volume snapshots can be used to provision a new volume.

Volume group snapshot

A volume group snapshot uses a label selector to group multiple persistent volume claims for snapshotting. A volume group snapshot represents copies from multiple volumes that are taken at the same point-in-time. This can be useful for applications that contain multiple volumes.

To use volume group snapshots, familiarity with persistent volumes is suggested. For information about persistent volumes, see "Understanding persistent volumes".

Volume group snapshots provide three new API objects for managing snapshots:

VolumeGroupSnapshot

Requests creation of a volume group snapshot for multiple persistent volume claims. It contains information about the volume group snapshot operation, such as the timestamp when the volume group snapshot was taken, and whether it is ready to use.

VolumeGroupSnapshotContent

Created by the snapshot controller for a dynamically created volumeGroupSnapshot. It contains information about the volume group snapshot including the volume group snapshot ID. This object represents a provisioned resource on the cluster (a group snapshot). The VolumeGroupSnapshotContent object binds to the volume group snapshot for which it was created with a one-to-one mapping.

VolumeGroupSnapshotClass

Created by cluster administrators to describe how volume group snapshots should be created, including the driver information, the deletion policy, etc.

These three API kinds are defined as CustomResourceDefinitions (CRDs). These CRDs are installed by default in the OKD cluster so that CSI drivers can support volume group snapshots.

CSI volume group snapshots limitations

Volume group snapshots have operational and consistency limitations that affect how you can use them for data protection and recovery. Understanding these constraints helps you design appropriate backup and recovery strategies for multi-volume applications.

Volume group snapshots have the following limitations:

  • Does not support reverting an existing persistent volume claim (PVC) to an earlier state represented by a snapshot. You can only provision a new volume from a snapshot.

  • No guarantees of application consistency, for example, crash consistency, are provided beyond those provided by the storage system. For more information about application consistency, see "Quiesce and Unquiesce Hooks".

  • Volume group snapshots need to be supported by the Container Storage Interface (CSI) driver. OpenShift Data Foundation supports volume group snapshots.

Additional resources

Creating a volume group snapshot class

Create a VolumeGroupSnapshotClass to define how volume group snapshots are provisioned, including the Container Storage Interface (CSI) driver and deletion policy. Cluster administrators must create this class before users can provision volume group snapshots.

Prerequisites

  • Logged in to a running OKD cluster with administrator privileges.

Procedure

  1. Create a VolumeGroupSnapshotClass YAML file using the following example file:

    Example volume group snapshot class YAML file
    apiVersion: groupsnapshot.storage.k8s.io/v1
kind: VolumeGroupSnapshotClass
metadata:
  name: csi-hostpath-groupsnapclass
deletionPolicy: Delete
driver: hostpath.csi.k8s.io
     …...

    • kind: Specifies the VolumeGroupSnapshotClass object.

    • metadata.name: Name of the VolumeGroupSnapshotClass.

  2. Create the 'VolumeGroupSnapshotClass' object by running the following command:

    $ oc create -f <volume-group-snapshot-class-filename>.yaml

Creating a volume group snapshot

Create a VolumeGroupSnapshot object to capture point-in-time copies of multiple persistent volume claims (PVCs). Label the PVCs, specify the VolumeGroupSnapshotClass, and individual VolumeSnapshot objects are created automatically.

When you create a VolumeGroupSnapshot object, OKD creates a volume group snapshot.

Prerequisites

  • Logged in to a running OKD cluster.

  • The persistent volume claims (PVCs) that you want to group for the snapshot have been created using a CSI driver that supports VolumeGroupSnapshot objects.

  • A storage class to provision the storage back end.

  • Administrator has created the VolumeGroupSnapshotClass object.

Procedure

  1. Locate (or create) the PVCs that you want to include in the volume group snapshot by running the following command:

    $ oc get pvc
    Example
    NAME        STATUS    VOLUME                                     CAPACITY   ACCESSMODES   AGE
pvc-0       Bound     pvc-a42d7ea2-e3df-11ed-b5ea-0242ac120002   1Gi        RWO           48s
pvc-1       Bound     pvc-a42d81b8-e3df-11ed-b5ea-0242ac120002   1Gi        RWO           48S

    This example uses two PVCs

  2. Label the PVCs to belong to a snapshot group:

    1. Label PVC pvc-0 by running the following command:

      $ oc label pvc pvc-0 group=myGroup
      Example output
      persistentvolumeclaim/pvc-0 labeled

    2. Label PVC pvc-1 by running the following command:

      Example output
      $ oc label pvc pvc-1 group=myGroup
      Example output
      persistentvolumeclaim/pvc-1 labeled

      In this example, you are labeling PVC "pvc-0" and "pvc-1" to belong to group "myGroup".

  3. Create a VolumeGroupSnapshot object to specify your volume group snapshot:

    1. Create a VolumeGroupSnapshot object YAML file with the following example file:

      Example VolumeGroupSnapshot YAML file
      apiVersion: groupsnapshot.storage.k8s.io/v1
kind: VolumeGroupSnapshot
metadata:
  name: <volume-group-snapshot-name>
  namespace: <namespace>
spec:
  volumeGroupSnapshotClassName: <volume-group-snapshot-class-name>
  source:
    selector:
      matchLabels:
        group: myGroup

      • kind: The VolumeGroupSnapshot object requests creation of a volume group snapshot for multiple PVCs.

      • metadata.name: Name of the volume group snapshot.

      • metadata.namespace: Namespace for the volume group snapshot.

      • spec.volumeGroupSnapshotClassName: The VolumeGroupSnapshotClass name. This object is created by the administrator and describes how volume group snapshots should be created.

      • spec.source.selector.matchLabels.group: The name of the label used to group the required PVCs for the snapshot. In this example, it is "myGroup".

    2. Create the VolumeGroupSnapshot object by running the following command:

      $ oc create -f <volume-group-snapshot-filename>.yaml
Results

Individual volume snapshots are created according to how many PVCs were specified as part of the volume group snapshot.

These individual volume snapshots are named with the following format: <hash of VolumeGroupSnaphotContentUUID+volumeHandle>:

apiVersion: snapshot.storage.k8s.io/v1
kind: VolumeSnapshot
metadata:
  name: snapshot-4dc1c53a29538b36e85003503a4bcac5dbde4cff59e81f1e3bb80b6c18c3fd03
  namespace: default
  ownerReferences:
  - apiVersion: groupsnapshot.storage.k8s.io/v1
    kind: VolumeGroupSnapshot
    name: my-groupsnapshot
    uid: ba2d60c5-5082-4279-80c2-daa85f0af354
  resourceVersion: "124503"
  uid: c0137282-f161-4e86-92c1-c41d36c6d04c
spec:
  source:
    persistentVolumeClaimName:pvc-1
status:
  volumeGroupSnapshotName: volume-group-snapshot-name

In the preceding example, two individual volume snapshots are created as part of the volume group snapshot.

snapshot-4dc1c53a29538b36e85003503a4bcac5dbde4cff59e81f1e3bb80b6c18c3fd03
snapshot-fbfe59eff570171765df664280910c3bf1a4d56e233a5364cd8cb0152a35965b

Restoring a volume group snapshot

Restore volumes from a volume group snapshot by creating new persistent volume claims (PVCs) from individual VolumeSnapshot objects. Each PVC provisions a volume populated with snapshot data. Repeat for each VolumeSnapshot in the group to restore all volumes to their previous state.

Prerequisites

  • Logged in to a running OKD cluster.

  • PVC has been created using a Container Storage Interface (CSI) driver that supports volume group snapshots.

  • A storage class to provision the storage back end.

  • A volume group snapshot has been created and is ready to use.

Procedure

  1. Specify a VolumeSnapshot data source from a volume group snapshot for a PVC as shown in the following example:

    Example restore PVC YAML file
    apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: <pvc-restore-name>
  namespace: <namespace>
spec:
  storageClassName: csi-hostpath-sc
  dataSource:
    name: snapshot-fbfe59eff570171765df664280910c3bf1a4d56e233a5364cd8cb0152a35965b
    kind: VolumeSnapshot
    apiGroup: snapshot.storage.k8s.io
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi

    • metadata.name: Name of the restore PVC.

    • metadata.namespace: Name of the namespace.

    • spec.dataSource.name: Name of an individual volume snapshot that is part of the volume group snapshot to use as source.

    • spec.dataSource.kind: Must be set to the VolumeSnapshot value.

    • spec.dataSource.apiGroup: Must be set to the snapshot.storage.k8s.io value.

  2. Create the PVC by running the following command:

    $ oc create -f <pvc-restore-filename>.yaml

    Where <pvc-restore-filename>.yaml is the name of the PVC restore file specified in the preceding step.

  3. Verify that the restored PVC has been created by running the following command:

    $ oc get pvc

    A new PVC with the name you specified in the first step is displayed.

  4. Repeat the procedure as needed until all volumes are created from all the snapshots that are part of a volume group snapshot.

Additional resources