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