mirror of
https://github.com/ceph/ceph
synced 2024-12-28 14:34:13 +00:00
6ebb486304
The docs were incorrectly usins 'rbd snap children' when the actual command is 'rbd children'. Signed-off-by: Travis Rhoden <trhoden@gmail.com>
324 lines
12 KiB
ReStructuredText
324 lines
12 KiB
ReStructuredText
===========
|
|
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:: **STOP I/O BEFORE** snapshotting an image.
|
|
If the image contains a filesystem, the filesystem must be in a
|
|
consistent state **BEFORE** snapshotting.
|
|
|
|
.. ditaa:: +------------+ +-------------+
|
|
| {s} | | {s} c999 |
|
|
| Active |<-------*| Snapshot |
|
|
| Image | | of Image |
|
|
| (stop i/o) | | (read only) |
|
|
+------------+ +-------------+
|
|
|
|
|
|
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 --id {user-name} --keyring=/path/to/secret [commands]
|
|
|
|
For example::
|
|
|
|
rbd --id 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 --pool {pool-name} snap create --snap {snap-name} {image-name}
|
|
rbd snap create {pool-name}/{image-name}@{snap-name}
|
|
|
|
For example::
|
|
|
|
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 and the image name. ::
|
|
|
|
rbd --pool {pool-name} snap ls {image-name}
|
|
rbd snap ls {pool-name}/{image-name}
|
|
|
|
For example::
|
|
|
|
rbd --pool rbd snap ls foo
|
|
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 --pool {pool-name} snap rollback --snap {snap-name} {image-name}
|
|
rbd snap rollback {pool-name}/{image-name}@{snap-name}
|
|
|
|
For example::
|
|
|
|
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. ::
|
|
|
|
rbd --pool {pool-name} snap rm --snap {snap-name} {image-name}
|
|
rbd snap rm {pool-name}/{image-name}@{snap-name}
|
|
|
|
For example::
|
|
|
|
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
|
|
|
|
|
|
.. 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 --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} children --image {image-name} --snap {snap-name}
|
|
rbd children {pool-name}/{image-name}@{snapshot-name}
|
|
|
|
For example::
|
|
|
|
rbd --pool rbd children --image my-image --snap my-snapshot
|
|
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 --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: ../../rados/operations/authentication/
|
|
.. _QEMU: ../qemu-rbd/
|
|
.. _OpenStack: ../rbd-openstack/
|
|
.. _CloudStack: ../rbd-cloudstack/
|
|
.. _libvirt: ../libvirt/ |