From f59806caff9b10f139c6953def19d94b428a3cc1 Mon Sep 17 00:00:00 2001 From: Robert Vasek Date: Wed, 6 Apr 2022 17:48:27 +0200 Subject: [PATCH] doc: added docs for snapshot-backed CephFS volumes Signed-off-by: Robert Vasek --- docs/cephfs-snapshot-backed-volumes.md | 61 ++++++++++++++++++++++++++ docs/deploy-cephfs.md | 1 + examples/cephfs/storageclass.yaml | 5 +++ 3 files changed, 67 insertions(+) create mode 100644 docs/cephfs-snapshot-backed-volumes.md diff --git a/docs/cephfs-snapshot-backed-volumes.md b/docs/cephfs-snapshot-backed-volumes.md new file mode 100644 index 000000000..618b2bc8f --- /dev/null +++ b/docs/cephfs-snapshot-backed-volumes.md @@ -0,0 +1,61 @@ +# Provisioning and mounting CephFS snapshot-backed volumes + +Snapshot-backed volumes allow CephFS subvolume snapshots to be exposed as +regular read-only PVCs. No data cloning is performed and provisioning such +volumes is done in constant time. + +For more details please refer to [Snapshots as shallow read-only volumes](./design/proposals/cephfs-snapshot-shallow-ro-vol.md) +design document. + +## Prerequisites + +Prerequisites for this feature are the same as for creating PVCs with snapshot +volume source. See [Create snapshot and Clone Volume](./snap-clone.md) for more +information. + +## Usage + +### Provisioning a snapshot-backed volume from a volume snapshot + +For provisioning new snapshot-backed volumes, following configuration must be +set for storage class(es) and their PVCs respectively: + +* StorageClass: + * Specify `backingSnapshot: "true"` parameter. +* PersistentVolumeClaim: + * Set `storageClassName` to point to your storage class with backing + snapshots enabled. + * Define `spec.dataSource` for your desired source volume snapshot. + * Set `spec.accessModes` to `ReadOnlyMany`. This is the only access mode that + is supported by this feature. + +### Mounting snapshots from pre-provisioned volumes + +Steps for defining a PersistentVolume and PersistentVolumeClaim for +pre-provisioned CephFS subvolumes are identical to those described in +[Static PVC with ceph-csi](./static-pvc.md), except one additional parameter +must be specified: `backingSnapshotID`. CephFS-CSI driver will retrieve the +snapshot identified by the given ID from within the specified subvolume, and +expose it to workloads in read-only mode. Volume access mode must be set to +`ReadOnlyMany`. + +Note that the snapshot retrieval is done by traversing `/.snap` and +searching for a directory that contains `backingSnapshotID` value in its name. +The specified snapshot ID does not necessarily need to be the complete directory +name inside `/.snap`, however it must be complete enough to uniquely +identify that directory. + +Example: + +``` +$ ls .snap +_f279df14-6729-4342-b82f-166f45204233_1099511628283 +_a364870e-6729-4342-b82f-166f45204233_1099635085072 +``` + +`f279df14-6729-4342-b82f-166f45204233` would be considered a valid value for +`backingSnapshotID` volume parameter, whereas `6729-4342-b82f-166f45204233` +would not, as it would be ambiguous. + +If the given snapshot ID is ambiguous, or no such snapshot is found, mounting +the PVC will fail with INVALID_ARGUMENT error code. diff --git a/docs/deploy-cephfs.md b/docs/deploy-cephfs.md index 833d604ca..181e8d1f3 100644 --- a/docs/deploy-cephfs.md +++ b/docs/deploy-cephfs.md @@ -81,6 +81,7 @@ you're running it inside a k8s cluster and find the config itself). | `pool` | no | Ceph pool into which volume data shall be stored | | `volumeNamePrefix` | no | Prefix to use for naming subvolumes (defaults to `csi-vol-`). | | `snapshotNamePrefix` | no | Prefix to use for naming snapshots (defaults to `csi-snap-`) | +| `backingSnapshot` | no | Boolean value. The PVC shall be backed by the CephFS snapshot specified in its data source. `pool` parameter must not be specified. (defaults to `false`) | | `kernelMountOptions` | no | Comma separated string of mount options accepted by cephfs kernel mounter, by default no options are passed. Check man mount.ceph for options. | | `fuseMountOptions` | no | Comma separated string of mount options accepted by ceph-fuse mounter, by default no options are passed. | | `csi.storage.k8s.io/provisioner-secret-name`, `csi.storage.k8s.io/node-stage-secret-name` | for Kubernetes | Name of the Kubernetes Secret object containing Ceph client credentials. Both parameters should have the same value | diff --git a/examples/cephfs/storageclass.yaml b/examples/cephfs/storageclass.yaml index 42fa35536..b23fa0213 100644 --- a/examples/cephfs/storageclass.yaml +++ b/examples/cephfs/storageclass.yaml @@ -47,6 +47,11 @@ parameters: # If omitted, defaults to "csi-vol-". # volumeNamePrefix: "foo-bar-" + # (optional) Boolean value. The PVC shall be backed by the CephFS snapshot + # specified in its data source. `pool` parameter must not be specified. + # (defaults to `false`) + # backingSnapshot: "true" + reclaimPolicy: Delete allowVolumeExpansion: true mountOptions: