ceph/doc/rbd/rbd-live-migration.rst

   1 ======================
   2  Image Live-Migration
   3 ======================
   4
   5 .. index:: Ceph Block Device; live-migration
   6
   7 RBD images can be live-migrated between different pools within the same cluster
   8 or between different image formats and layouts. When started, the source image
   9 will be deep-copied to the destination image, pulling all snapshot history and
  10 optionally keeping any link to the source image's parent to help preserve
  11 sparseness.
  12
  13 This copy process can safely run in the background while the new target image is
  14 in-use. There is currently a requirement to temporarily stop using the source
  15 image before preparing a migration. This helps to ensure that the client using
  16 the image is updated to point to the new target image.
  17
  18 .. note::
  19    Image live-migration requires the Ceph Nautilus release or later. The krbd
  20    kernel module does not support live-migration at this time.
  21
  22
  23 .. ditaa::
  24
  25            +-------------+               +-------------+
  26            | {s} c999    |               | {s}         |
  27            |  Live       | Target refers |  Live       |
  28            |  migration  |<-------------*|  migration  |
  29            |  source     |  to Source    |  target     |
  30            |             |               |             |
  31            | (read only) |               | (writable)  |
  32            +-------------+               +-------------+
  33
  34                Source                        Target
  35
  36 The live-migration process is comprised of three steps:
  37
  38 #. **Prepare Migration:** The initial step creates the new target image and
  39    cross-links the source and target images. Similar to `layered images`_,
  40    attempts to read uninitialized extents within the target image will
  41    internally redirect the read to the source image, and writes to
  42    uninitialized extents within the target will internally deep-copy the
  43    overlapping source image block to the target image.
  44
  45
  46 #. **Execute Migration:** This is a background operation that deep-copies all
  47    initialized blocks from the source image to the target. This step can be
  48    run while clients are actively using the new target image.
  49
  50
  51 #. **Finish Migration:** Once the background migration process has completed,
  52    the migration can be committed or aborted. Committing the migration will
  53    remove the cross-links between the source and target images, and will
  54    remove the source image. Aborting the migration will remove the cross-links,
  55    and will remove the target image.
  56
  57 Prepare Migration
  58 =================
  59
  60 The live-migration process is initiated by running the `rbd migration prepare`
  61 command, providing the source and target images::
  62
  63     $ rbd migration prepare migration_source [migration_target]
  64
  65 The `rbd migration prepare` command accepts all the same layout optionals as the
  66 `rbd create` command, which allows changes to the immutable image on-disk
  67 layout. The `migration_target` can be skipped if the goal is only to change the
  68 on-disk layout, keeping the original image name.
  69
  70 All clients using the source image must be stopped prior to preparing a
  71 live-migration. The prepare step will fail if it finds any running clients with
  72 the image open in read/write mode. Once the prepare step is complete, the
  73 clients can be restarted using the new target image name. Attempting to restart
  74 the clients using the source image name will result in failure.
  75
  76 The `rbd status` command will show the current state of the live-migration::
  77
  78     $ rbd status migration_target
  79     Watchers: none
  80     Migration:
  81                 source: rbd/migration_source (5e2cba2f62e)
  82                 destination: rbd/migration_target (5e2ed95ed806)
  83                 state: prepared
  84
  85 Note that the source image will be moved to the RBD trash to avoid mistaken
  86 usage during the migration process::
  87
  88     $ rbd info migration_source
  89     rbd: error opening image migration_source: (2) No such file or directory
  90     $ rbd trash ls --all
  91     5e2cba2f62e migration_source
  92
  93
  94 Execute Migration
  95 =================
  96
  97 After preparing the live-migration, the image blocks from the source image
  98 must be copied to the target image. This is accomplished by running the
  99 `rbd migration execute` command::
 100
 101     $ rbd migration execute migration_target
 102     Image migration: 100% complete...done.
 103
 104 The `rbd status` command will also provide feedback on the progress of the
 105 migration block deep-copy process::
 106
 107     $ rbd status migration_target
 108     Watchers:
 109         watcher=1.2.3.4:0/3695551461 client.123 cookie=123
 110     Migration:
 111                 source: rbd/migration_source (5e2cba2f62e)
 112                 destination: rbd/migration_target (5e2ed95ed806)
 113                 state: executing (32% complete)
 114
 115
 116 Commit Migration
 117 ================
 118
 119 Once the live-migration has completed deep-copying all data blocks from the
 120 source image to the target, the migration can be committed::
 121
 122     $ rbd status migration_target
 123     Watchers: none
 124     Migration:
 125                 source: rbd/migration_source (5e2cba2f62e)
 126                 destination: rbd/migration_target (5e2ed95ed806)
 127                 state: executed
 128     $ rbd migration commit migration_target
 129     Commit image migration: 100% complete...done.
 130
 131 If the `migration_source` image is a parent of one or more clones, the `--force`
 132 option will need to be specified after ensuring all descendent clone images are
 133 not in use.
 134
 135 Committing the live-migration will remove the cross-links between the source
 136 and target images, and will remove the source image::
 137
 138     $ rbd trash list --all
 139
 140
 141 Abort Migration
 142 ===============
 143
 144 If you wish to revert the prepare or execute step, run the `rbd migration abort`
 145 command to revert the migration process::
 146
 147         $ rbd migration abort migration_target
 148         Abort image migration: 100% complete...done.
 149
 150 Aborting the migration will result in the target image being deleted and access
 151 to the original source image being restored::
 152
 153         $ rbd ls
 154         migration_source
 155
 156
 157 .. _layered images: ../rbd-snapshot/#layering