libvirt/docs/kbase/merging_disk_image_chains.rst
Kashyap Chamarthy f98759170e docs: kbase: Add a doc on merging disk image chains
This is a rewrite of:

    https://wiki.libvirt.org/page/Live-merge-an-entire-disk-image-chain-including-current-active-disk

Once this commit merges, the above wiki should point to this kbase
document.

Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com>
Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
2021-05-11 11:23:57 +02:00

201 lines
6.5 KiB
ReStructuredText

===============================
Merging disk image image chains
===============================
.. contents::
Context
=======
Sometimes a `disk image chain
<https://libvirt.org/kbase/backing_chains.html>`_ can get long and
cumbersome. For the purpose of illustration, consider this smaller disk
image chain::
base.raw <-- a.qcow2 <-- b.qcow2 <-- c.qcow2 (live QEMU)
You may want to reduce the backing chain length, or consolidate *all*
the disk images in the chain into a single image. But you want to
accomplish this *without* incurring guest down time. Here's how to go
about it.
The same principles used in the `live full disk backup
<https://libvirt.org/kbase/live_full_disk_backup.html>` document are
used here too.
Reducing the disk image chain length
====================================
Starting the earlier image chain::
base.raw <-- a.qcow2 <-- b.qcow2 <-- c.qcow2 (live QEMU)
Reduce the length of the chain by two images, with the resulting chain
being::
base.raw <-- c.qcow2 (live QEMU)
Where the ``base.raw`` contains the contents of ``a.qcow2`` and
``b.qcow2``.
#. Start by listing the current active disk image in use::
$ virsh domblklist vm1
Target Source
------------------------------------------------
vda /var/lib/libvirt/images/base.raw
#. Create the image chain by creating three QCOW2 overlays (or "external
snapshots") on top of each other, while adding some differentiating
content in each image::
$ virsh snapshot-create-as --domain vm1 snap1 \
--diskspec vda,file=/var/lib/libvirt/images/a.qcow2 \
--disk-only --no-metadata
# <Add a file in the guest>
$ virsh snapshot-create-as --domain vm1 snap2 \
--diskspec vda,file=/var/lib/libvirt/images/b.qcow2 \
--disk-only --no-metadata
# <Add another file in the guest>
$ virsh snapshot-create-as --domain vm1 snap3 \
--diskspec vda,file=/var/lib/libvirt/images/c.qcow2 \
--disk-only --no-metadata
#. Enumerate the backing file chain (here the ``force-share`` option
simply allows ``qemu-img`` to safely query the disk image status
while it is active) ::
$ qemu-img info --force-share --backing-chain /var/lib/libvirt/images/cur.qcow2
[...]
#. Again, list the current active disk image in use::
$ virsh domblklist vm1
Target Source
------------------------------------------------
vda /var/lib/libvirt/images/c.qcow2
#. Perform the "block-commit" by specify the "base" and "top" images,
i.e. merge the contents of ``b.qcow2`` *and* ``a.qcow2`` into
``base.raw``, *and* ::
$ virsh blockcommit vm1 vda \
--base=/var/lib/libvirt/images/base.raw
--top=/var/lib/libvirt/images/b.qcow2
A note on accessing 'base' and 'top' images
-------------------------------------------
Specifying file paths, as above, make sense when your disks are in the
local filesystem. However, when using more complicated setups such as
network block device (NBD) disks, there are no file paths. Hhere is
where accessing the disk by its index number comes into picture.
As an example, the below is the ``<disk>`` element of the guest XML for
with the original disk image chain of four images::
...
<disk type='file' device='disk'>
<driver name='qemu' type='qcow2'/>
<source file='/var/lib/libvirt/images/c.qcow2' index='4'/>
<backingStore type='file' index='3'>
<format type='qcow2'/>
<source file='/var/lib/libvirt/images/b.qcow2'/>
<backingStore type='file' index='2'>
<format type='qcow2'/>
<source file='/var/lib/libvirt/images/a.qcow2'/>
<backingStore type='file' index='1'>
<format type='raw'/>
<source file='/var/lib/libvirt/images/base.raw'/>
<backingStore/>
</backingStore>
</backingStore>
</backingStore>
<target dev='vda' bus='virtio'/>
<alias name='virtio-disk0'/>
<address type='pci' domain='0x0000' bus='0x00' slot='0x05' function='0x0'/>
</disk>
...
And we can merge the images ``a.qcow2`` and ``b.qcow2`` into
``base.qcow2`` using the index numbers 1 (for ``base.qcow2``) and ::
$> virsh blockcommit vm1 vda --base='vda[1]' --top='vda[3]'
Note that the shell quoting is necessary here, since unquoted ``[1]``
would do an unexpected shell "globbing" (i.e. file name expansion) if
you have a file '1' in the current directory
Accessing the disk images via their index numbers is more useful when
you're using blockCommit() API programmatically.
Consolidating an entire disk image chain into a single image
============================================================
Again, starting the original image chain::
base.raw <-- a.qcow2 <-- b.qcow2 <-- c.qcow2 (live QEMU)
Reduce the length of the chain by two images, with the resulting chain
being::
base.raw (live QEMU)
Where the ``base.raw`` contains the contents of ``a.qcow2``, ``b.qcow2``
and ``c.qcow2``; *and* the live QEMU is piovoted to point to the
``base.raw``.
#. Use the same procedure discussed earlier to create the disk image
chain.
#. Now perform the "active block-commit" operation::
$ virsh blockcommit vm1 vda --verbose --pivot --active
Block Commit: [100 %]
Successfully pivoted
Notes:
- ``--active``: It performs a two-stage operation: first, the contents
from top images (``a.qcow2``, ``b.qcow2``, and ``c.qcow2``) are
committed into the base image; and in the second stage, the
"block-commit" operation remains awake to synchronize any further
changes from top images into base. Here the user can take two
actions: cancel the job, or pivot the job, i.e. adjust the base
image as the current active image.
- ``--pivot``: Once data is committed from sn1, sn2 and current into
base, it pivots the live QEMU to use base as the active image.
- ``--verbose``: It shows the progress of block operation.
#. Again, check the current active block device in use::
$ virsh domblklist vm1
Target Source
------------------------------------------------
vda /var/lib/libvirt/images/base.raw
#. Enumerate the backing file chain::
$ qemu-img info --backing-chain /var/lib/libvirt/images/base.raw
[...]
And the final resulting disk image "chain" will be a single,
consolidated disk image::
[base] (live QEMU)
It is worth bearing in mind that once the above pivot completes, *all*
three overlay files — ``a.qcow2``, ``b.qcow2``, and ``c.qcow2`` — are no
longer valid, and can be safely discarded.