diff options
Diffstat (limited to 'src/ceph/doc/rbd/rbd-snapshot.rst')
| -rw-r--r-- | src/ceph/doc/rbd/rbd-snapshot.rst | 308 |
1 files changed, 0 insertions, 308 deletions
diff --git a/src/ceph/doc/rbd/rbd-snapshot.rst b/src/ceph/doc/rbd/rbd-snapshot.rst deleted file mode 100644 index 2e5af9f..0000000 --- a/src/ceph/doc/rbd/rbd-snapshot.rst +++ /dev/null @@ -1,308 +0,0 @@ -=========== - Snapshots -=========== - -.. index:: Ceph Block Device; snapshots - -A snapshot is a read-only copy of the state of an image at a particular point in -time. One of the advanced features of Ceph block devices is that you can create -snapshots of the images to retain a history of an image's state. Ceph also -supports snapshot layering, which allows you to clone images (e.g., a VM image) -quickly and easily. Ceph supports block device snapshots using the ``rbd`` -command and many higher level interfaces, including `QEMU`_, `libvirt`_, -`OpenStack`_ and `CloudStack`_. - -.. important:: To use use RBD snapshots, you must have a running Ceph cluster. - -.. note:: If a snapshot is taken while `I/O` is still in progress in a image, the - snapshot might not get the exact or latest data of the image and the snapshot - may have to be cloned to a new image to be mountable. So, we recommend to stop - `I/O` before taking a snapshot of an image. If the image contains a filesystem, - the filesystem must be in a consistent state before taking a snapshot. To stop - `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 - filesystems when creating a snapshot. - -.. ditaa:: +------------+ +-------------+ - | {s} | | {s} c999 | - | Active |<-------*| Snapshot | - | Image | | of Image | - | (stop i/o) | | (read only) | - +------------+ +-------------+ - - -Cephx Notes -=========== - -When `cephx`_ is enabled (it is by default), you must specify a user name or ID -and a path to the keyring containing the corresponding key for the user. See -`User Management`_ for details. You may also add the ``CEPH_ARGS`` environment -variable to avoid re-entry of the following parameters. :: - - rbd --id {user-ID} --keyring=/path/to/secret [commands] - rbd --name {username} --keyring=/path/to/secret [commands] - -For example:: - - 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. - - -Snapshot Basics -=============== - -The following procedures demonstrate how to create, list, and remove -snapshots using the ``rbd`` command on the command line. - -Create Snapshot ---------------- - -To create a snapshot with ``rbd``, specify the ``snap create`` option, the pool -name and the image name. :: - - rbd snap create {pool-name}/{image-name}@{snap-name} - -For example:: - - rbd snap create rbd/foo@snapname - - -List Snapshots --------------- - -To list snapshots of an image, specify the pool name and the image name. :: - - rbd snap ls {pool-name}/{image-name} - -For example:: - - rbd snap ls rbd/foo - - -Rollback Snapshot ------------------ - -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} - -For example:: - - 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 rollback** - an image to a snapshot, and it is the preferred method of returning - to a pre-existing state. - - -Delete a Snapshot ------------------ - -To delete a snapshot with ``rbd``, specify the ``snap rm`` option, the pool -name, the image name and the snap name. :: - - rbd snap rm {pool-name}/{image-name}@{snap-name} - -For example:: - - rbd snap rm rbd/foo@snapname - - -.. note:: Ceph OSDs delete data asynchronously, so deleting a snapshot - doesn't free up the disk space immediately. - -Purge Snapshots ---------------- - -To delete all snapshots for an image with ``rbd``, specify the ``snap purge`` -option and the image name. :: - - rbd snap purge {pool-name}/{image-name} - -For example:: - - rbd snap purge rbd/foo - - -.. index:: Ceph Block Device; snapshot layering - -Layering -======== - -Ceph supports the ability to create many copy-on-write (COW) clones of a block -device shapshot. 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. - - -.. ditaa:: +-------------+ +-------------+ - | {s} c999 | | {s} | - | Snapshot | Child refers | COW Clone | - | of Image |<------------*| of Snapshot | - | | to Parent | | - | (read only) | | (writable) | - +-------------+ +-------------+ - - Parent Child - -.. note:: The terms "parent" and "child" mean 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. - -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 refers to the snapshot, so you **MUST** protect the snapshot before -you clone it. The following diagram depicts the process. - -.. note:: Ceph only supports cloning for format 2 images (i.e., created with - ``rbd create --image-format 2``). The kernel client supports cloned images - since kernel 3.10. - -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. - -.. ditaa:: +----------------------------+ +-----------------------------+ - | | | | - | Create Block Device Image |------->| Create a Snapshot | - | | | | - +----------------------------+ +-----------------------------+ - | - +--------------------------------------+ - | - v - +----------------------------+ +-----------------------------+ - | | | | - | Protect the Snapshot |------->| Clone 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 - 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. - -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. :: - - rbd snap protect {pool-name}/{image-name}@{snapshot-name} - -For example:: - - rbd snap protect rbd/my-image@my-snapshot - -.. 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. :: - - rbd clone {pool-name}/{parent-image}@{snap-name} {pool-name}/{child-image-name} - -For example:: - - rbd clone rbd/my-image@my-snapshot rbd/new-image - -.. 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, -you may *NOT* delete snapshots that have references from clones. You must -flatten each clone of a snapshot, before you can delete the snapshot. :: - - rbd snap unprotect {pool-name}/{image-name}@{snapshot-name} - -For example:: - - rbd snap unprotect rbd/my-image@my-snapshot - - -Listing Children of a Snapshot ------------------------------- - -To list the children of a snapshot, execute the following:: - - rbd children {pool-name}/{image-name}@{snapshot-name} - -For example:: - - rbd children rbd/my-image@my-snapshot - - -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. :: - - rbd flatten {pool-name}/{image-name} - -For example:: - - rbd flatten rbd/my-image - -.. 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. - - -.. _cephx: ../../rados/configuration/auth-config-ref/ -.. _User Management: ../../operations/user-management -.. _QEMU: ../qemu-rbd/ -.. _OpenStack: ../rbd-openstack/ -.. _CloudStack: ../rbd-cloudstack/ -.. _libvirt: ../libvirt/ |