From fdf477678d4edad20f8a6e3ae77a205e100e1f27 Mon Sep 17 00:00:00 2001 From: Zac Dover Date: Mon, 20 May 2024 21:55:16 +1000 Subject: [PATCH] doc/cephfs: edit "Cloning Snapshots" in fs-volumes.rst Edit the "Cloning Snapshots" section in doc/cephfs/fs-volumes.rst. This commit represents only a grammar pass. A future commit (and future PR) will separate this section into subsections by command. Signed-off-by: Zac Dover (cherry picked from commit 69941180e9b1ff5f7f0eddfba670028aae93e333) --- doc/cephfs/fs-volumes.rst | 120 ++++++++++++++++++++++++-------------- 1 file changed, 76 insertions(+), 44 deletions(-) diff --git a/doc/cephfs/fs-volumes.rst b/doc/cephfs/fs-volumes.rst index 903b6f20d52..3b017a23e91 100644 --- a/doc/cephfs/fs-volumes.rst +++ b/doc/cephfs/fs-volumes.rst @@ -575,14 +575,17 @@ fail (if the metadata key did not exist). Cloning Snapshots ----------------- -Subvolumes can be created by cloning subvolume snapshots. Cloning is an asynchronous operation that copies -data from a snapshot to a subvolume. Due to this bulk copying, cloning is inefficient for very large -data sets. +Subvolumes can be created by cloning subvolume snapshots. Cloning is an +asynchronous operation that copies data from a snapshot to a subvolume. Because +cloning is an operation that involves bulk copying, it is inefficient for +very large data sets. -.. note:: Removing a snapshot (source subvolume) would fail if there are pending or in progress clone operations. +.. note:: Removing a snapshot (source subvolume) fails when there are + pending or in-progress clone operations. -Protecting snapshots prior to cloning was a prerequisite in the Nautilus release, and the commands to protect/unprotect -snapshots were introduced for this purpose. This prerequisite, and hence the commands to protect/unprotect, is being +Protecting snapshots prior to cloning was a prerequisite in the Nautilus +release. Commands that made possible the protection and unprotection of +snapshots were introduced for this purpose. This prerequisite is being deprecated and may be removed from a future release. The commands being deprecated are: @@ -596,31 +599,38 @@ The commands being deprecated are: .. note:: Use the ``subvolume info`` command to fetch subvolume metadata regarding supported ``features`` to help decide if protect/unprotect of snapshots is required, based on the availability of the ``snapshot-autoprotect`` feature. -To initiate a clone operation use:: +Run a command of the following form to initiate a clone operation: + +.. prompt:: bash $ $ ceph fs subvolume snapshot clone .. note:: ``subvolume snapshot clone`` command depends upon the above mentioned config option ``snapshot_clone_no_wait`` -If a snapshot (source subvolume) is a part of non-default group, the group name needs to be specified:: +Run a command of the following form when a snapshot (source subvolume) is a +part of non-default group. Note that the group name needs to be specified: - $ ceph fs subvolume snapshot clone --group_name +.. prompt:: bash $ -If a snapshot (source subvolume) is a part of non-default group, the group name needs to be specified: + ceph fs subvolume snapshot clone --target_group_name -Cloned subvolumes can be a part of a different group than the source snapshot (by default, cloned subvolumes are created in default group). To clone to a particular group use:: +Cloned subvolumes can be a part of a different group than the source snapshot +(by default, cloned subvolumes are created in default group). Run a command of +the following form to clone to a particular group use: - $ ceph fs subvolume snapshot clone --target_group_name +.. prompt:: bash # -Similar to specifying a pool layout when creating a subvolume, pool layout can be specified when creating a cloned subvolume. To create a cloned subvolume with a specific pool layout use:: + ceph fs subvolume snapshot clone --pool_layout - $ ceph fs subvolume snapshot clone --pool_layout +Pool layout can be specified when creating a cloned subvolume in a way that is +similar to specifying a pool layout when creating a subvolume. Run a command of +the following form to create a cloned subvolume with a specific pool layout: -To check the status of a clone operation use:: +.. prompt:: bash # ceph fs subvolume snapshot clone --pool_layout -To check the status of a clone operation use: +Run a command of the following form to check the status of a clone operation: .. prompt:: bash # @@ -676,11 +686,14 @@ Here is an example of a ``failed`` clone:: } } -(NOTE: since ``subvol1`` is in the default group, the ``source`` object's ``clone status`` does not include the group name) +.. note:: Because ``subvol1`` is in the default group, the ``source`` object's + ``clone status`` does not include the group name) -.. note:: Cloned subvolumes are accessible only after the clone operation has successfully completed. +.. note:: Cloned subvolumes are accessible only after the clone operation has + successfully completed. -After a successful clone operation, ``clone status`` will look like the below:: +After a successful clone operation, ``clone status`` will look like the +following:: $ ceph fs clone status cephfs clone1 { @@ -691,35 +704,51 @@ After a successful clone operation, ``clone status`` will look like the below:: If a clone operation is unsuccessful, the ``state`` value will be ``failed``. -To retry a failed clone operation, the incomplete clone must be deleted and the clone operation must be issued again. -To delete a partial clone use:: +To retry a failed clone operation, the incomplete clone must be deleted and the +clone operation must be issued again. - $ ceph fs subvolume rm [--group_name ] --force +Run a command of the following form to delete a partial clone: -.. note:: Cloning synchronizes only directories, regular files and symbolic links. Inode timestamps (access and - modification times) are synchronized up to seconds granularity. +.. prompt:: bash $ -An ``in-progress`` or a ``pending`` clone operation may be canceled. To cancel a clone operation use the ``clone cancel`` command:: + ceph fs subvolume rm [--group_name ] --force - $ ceph fs clone cancel [--group_name ] +.. note:: Cloning synchronizes only directories, regular files and symbolic + links. inode timestamps (access and modification times) are synchronized up + to a second's granularity. -On successful cancellation, the cloned subvolume is moved to the ``canceled`` state:: +An ``in-progress`` or a ``pending`` clone operation may be canceled. To cancel +a clone operation use the ``clone cancel`` command: - $ ceph fs subvolume snapshot clone cephfs subvol1 snap1 clone1 - $ ceph fs clone cancel cephfs clone1 - $ ceph fs clone status cephfs clone1 - { - "status": { - "state": "canceled", - "source": { - "volume": "cephfs", - "subvolume": "subvol1", - "snapshot": "snap1" - } +.. prompt:: bash $ + + ceph fs clone cancel [--group_name ] + +On successful cancellation, the cloned subvolume is moved to the ``canceled`` +state: + +.. prompt:: bash # + + ceph fs subvolume snapshot clone cephfs subvol1 snap1 clone1 + ceph fs clone cancel cephfs clone1 + ceph fs clone status cephfs clone1 + +:: + + { + "status": { + "state": "canceled", + "source": { + "volume": "cephfs", + "subvolume": "subvol1", + "snapshot": "snap1" + } + } } } -.. note:: The canceled cloned may be deleted by supplying the ``--force`` option to the `fs subvolume rm` command. +.. note:: Delete the canceled cloned by supplying the ``--force`` option to the + ``fs subvolume rm`` command. Configurables ~~~~~~~~~~~~~ @@ -730,17 +759,20 @@ Configure the maximum number of concurrent clone operations. The default is 4: ceph config set mgr mgr/volumes/max_concurrent_clones -Configure the snapshot_clone_no_wait option : +Configure the ``snapshot_clone_no_wait`` option: -The ``snapshot_clone_no_wait`` config option is used to reject clone creation requests when cloner threads -(which can be configured using above option i.e. ``max_concurrent_clones``) are not available. -It is enabled by default i.e. the value set is True, whereas it can be configured by using below command. +The ``snapshot_clone_no_wait`` config option is used to reject clone-creation +requests when cloner threads (which can be configured using the above options, +for example, ``max_concurrent_clones``) are not available. It is enabled by +default. This means that the value is set to ``True``, but it can be configured +by using the following command: .. prompt:: bash # ceph config set mgr mgr/volumes/snapshot_clone_no_wait -The current value of ``snapshot_clone_no_wait`` can be fetched by using below command. +The current value of ``snapshot_clone_no_wait`` can be fetched by running the +following command. .. prompt:: bash # -- 2.39.5