docs: add documentation for rbd volumegroupsnapshot

This PR adds the sample YAMLs and documentation for the RBD VolumeGroupSnapshot. Signed-off-by: Niraj Yadav <niryadav@redhat.com>
2024-10-15 16:09:01 +05:30
parent 09562fdda5
commit 524b6071d2
5 changed files with 126 additions and 7 deletions
@@ -23,12 +23,97 @@ In short, as the documentation describes it:
    Created by cluster administrators to describe how volume group snapshots
    should be created. including the driver information, the deletion policy, etc.

-## Volume Group Snapshots
+## RBD Volume Group Snapshots
+
+### RBD VolumeGroupSnapshotClass
+
+In [VolumeGroupSnapshotClass](https://github.com/rook/rook/tree/master/deploy/examples/csi/rbd/groupsnapshotclass.yaml),
+the `csi.storage.k8s.io/group-snapshotter-secret-name` parameter references the
+name of the secret created for the rbd-plugin and `pool` to reflect the Ceph pool name.
+
+In the `VolumeGroupSnapshotClass`, update the value of the `clusterID` field to match the namespace
+that Rook is running in. When Ceph CSI is deployed by Rook, the operator will automatically
+maintain a configmap whose contents will match this key. By default this is
+"rook-ceph".
+
+```console
+kubectl create -f deploy/examples/csi/rbd/groupsnapshotclass.yaml
+```
+
+### RBD VolumeGroupSnapshot
+
+In [VolumeGroupSnapshot](https://github.com/rook/rook/tree/master/deploy/examples/csi/rbd/groupsnapshot.yaml),
+`volumeGroupSnapshotClassName` is the name of the `VolumeGroupSnapshotClass`
+previously created. The labels inside `matchLabels` must be present on the
+PVCs that are already created by the RBD CSI driver.
+
+```console
+kubectl create -f deploy/examples/csi/rbd/groupsnapshot.yaml
+```
+
+### Verify RBD GroupSnapshot Creation
+
+```console
+$ kubectl get volumegroupsnapshotclass
+NAME                              DRIVER                          DELETIONPOLICY   AGE
+csi-rbdplugin-groupsnapclass      rook-ceph.rbd.csi.ceph.com      Delete           21m
+```
+
+```console
+$ kubectl get volumegroupsnapshot
+NAME                       READYTOUSE   VOLUMEGROUPSNAPSHOTCLASS          VOLUMEGROUPSNAPSHOTCONTENT                              CREATIONTIME   AGE
+rbd-groupsnapshot          true         csi-rbdplugin-groupsnapclass      groupsnapcontent-d13f4d95-8822-4729-9586-4f222a3f788e   5m37s          5m39s
+```
+
+The snapshot will be ready to restore to a new PVC when `READYTOUSE` field of the
+`volumegroupsnapshot` is set to true.
+
+### Restore the RBD volume group snapshot to a new PVC
+
+Find the name of the snapshots created by the `VolumeGroupSnapshot` first by running:
+
+```console
+$ kubectl get volumegroupsnapshot/rbd-groupsnapshot -o=jsonpath='{range .status.pvcVolumeSnapshotRefList[*]}PVC: {.persistentVolumeClaimRef.name}, Snapshot: {.volumeSnapshotRef.name}{"\n"}{end}'
+PVC: rbd-pvc, Snapshot: snapshot-9d21b143904c10f49ddc92664a7e8fe93c23387d0a88549c14337484ebaf1011-2024-09-12-3.49.13
+```
+
+It will list the PVC's name followed by its snapshot name.
+
+In
+[pvc-restore](https://github.com/rook/rook/tree/master/deploy/examples/csi/rbd/pvc-restore.yaml),
+`dataSource` is one of the `Snapshot` that we just
+found. The `dataSource` kind must be the `VolumeSnapshot`.
+
+Create a new PVC from the snapshot
+
+```console
+kubectl create -f deploy/examples/csi/rbd/pvc-restore.yaml
+```
+
+### Verify RBD Restore PVC Creation
+
+```console
+$ kubectl get pvc
+rbd-pvc           Bound    pvc-9ae60bf9-4931-4f9a-9de1-7f45f31fe4da   1Gi        RWO            rook-cephfs    <unset>                 171m
+rbd-pvc-restore   Bound    pvc-b4b73cbb-5061-48c7-9ac8-e1202508cf97   1Gi        RWO            rook-cephfs    <unset>                 46s
+```
+
+### RBD volume group snapshot resource Cleanup
+
+To clean the resources created by this example, run the following:
+
+```console
+kubectl delete -f deploy/examples/csi/rbd/pvc-restore.yaml
+kubectl delete -f deploy/examples/csi/rbd/groupsnapshot.yaml
+kubectl delete -f deploy/examples/csi/rbd/groupsnapshotclass.yaml
+```
+
+## CephFS Volume Group Snapshots

 ### CephFS VolumeGroupSnapshotClass

 In [VolumeGroupSnapshotClass](https://github.com/rook/rook/tree/master/deploy/examples/csi/cephfs/groupsnapshotclass.yaml),
-the `csi.storage.k8s.io/group-snapshotter-secret-name` parameter should reference the
+the `csi.storage.k8s.io/group-snapshotter-secret-name` parameter references the
 name of the secret created for the cephfs-plugin.

 In the `VolumeGroupSnapshotClass`, update the value of the `clusterID` field to match the namespace
@@ -43,8 +128,8 @@ kubectl create -f deploy/examples/csi/cephfs/groupsnapshotclass.yaml
 ### CephFS VolumeGroupSnapshot

 In [VolumeGroupSnapshot](https://github.com/rook/rook/tree/master/deploy/examples/csi/cephfs/groupsnapshot.yaml),
-`volumeGroupSnapshotClassName` should be the name of the `VolumeGroupSnapshotClass`
-previously created. The labels inside `matchLabels` should be present on the
+`volumeGroupSnapshotClassName` is the name of the `VolumeGroupSnapshotClass`
+previously created. The labels inside `matchLabels` must be present on the
 PVCs that are already created by the CephFS CSI driver.

 ```console
@@ -81,8 +166,8 @@ It will list the PVC's name followed by its snapshot name.

 In
 [pvc-restore](https://github.com/rook/rook/tree/master/deploy/examples/csi/cephfs/pvc-restore.yaml),
-`dataSource` should be one of the `Snapshot` that we just
-found. The `dataSource` kind should be the `VolumeSnapshot`.
+`dataSource` is one of the `Snapshot` that we just
+found. The `dataSource` kind must be the `VolumeSnapshot`.

 Create a new PVC from the snapshot

@@ -98,7 +183,7 @@ cephfs-pvc           Bound    pvc-9ae60bf9-4931-4f9a-9de1-7f45f31fe4da   1Gi
 cephfs-pvc-restore   Bound    pvc-b4b73cbb-5061-48c7-9ac8-e1202508cf97   1Gi        RWO            rook-cephfs    <unset>                 46s
 ```

-## CephFS volume group snapshot resource Cleanup
+### CephFS volume group snapshot resource Cleanup

 To clean the resources created by this example, run the following:

@@ -3,6 +3,8 @@ apiVersion: v1
 kind: PersistentVolumeClaim
 metadata:
  name: cephfs-pvc
+  # Use this with the example `groupsnapshotclass.yaml`.
+  # Not needed if the volume group snapshots are not required.
  labels:
    group: snapshot-test
 spec:
@@ -0,0 +1,13 @@
+---
+apiVersion: groupsnapshot.storage.k8s.io/v1alpha1
+kind: VolumeGroupSnapshot
+metadata:
+  name: rbd-groupsnapshot
+spec:
+  source:
+    selector:
+      matchLabels:
+        # The PVCs require this label for them to be
+        # included in the VolumeGroupSnapshot
+        group: snapshot-test
+  volumeGroupSnapshotClassName: csi-rbdplugin-groupsnapclass
@@ -0,0 +1,15 @@
+---
+apiVersion: groupsnapshot.storage.k8s.io/v1alpha1
+kind: VolumeGroupSnapshotClass
+metadata:
+  name: csi-rbdplugin-groupsnapclass
+driver: rook-ceph.rbd.csi.ceph.com # csi-provisioner-name
+parameters:
+  # Specify a string that identifies your cluster. Ceph CSI supports any
+  # unique string. When Ceph CSI is deployed by Rook use the Rook namespace,
+  # for example "rook-ceph".
+  clusterID: rook-ceph # namespace: cluster
+  pool: replicapool
+  csi.storage.k8s.io/group-snapshotter-secret-name: rook-csi-rbd-provisioner
+  csi.storage.k8s.io/group-snapshotter-secret-namespace: rook-ceph
+deletionPolicy: Delete
@@ -3,6 +3,10 @@ apiVersion: v1
 kind: PersistentVolumeClaim
 metadata:
  name: rbd-pvc
+  # Use this with the example `groupsnapshotclass.yaml`.
+  # Not needed if the volume group snapshots are not required.
+  labels:
+    group: snapshot-test
 spec:
  accessModes:
    - ReadWriteOnce