From 524b6071d2dd17fcdf7ee587ba1b43feaa4dfa1e Mon Sep 17 00:00:00 2001 From: Niraj Yadav Date: Mon, 14 Oct 2024 16:29:48 +0530 Subject: [PATCH] docs: add documentation for rbd volumegroupsnapshot This PR adds the sample YAMLs and documentation for the RBD VolumeGroupSnapshot. Signed-off-by: Niraj Yadav --- .../ceph-csi-volume-group-snapshot.md | 99 +++++++++++++++++-- deploy/examples/csi/cephfs/pvc.yaml | 2 + deploy/examples/csi/rbd/groupsnapshot.yaml | 13 +++ .../examples/csi/rbd/groupsnapshotclass.yaml | 15 +++ deploy/examples/csi/rbd/pvc.yaml | 4 + 5 files changed, 126 insertions(+), 7 deletions(-) create mode 100644 deploy/examples/csi/rbd/groupsnapshot.yaml create mode 100644 deploy/examples/csi/rbd/groupsnapshotclass.yaml diff --git a/Documentation/Storage-Configuration/Ceph-CSI/ceph-csi-volume-group-snapshot.md b/Documentation/Storage-Configuration/Ceph-CSI/ceph-csi-volume-group-snapshot.md index 33d58b807..f569ac151 100644 --- a/Documentation/Storage-Configuration/Ceph-CSI/ceph-csi-volume-group-snapshot.md +++ b/Documentation/Storage-Configuration/Ceph-CSI/ceph-csi-volume-group-snapshot.md @@ -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 171m +rbd-pvc-restore Bound pvc-b4b73cbb-5061-48c7-9ac8-e1202508cf97 1Gi RWO rook-cephfs 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 46s ``` -## CephFS volume group snapshot resource Cleanup +### CephFS volume group snapshot resource Cleanup To clean the resources created by this example, run the following: diff --git a/deploy/examples/csi/cephfs/pvc.yaml b/deploy/examples/csi/cephfs/pvc.yaml index cf3057de3..656d46859 100644 --- a/deploy/examples/csi/cephfs/pvc.yaml +++ b/deploy/examples/csi/cephfs/pvc.yaml @@ -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: diff --git a/deploy/examples/csi/rbd/groupsnapshot.yaml b/deploy/examples/csi/rbd/groupsnapshot.yaml new file mode 100644 index 000000000..b0f329125 --- /dev/null +++ b/deploy/examples/csi/rbd/groupsnapshot.yaml @@ -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 diff --git a/deploy/examples/csi/rbd/groupsnapshotclass.yaml b/deploy/examples/csi/rbd/groupsnapshotclass.yaml new file mode 100644 index 000000000..05a64852f --- /dev/null +++ b/deploy/examples/csi/rbd/groupsnapshotclass.yaml @@ -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 diff --git a/deploy/examples/csi/rbd/pvc.yaml b/deploy/examples/csi/rbd/pvc.yaml index 516a5aa87..edb8b1ba8 100644 --- a/deploy/examples/csi/rbd/pvc.yaml +++ b/deploy/examples/csi/rbd/pvc.yaml @@ -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