src/ceph/doc/rbd/rbd-snapshot.rst

   1 ===========
   2  Snapshots
   3 ===========
   4
   5 .. index:: Ceph Block Device; snapshots
   6
   7 A snapshot is a read-only copy of the state of an image at a particular point in
   8 time. One of the advanced features of Ceph block devices is that you can create
   9 snapshots of the images to retain a history of an image's state. Ceph also
  10 supports snapshot layering, which allows you to clone images (e.g., a VM image)
  11 quickly and easily. Ceph supports block device snapshots using the ``rbd``
  12 command and many higher level interfaces, including `QEMU`_, `libvirt`_,
  13 `OpenStack`_ and `CloudStack`_.
  14
  15 .. important:: To use use RBD snapshots, you must have a running Ceph cluster.
  16
  17 .. note:: If a snapshot is taken while `I/O` is still in progress in a image, the
  18    snapshot might not get the exact or latest data of the image and the snapshot
  19    may have to be cloned to a new image to be mountable. So, we recommend to stop
  20    `I/O` before taking a snapshot of an image. If the image contains a filesystem,
  21    the filesystem must be in a consistent state before taking a snapshot. To stop
  22    `I/O` you can use `fsfreeze` command. See `fsfreeze(8)` man page for more details.
  23    For virtual machines, `qemu-guest-agent` can be used to automatically freeze
  24    filesystems when creating a snapshot.
  25
  26 .. ditaa:: +------------+         +-------------+
  27            | {s}        |         | {s} c999    |
  28            |   Active   |<-------*|   Snapshot  |
  29            |   Image    |         |   of Image  |
  30            | (stop i/o) |         | (read only) |
  31            +------------+         +-------------+
  32
  33
  34 Cephx Notes
  35 ===========
  36
  37 When `cephx`_ is enabled (it is by default), you must specify a user name or ID
  38 and a path to the keyring containing the corresponding key for the user. See
  39 `User Management`_ for details. You may also add the ``CEPH_ARGS`` environment
  40 variable to avoid re-entry of the following parameters. ::
  41
  42         rbd --id {user-ID} --keyring=/path/to/secret [commands]
  43         rbd --name {username} --keyring=/path/to/secret [commands]
  44
  45 For example::
  46
  47         rbd --id admin --keyring=/etc/ceph/ceph.keyring [commands]
  48         rbd --name client.admin --keyring=/etc/ceph/ceph.keyring [commands]
  49
  50 .. tip:: Add the user and secret to the ``CEPH_ARGS`` environment
  51    variable so that you don't need to enter them each time.
  52
  53
  54 Snapshot Basics
  55 ===============
  56
  57 The following procedures demonstrate how to create, list, and remove
  58 snapshots using the ``rbd`` command on the command line.
  59
  60 Create Snapshot
  61 ---------------
  62
  63 To create a snapshot with ``rbd``, specify the ``snap create`` option,  the pool
  64 name and the image name.  ::
  65
  66         rbd snap create {pool-name}/{image-name}@{snap-name}
  67
  68 For example::
  69
  70         rbd snap create rbd/foo@snapname
  71
  72
  73 List Snapshots
  74 --------------
  75
  76 To list snapshots of an image, specify the pool name and the image name. ::
  77
  78         rbd snap ls {pool-name}/{image-name}
  79
  80 For example::
  81
  82         rbd snap ls rbd/foo
  83
  84
  85 Rollback Snapshot
  86 -----------------
  87
  88 To rollback to a snapshot with ``rbd``, specify the ``snap rollback`` option, the
  89 pool name, the image name and the snap name. ::
  90
  91         rbd snap rollback {pool-name}/{image-name}@{snap-name}
  92
  93 For example::
  94
  95         rbd snap rollback rbd/foo@snapname
  96
  97
  98 .. note:: Rolling back an image to a snapshot means overwriting
  99    the current version of the image with data from a snapshot. The
 100    time it takes to execute a rollback increases with the size of the
 101    image. It is **faster to clone** from a snapshot **than to rollback**
 102    an image to a snapshot, and it is the preferred method of returning
 103    to a pre-existing state.
 104
 105
 106 Delete a Snapshot
 107 -----------------
 108
 109 To delete a snapshot with ``rbd``, specify the ``snap rm`` option, the pool
 110 name, the image name and the snap name. ::
 111
 112         rbd snap rm {pool-name}/{image-name}@{snap-name}
 113
 114 For example::
 115
 116         rbd snap rm rbd/foo@snapname
 117
 118
 119 .. note:: Ceph OSDs delete data asynchronously, so deleting a snapshot
 120    doesn't free up the disk space immediately.
 121
 122 Purge Snapshots
 123 ---------------
 124
 125 To delete all snapshots for an image with ``rbd``, specify the ``snap purge``
 126 option and the image name. ::
 127
 128         rbd snap purge {pool-name}/{image-name}
 129
 130 For example::
 131
 132         rbd snap purge rbd/foo
 133
 134
 135 .. index:: Ceph Block Device; snapshot layering
 136
 137 Layering
 138 ========
 139
 140 Ceph supports the ability to create many copy-on-write (COW) clones of a block
 141 device shapshot. Snapshot layering enables Ceph block device clients to create
 142 images very quickly. For example, you might create a block device image with a
 143 Linux VM written to it; then, snapshot the image, protect the snapshot, and
 144 create as many copy-on-write clones as you like. A snapshot is read-only,
 145 so cloning a snapshot simplifies semantics--making it possible to create
 146 clones rapidly.
 147
 148
 149 .. ditaa:: +-------------+              +-------------+
 150            | {s} c999    |              | {s}         |
 151            |  Snapshot   | Child refers |  COW Clone  |
 152            |  of Image   |<------------*| of Snapshot |
 153            |             |  to Parent   |             |
 154            | (read only) |              | (writable)  |
 155            +-------------+              +-------------+
 156
 157                Parent                        Child
 158
 159 .. note:: The terms "parent" and "child" mean a Ceph block device snapshot (parent),
 160    and the corresponding image cloned from the snapshot (child). These terms are
 161    important for the command line usage below.
 162
 163 Each cloned image (child) stores a reference to its parent image, which enables
 164 the cloned image to open the parent snapshot and read it.
 165
 166 A COW clone of a snapshot behaves exactly like any other Ceph block device
 167 image. You can read to, write from, clone, and resize cloned images. There are
 168 no special restrictions with cloned images. However, the copy-on-write clone of
 169 a snapshot refers to the snapshot, so you **MUST** protect the snapshot before
 170 you clone it. The following diagram depicts the process.
 171
 172 .. note:: Ceph only supports cloning for format 2 images (i.e., created with
 173    ``rbd create --image-format 2``).  The kernel client supports cloned images
 174    since kernel 3.10.
 175
 176 Getting Started with Layering
 177 -----------------------------
 178
 179 Ceph block device layering is a simple process. You must have an image. You must
 180 create a snapshot of the image. You must protect the snapshot. Once you have
 181 performed these steps, you can begin cloning the snapshot.
 182
 183 .. ditaa:: +----------------------------+        +-----------------------------+
 184            |                            |        |                             |
 185            | Create Block Device Image  |------->|      Create a Snapshot      |
 186            |                            |        |                             |
 187            +----------------------------+        +-----------------------------+
 188                                                                 |
 189                          +--------------------------------------+
 190                          |
 191                          v
 192            +----------------------------+        +-----------------------------+
 193            |                            |        |                             |
 194            |   Protect the Snapshot     |------->|     Clone the Snapshot      |
 195            |                            |        |                             |
 196            +----------------------------+        +-----------------------------+
 197
 198
 199 The cloned image has a reference to the parent snapshot, and includes the pool
 200 ID,  image ID and snapshot ID. The inclusion of the pool ID means that you may
 201 clone snapshots  from one pool to images in another pool.
 202
 203
 204 #. **Image Template:** A common use case for block device layering is to create a
 205    a master image and a snapshot that serves as a template for clones. For example,
 206    a user may create an image for a Linux distribution (e.g., Ubuntu 12.04), and
 207    create a snapshot for it. Periodically, the user may update the image and create
 208    a new snapshot (e.g., ``sudo apt-get update``, ``sudo apt-get upgrade``,
 209    ``sudo apt-get dist-upgrade`` followed by ``rbd snap create``). As the image
 210    matures, the user can clone any one of the snapshots.
 211
 212 #. **Extended Template:** A more advanced use case includes extending a template
 213    image that provides more information than a base image. For example, a user may
 214    clone an image (e.g., a VM template) and install other software (e.g., a database,
 215    a content management system, an analytics system, etc.) and then snapshot the
 216    extended image, which itself may be updated just like the base image.
 217
 218 #. **Template Pool:** One way to use block device layering is to create a
 219    pool that contains master images that act as templates, and snapshots of those
 220    templates. You may then extend read-only privileges to users so that they
 221    may clone the snapshots without the ability to write or execute within the pool.
 222
 223 #. **Image Migration/Recovery:** One way to use block device layering is to migrate
 224    or recover data from one pool into another pool.
 225
 226 Protecting a Snapshot
 227 ---------------------
 228
 229 Clones access the parent snapshots. All clones would break if a user inadvertently
 230 deleted the parent snapshot. To prevent data loss, you **MUST** protect the
 231 snapshot before you can clone it. ::
 232
 233         rbd snap protect {pool-name}/{image-name}@{snapshot-name}
 234
 235 For example::
 236
 237         rbd snap protect rbd/my-image@my-snapshot
 238
 239 .. note:: You cannot delete a protected snapshot.
 240
 241 Cloning a Snapshot
 242 ------------------
 243
 244 To clone a snapshot, specify you need to specify the parent pool, image and
 245 snapshot; and, the child pool and image name. You must protect the snapshot
 246 before  you can clone it. ::
 247
 248         rbd clone {pool-name}/{parent-image}@{snap-name} {pool-name}/{child-image-name}
 249
 250 For example::
 251
 252         rbd clone rbd/my-image@my-snapshot rbd/new-image
 253
 254 .. note:: You may clone a snapshot from one pool to an image in another pool. For example,
 255    you may maintain read-only images and snapshots as templates in one pool, and writeable
 256    clones in another pool.
 257
 258 Unprotecting a Snapshot
 259 -----------------------
 260
 261 Before you can delete a snapshot, you must unprotect it first. Additionally,
 262 you may *NOT* delete snapshots that have references from clones. You must
 263 flatten each clone of a snapshot, before you can delete the snapshot. ::
 264
 265         rbd snap unprotect {pool-name}/{image-name}@{snapshot-name}
 266
 267 For example::
 268
 269         rbd snap unprotect rbd/my-image@my-snapshot
 270
 271
 272 Listing Children of a Snapshot
 273 ------------------------------
 274
 275 To list the children of a snapshot, execute the following::
 276
 277         rbd children {pool-name}/{image-name}@{snapshot-name}
 278
 279 For example::
 280
 281         rbd children rbd/my-image@my-snapshot
 282
 283
 284 Flattening a Cloned Image
 285 -------------------------
 286
 287 Cloned images retain a reference to the parent snapshot. When you remove the
 288 reference from the child clone to the parent snapshot, you effectively "flatten"
 289 the image by copying the information from the snapshot to the clone. The time
 290 it takes to flatten a clone increases with the size of the snapshot. To delete
 291 a snapshot, you must flatten the child images first. ::
 292
 293         rbd flatten {pool-name}/{image-name}
 294
 295 For example::
 296
 297         rbd flatten rbd/my-image
 298
 299 .. note:: Since a flattened image contains all the information from the snapshot,
 300    a flattened image will take up more storage space than a layered clone.
 301
 302
 303 .. _cephx: ../../rados/configuration/auth-config-ref/
 304 .. _User Management: ../../operations/user-management
 305 .. _QEMU: ../qemu-rbd/
 306 .. _OpenStack: ../rbd-openstack/
 307 .. _CloudStack: ../rbd-cloudstack/
 308 .. _libvirt: ../libvirt/