diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/rbd/rbd-snapshot.rst | 326 |
1 files changed, 189 insertions, 137 deletions
diff --git a/doc/rbd/rbd-snapshot.rst b/doc/rbd/rbd-snapshot.rst index 96dec81c87c..120dd8ec125 100644 --- a/doc/rbd/rbd-snapshot.rst +++ b/doc/rbd/rbd-snapshot.rst @@ -5,26 +5,29 @@ .. index:: Ceph Block Device; snapshots A snapshot is a read-only logical copy of an image at a particular point in -time: a checkpoint. One of the advanced features of Ceph block devices is -that you can create snapshots of images to retain point-in-time state history. -Ceph also supports snapshot layering, which allows you to clone images (e.g., a -VM image) quickly and easily. Ceph block device snapshots are managed using the -``rbd`` command and multiple higher level interfaces, including `QEMU`_, -`libvirt`_, `OpenStack`_ and `CloudStack`_. +time: a checkpoint. One of the advanced features of Ceph block devices is that +you can create snapshots of images to retain point-in-time state history. Ceph +also supports snapshot layering, which allows you to clone images (for example, +VM images) quickly and easily. Ceph block device snapshots are managed using +the ``rbd`` command and several higher-level interfaces, including `QEMU`_, +`libvirt`_, `OpenStack`_, and `CloudStack`_. .. important:: To use RBD snapshots, you must have a running Ceph cluster. -.. note:: Because RBD does not know about any filesystem within an image - (volume), snapshots are only `crash-consistent` unless they are - coordinated within the mounting (attaching) operating system. - We therefore recommend that you pause or stop I/O before taking a snapshot. - If the volume contains a filesystem, it should be in an internally - consistent state before taking a snapshot. Snapshots taken without - write quiescing may need an `fsck` pass before subsequent - mounting. To quiesce `I/O` you can use `fsfreeze` command. See - `fsfreeze(8)` man page for more details. - For virtual machines, `qemu-guest-agent` can be used to automatically - freeze file systems when creating a snapshot. + +.. note:: Because RBD is unaware of any file system within an image (volume), + snapshots are merely `crash-consistent` unless they are coordinated within + the mounting (attaching) operating system. We therefore recommend that you + pause or stop I/O before taking a snapshot. + + If the volume contains a file system, the file system should be in an + internally consistent state before a snapshot is taken. Snapshots taken + without write quiescing could need an `fsck` pass before they are mounted + again. To quiesce I/O you can use `fsfreeze` command. See the `fsfreeze(8)` + man page for more details. + + For virtual machines, `qemu-guest-agent` can be used to automatically freeze + file systems when creating a snapshot. .. ditaa:: @@ -41,19 +44,22 @@ Cephx Notes When `cephx`_ authentication is enabled (it is by default), you must specify a user name or ID and a path to the keyring containing the corresponding key. See -:ref:`User Management <user-management>` for details. You may also set the -``CEPH_ARGS`` environment variable to avoid re-entry of these parameters. :: +:ref:`User Management <user-management>` for details. + +.. prompt:: bash $ + + rbd --id {user-ID} --keyring /path/to/secret [commands] + rbd --name {username} --keyring /path/to/secret [commands] - rbd --id {user-ID} --keyring=/path/to/secret [commands] - rbd --name {username} --keyring=/path/to/secret [commands] +For example: -For example:: +.. prompt:: bash $ - rbd --id admin --keyring=/etc/ceph/ceph.keyring [commands] - rbd --name client.admin --keyring=/etc/ceph/ceph.keyring [commands] + rbd --id admin --keyring /etc/ceph/ceph.keyring [commands] + rbd --name client.admin --keyring /etc/ceph/ceph.keyring [commands] -.. tip:: Add the user and secret to the ``CEPH_ARGS`` environment - variable so that you don't need to enter them each time. +.. tip:: Add the user and secret to the ``CEPH_ARGS`` environment variable to + avoid re-entry of these parameters. Snapshot Basics @@ -65,76 +71,97 @@ snapshots using the ``rbd`` command. Create Snapshot --------------- -To create a snapshot with ``rbd``, specify the ``snap create`` option, the pool -name and the image name. :: +To create a snapshot, use the ``rbd snap create`` command and specify the pool +name, the image name, and the snap name: - rbd snap create {pool-name}/{image-name}@{snap-name} +.. prompt:: bash $ -For example:: + rbd snap create {pool-name}/{image-name}@{snap-name} - rbd snap create rbd/foo@snapname +For example: + +.. prompt:: bash $ + + rbd snap create rbd/foo@snapname List Snapshots -------------- -To list snapshots of an image, specify the pool name and the image name. :: +To list the snapshots of an image, use the ``rbd snap ls`` command and specify +the pool name and the image name: - rbd snap ls {pool-name}/{image-name} +.. prompt:: bash $ -For example:: + rbd snap ls {pool-name}/{image-name} - rbd snap ls rbd/foo +For example: +.. prompt:: bash $ -Rollback Snapshot ------------------ + rbd snap ls rbd/foo -To rollback to a snapshot with ``rbd``, specify the ``snap rollback`` option, the -pool name, the image name and the snap name. :: - rbd snap rollback {pool-name}/{image-name}@{snap-name} +Roll back Snapshot +------------------ -For example:: +To roll back to a snapshot, use the ``rbd snap rollback`` command and specify +the pool name, the image name, and the snap name: - rbd snap rollback rbd/foo@snapname +.. prompt:: bash $ + rbd snap rollback {pool-name}/{image-name}@{snap-name} -.. note:: Rolling back an image to a snapshot means overwriting - the current version of the image with data from a snapshot. The - time it takes to execute a rollback increases with the size of the - image. It is **faster to clone** from a snapshot **than to rollback** - an image to a snapshot, and is the preferred method of returning - to a pre-existing state. +For example: + +.. prompt:: bash $ + + rbd snap rollback rbd/foo@snapname + + +.. note:: Rolling back an image to a snapshot means overwriting the current + version of the image with data from a snapshot. The time it takes to execute + a rollback increases with the size of the image. It is **faster to clone** + from a snapshot **than to roll back** an image to a snapshot. Cloning from a + snapshot is the preferred method of returning to a pre-existing state. Delete a Snapshot ----------------- -To delete a snapshot with ``rbd``, specify the ``snap rm`` subcommand, the pool -name, the image name and the snap name. :: +To delete a snapshot, use the ``rbd snap rm`` command and specify the pool +name, the image name, and the snap name: - rbd snap rm {pool-name}/{image-name}@{snap-name} +.. prompt:: bash $ + + rbd snap rm {pool-name}/{image-name}@{snap-name} -For example:: +For example: + +.. prompt:: bash $ - rbd snap rm rbd/foo@snapname + rbd snap rm rbd/foo@snapname -.. note:: Ceph OSDs delete data asynchronously, so deleting a snapshot - doesn't immediately free up the underlying OSDs' capacity. +.. note:: Ceph OSDs delete data asynchronously, so deleting a snapshot does + not immediately free up the capacity of the underlying OSDs. This process is + known as "snaptrim", and is referred to as such in ``ceph status`` output. Purge Snapshots --------------- -To delete all snapshots for an image with ``rbd``, specify the ``snap purge`` -subcommand and the image name. :: +To delete all snapshots, use the ``rbd snap purge`` command and specify the +pool name and the image name: + +.. prompt:: bash $ + + rbd snap purge {pool-name}/{image-name} - rbd snap purge {pool-name}/{image-name} +For example: -For example:: +.. prompt:: bash $ - rbd snap purge rbd/foo + rbd snap purge rbd/foo .. index:: Ceph Block Device; snapshot layering @@ -145,10 +172,9 @@ Layering Ceph supports the ability to create many copy-on-write (COW) clones of a block device snapshot. Snapshot layering enables Ceph block device clients to create images very quickly. For example, you might create a block device image with a -Linux VM written to it; then, snapshot the image, protect the snapshot, and -create as many copy-on-write clones as you like. A snapshot is read-only, -so cloning a snapshot simplifies semantics--making it possible to create -clones rapidly. +Linux VM written to it, snapshot the image, protect the snapshot, and create as +many copy-on-write clones as you like. A snapshot is read-only, so cloning a +snapshot simplifies semantics, making it possible to create clones rapidly. .. ditaa:: @@ -163,29 +189,30 @@ clones rapidly. Parent Child -.. note:: The terms "parent" and "child" refer to a Ceph block device snapshot (parent), - and the corresponding image cloned from the snapshot (child). These terms are - important for the command line usage below. +.. note:: The terms "parent" and "child" refer to a Ceph block device snapshot + (parent) and the corresponding image cloned from the snapshot (child). + These terms are important for the command line usage below. Each cloned image (child) stores a reference to its parent image, which enables -the cloned image to open the parent snapshot and read it. +the cloned image to open the parent snapshot and read it. -A COW clone of a snapshot behaves exactly like any other Ceph block device -image. You can read to, write from, clone, and resize cloned images. There are -no special restrictions with cloned images. However, the copy-on-write clone of -a snapshot depends on the snapshot, so you **MUST** protect the snapshot before -you clone it. The following diagram depicts the process. +A copy-on-write clone of a snapshot behaves exactly like any other Ceph +block device image. You can read to, write from, clone, and resize cloned +images. There are no special restrictions with cloned images. However, the +copy-on-write clone of a snapshot depends on the snapshot, so you must +protect the snapshot before you clone it. The diagram below depicts this +process. -.. note:: Ceph only supports cloning of RBD format 2 images (i.e., created with - ``rbd create --image-format 2``). The kernel client supports cloned images - beginning with the 3.10 release. +.. note:: Ceph supports the cloning of only "RBD format 2" images (that is, + images created without specifying ``--image-format 1``). The Linux kernel + client supports cloned images beginning with the 3.10 release. Getting Started with Layering ----------------------------- -Ceph block device layering is a simple process. You must have an image. You must -create a snapshot of the image. You must protect the snapshot. Once you have -performed these steps, you can begin cloning the snapshot. +Ceph block device layering is a simple process. You must have an image. You +must create a snapshot of the image. You must protect the snapshot. After you +have performed these steps, you can begin cloning the snapshot. .. ditaa:: @@ -206,107 +233,132 @@ performed these steps, you can begin cloning the snapshot. The cloned image has a reference to the parent snapshot, and includes the pool -ID, image ID and snapshot ID. The inclusion of the pool ID means that you may -clone snapshots from one pool to images in another pool. - - -#. **Image Template:** A common use case for block device layering is to create a - master image and a snapshot that serves as a template for clones. For example, - a user may create an image for a Linux distribution (e.g., Ubuntu 12.04), and - create a snapshot for it. Periodically, the user may update the image and create - a new snapshot (e.g., ``sudo apt-get update``, ``sudo apt-get upgrade``, - ``sudo apt-get dist-upgrade`` followed by ``rbd snap create``). As the image - matures, the user can clone any one of the snapshots. - -#. **Extended Template:** A more advanced use case includes extending a template - image that provides more information than a base image. For example, a user may - clone an image (e.g., a VM template) and install other software (e.g., a database, - a content management system, an analytics system, etc.) and then snapshot the - extended image, which itself may be updated just like the base image. - -#. **Template Pool:** One way to use block device layering is to create a - pool that contains master images that act as templates, and snapshots of those - templates. You may then extend read-only privileges to users so that they - may clone the snapshots without the ability to write or execute within the pool. - -#. **Image Migration/Recovery:** One way to use block device layering is to migrate - or recover data from one pool into another pool. +ID, the image ID, and the snapshot ID. The inclusion of the pool ID means that +you may clone snapshots from one pool to images in another pool. + +#. **Image Template:** A common use case for block device layering is to create + a base image and a snapshot that serves as a template for clones. For + example: a user may create an image for a Linux distribution (for example, + Ubuntu 22.04) and create a snapshot of it. The user may occasionally update + the image and create a new snapshot (by using such commands as ``sudo + apt-get update``, ``sudo apt-get upgrade``, or ``sudo apt-get dist-upgrade`` + followed by ``rbd snap create``). As the image matures, the user can clone + any one of the snapshots. + +#. **Extended Template:** A more advanced use case includes extending a + template image to provide more information than a base image. For + example, a user may clone an image (for example, a VM template) and install + other software (for example, a database, a content management system, an + analytics system) and then snapshot the extended image, which may itself be + updated just like the base image. + +#. **Template Pool:** One way to use block device layering is to create a pool + that contains (1) base images that act as templates and (2) snapshots of + those templates. You may then extend read-only privileges to users so that + they may clone the snapshots even though they do not have permissions that + allow them to write or execute within the pool. + +#. **Image Migration/Recovery:** One way to use block device layering is to + migrate or recover data from one pool into another pool. Protecting a Snapshot --------------------- -Clones access the parent snapshots. All clones would break if a user inadvertently -deleted the parent snapshot. To prevent data loss, you **MUST** protect the -snapshot before you can clone it. :: +Clones access the parent snapshots. All clones would break if a user +inadvertently deleted the parent snapshot. To prevent data loss, you must +protect the snapshot before you can clone it: + +.. prompt:: bash $ - rbd snap protect {pool-name}/{image-name}@{snapshot-name} + rbd snap protect {pool-name}/{image-name}@{snapshot-name} -For example:: +For example: - rbd snap protect rbd/my-image@my-snapshot +.. prompt:: bash $ + + rbd snap protect rbd/foo@snapname .. note:: You cannot delete a protected snapshot. Cloning a Snapshot ------------------ -To clone a snapshot, specify you need to specify the parent pool, image and -snapshot; and, the child pool and image name. You must protect the snapshot -before you can clone it. :: +To clone a snapshot, specify the parent pool, the parent image, and the parent +snapshot; and also the child pool together with the image name. You must +protect the snapshot before you can clone it: + +.. prompt:: bash $ - rbd clone {pool-name}/{parent-image}@{snap-name} {pool-name}/{child-image-name} + rbd clone {pool-name}/{parent-image-name}@{snap-name} {pool-name}/{child-image-name} -For example:: +For example: - rbd clone rbd/my-image@my-snapshot rbd/new-image +.. prompt:: bash $ + + rbd clone rbd/foo@snapname rbd/bar -.. note:: You may clone a snapshot from one pool to an image in another pool. For example, - you may maintain read-only images and snapshots as templates in one pool, and writeable - clones in another pool. + +.. note:: You may clone a snapshot from one pool to an image in another pool. + For example, you may maintain read-only images and snapshots as templates in + one pool, and writeable clones in another pool. Unprotecting a Snapshot ----------------------- -Before you can delete a snapshot, you must unprotect it first. Additionally, +Before you can delete a snapshot, you must first unprotect it. Additionally, you may *NOT* delete snapshots that have references from clones. You must -flatten each clone of a snapshot, before you can delete the snapshot. :: +flatten or delete each clone of a snapshot before you can unprotect the +snapshot: + +.. prompt:: bash $ + + rbd snap unprotect {pool-name}/{image-name}@{snapshot-name} - rbd snap unprotect {pool-name}/{image-name}@{snapshot-name} +For example: -For example:: +.. prompt:: bash $ - rbd snap unprotect rbd/my-image@my-snapshot + rbd snap unprotect rbd/foo@snapname Listing Children of a Snapshot ------------------------------ -To list the children of a snapshot, execute the following:: +To list the children of a snapshot, use the ``rbd children`` command and +specify the pool name, the image name, and the snap name: - rbd children {pool-name}/{image-name}@{snapshot-name} +.. prompt:: bash $ -For example:: + rbd children {pool-name}/{image-name}@{snapshot-name} - rbd children rbd/my-image@my-snapshot +For example: + +.. prompt:: bash $ + + rbd children rbd/foo@snapname Flattening a Cloned Image ------------------------- Cloned images retain a reference to the parent snapshot. When you remove the -reference from the child clone to the parent snapshot, you effectively "flatten" -the image by copying the information from the snapshot to the clone. The time -it takes to flatten a clone increases with the size of the snapshot. To delete -a snapshot, you must flatten the child images first. :: +reference to the parent snapshot from the clone, you effectively "flatten" the +clone by copying the data stored in the snapshot to the clone. The time it +takes to flatten a clone increases with the size of the snapshot. To delete a +snapshot, you must first flatten the child images (or delete them): + +.. prompt:: bash $ + + rbd flatten {pool-name}/{image-name} - rbd flatten {pool-name}/{image-name} +For example: -For example:: +.. prompt:: bash $ - rbd flatten rbd/new-image + rbd flatten rbd/bar -.. note:: Since a flattened image contains all the information from the snapshot, - a flattened image will take up more storage space than a layered clone. +.. note:: Since a flattened image contains all the data stored in the snapshot, + a flattened image takes up more storage space than a layered clone does. .. _cephx: ../../rados/configuration/auth-config-ref/ |