From: John Wilkins Date: Thu, 1 Nov 2012 17:41:38 +0000 (-0700) Subject: doc: Added layering to the snapshot section. X-Git-Tag: v0.55~130^2~30 X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=968b315a096ee24745a0e331b20271ce6c2b26a3;p=ceph.git doc: Added layering to the snapshot section. Signed-off-by: John Wilkins --- diff --git a/doc/rbd/rbd-snapshot.rst b/doc/rbd/rbd-snapshot.rst index 63fe4f2f1ed..b0800fe08ef 100644 --- a/doc/rbd/rbd-snapshot.rst +++ b/doc/rbd/rbd-snapshot.rst @@ -1,70 +1,320 @@ -================== - RBD Snapshotting -================== +=========== + Snapshots +=========== -One of the advanced features of RADOS block devices is that you can create -snapshots of the images to retain a history of an image's state. Ceph supports -RBD snapshots from the ``rbd`` command, from a kernel object, from a -KVM, and from cloud solutions. Once you create snapshots of an image, you -can rollback to a snapshot, list snapshots, remove snapshots and purge -the 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. -.. warning:: Stop i/o before snapshotting an image. +.. note:: **STOP I/O BEFORE** snapshotting an image. If the image contains a filesystem, the filesystem must be in a - consistent state before snapshotting. + consistent state **BEFORE** snapshotting. + +.. ditaa:: +------------+ +-------------+ + | {s} | | {s} c999 | + | Active |<-------*| Snapshot | + | Image | | of Image | + | (stop i/o) | | (read only) | + +------------+ +-------------+ -Create Snapshot + +Cephx Notes +=========== + +When `cephx`_ is enabled, you must specify a user and a secret file +on the command line, or use the ``CEPH_ARGS`` environment variable +to avoid re-entry of the following parameters. :: + + rbd --user {user-name} --keyring=/path/to/secret [commands] + +For example:: + + rbd --user 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 =============== -To create a snapshot with ``rbd``, specify the ``snap create`` option, -the pool name, the image name and the username. If you use ``cephx`` for -authentication, you must also specify a key or a secret file. :: +The following procedures demonstrate how to create, list, and remove +snapshots using the ``rbd`` command on the command line. - rbd --name {user-name} --keyfile=/path/to/secret --pool {pool-name} snap create --snap {snap-name} {image-name} +Create Snapshot +--------------- + +To create a snapshot with ``rbd``, specify the ``snap create`` option, the pool +name and the image name. :: + + rbd --pool {pool-name} snap create --snap {snap-name} {image-name} + rbd snap create {pool-name}/{image-name}@{snap-name} For example:: - rbd --name client.admin --pool rbd snap create --snap foo.snapname foo + rbd --pool rbd snap create --snap snapname foo + rbd snap create rbd/foo@snapname + List Snapshots -============== +-------------- -To list snapshots of an image, specify the pool name, the image name, and -the username. If you use ``cephx`` for authentication, you must also -specify a key or a secret file. :: +To list snapshots of an image, specify the pool name and the image name. :: - rbd --name {user-name} --keyfile=/path/to/secret --pool {pool-name} snap ls {image-name} + rbd --pool {pool-name} snap ls {image-name} + rbd snap ls {pool-name}/{image-name} For example:: - rbd --name client.admin --pool rbd snap ls foo + rbd --pool rbd snap ls foo + rbd snap ls rbd/foo Rollback Snapshot -================= +----------------- -To rollback a snapshot with ``rbd``, specify the ``snap rollback`` option, -the pool name, the image name and the username. If you use ``cephx`` for -authentication, you must also specify a key or a secret file. :: +To rollback to a snapshot with ``rbd``, specify the ``snap rollback`` option, the +pool name, the image name and the snap name. :: - rbd --name {user-name} --keyfile=/path/to/secret --pool {pool-name} snap rollback --snap {snap-name} {image-name} + rbd --pool {pool-name} snap rollback --snap {snap-name} {image-name} + rbd snap rollback {pool-name}/{image-name}@{snap-name} For example:: - rbd --name client.admin --pool rbd snap rollback --snap foo.snapname foo + rbd --pool rbd snap rollback --snap snapname foo + rbd snap rollback rbd/foo@snapname + + + +For the rollback section, you could mention that rollback means +overwriting the current version with data from a snapshot, and takes +longer with larger images. So cloning is preferable for fast recovery. + +.. 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 username. If you use ``cephx`` for -authentication, you must also specify a key or a secret file. :: +To delete a snapshot with ``rbd``, specify the ``snap rm`` option, the pool +name, the image name and the username. :: - rbd --name {user-name} --keyfile=/path/to/secret --pool {pool-name} snap rm --snap {snap-name} {image-name} + rbd --pool {pool-name} snap rm --snap {snap-name} {image-name} + rbd snap rm {pool-name}/{image-name}@{snap-name} For example:: - rbd --name client.admin --pool rbd snap rm --snap foo.snapname foo + rbd --pool rbd snap rm --snap snapname foo + 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 --pool {pool-name} snap purge {image-name} + rbd snap purge {pool-name}/{image-name} + +For example:: + + rbd --pool rbd snap purge foo + rbd snap purge rbd/foo + + +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) | | (writeable) | + +-------------+ +-------------+ + + 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 --format 2``), and is not yet supported by the kernel ``rbd`` module. + So you MUST use QEMU/KVM or ``librbd`` directly to access clones in the current + 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. + +.. 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 priveleges 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 inadvertantly +deleted the parent snapshot. To prevent data loss, you **MUST** protect the +snapshot before you can clone it. :: + + rbd --pool {pool-name} snap protect --image {image-name} --snap {snapshot-name} + rbd snap protect {pool-name}/{image-name}@{snapshot-name} + +For example:: + + rbd --pool rbd snap protect --image my-image --snap my-snapshot + 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 --pool {pool-name} --image {parent-image} --snap {snap-name} --dest-pool {pool-name} --dest {child-image} + 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 --pool {pool-name} snap unprotect --image {image-name} --snap {snapshot-name} + rbd snap unprotect {pool-name}/{image-name}@{snapshot-name} + +For example:: + + rbd --pool rbd snap unprotect --image my-image --snap my-snapshot + rbd snap unprotect rbd/my-image@my-snapshot + + +Listing Children of a Snapshot +------------------------------ + +To list the children of a snapshot, execute the following:: + + rbd --pool {pool-name} snap children --image {image-name} --snap {snap-name} + rbd snap children {pool-name}/{image-name}@{snapshot-name} + +For example:: + + rbd --pool rbd snap children --image my-image --snap my-snapshot + rbd snap 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 --pool {pool-name} flatten --image {image-name} + rbd flatten {pool-name}/{image-name} + +For example:: + + rbd --pool rbd flatten --image my-image + 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: ../../cluster-ops/authentication/ +.. _QEMU: ../qemu-rbd/ +.. _OpenStack: ../rbd-openstack/ +.. _CloudStack: ../rbd-cloudstack/ +.. _libvirt: ../libvirt/ \ No newline at end of file