Signed-off-by: Konstantin Khorenko <khore...@virtuozzo.com> --- .../fs-ext4-fast_online_shrink_support.rst | 113 ++++++++++++++++++ .../fs-xfs-fast_online_shrink_support.rst | 1 + 2 files changed, 114 insertions(+) create mode 100644 Documentation/Virtuozzo/FeatureDescriptions/fs-ext4-fast_online_shrink_support.rst create mode 120000 Documentation/Virtuozzo/FeatureDescriptions/fs-xfs-fast_online_shrink_support.rst
diff --git a/Documentation/Virtuozzo/FeatureDescriptions/fs-ext4-fast_online_shrink_support.rst b/Documentation/Virtuozzo/FeatureDescriptions/fs-ext4-fast_online_shrink_support.rst new file mode 100644 index 000000000000..75ffdd272fc1 --- /dev/null +++ b/Documentation/Virtuozzo/FeatureDescriptions/fs-ext4-fast_online_shrink_support.rst @@ -0,0 +1,113 @@ +============================== +fs: fast online shrink support +============================== + +Background: +=========== + +ploop doesn't support pure shrinking block-device size due to lack of +online shrink support in ext4. As a workaround, "ballooning" technique is +proposed. + +Ballooning operation consists of inflating special balloon file in +user-space (the file will be invisible for ordinary users, e.g. inside +container), loading fiemap info of inflated balloon to kernel, relocating +blocks of image file from the tail to the space specified by fiemap info +and truncating tail of image file. + +Implementation description: +=========================== + +Desired outcome is image file of smaller size. However, it's quite possible +that inflated balloon file will span only blocks that were never touched +before. They will look as "not allocated" space from kernel ploop view. +In this case nothing will be relocated and nothing truncated. + +So, if balloon operation succeeded, it's only guaranteed that user of ploop +device won't be able to consume more space than initial block device size +minus size of inflated balloon. On the other hand, if user of block device +used a lot of space on it, then freed significant part of used space, +balloon operation will result in significant truncate of image file. + +Note 1: currently ext4 and xfs filesystems are supported. The text is +written using the ext4 as an example, all the things are true for xfs as +well. + +Note 2: ploop images are used for iSCSI scenario implementation in vStorage +and in Incus Containers scenario, both of them benefit from the ploop +online shrink feature. + +Brief ploop balloon usage description: +-------------------------------------- + +To enable ballooning, ext4 residing on ploop device should be mounted with +special "balloon_ino" option:: + + # mount -t ext4 -o balloon_ino=12 /dev/ploop0 /mnt_ploop + +where 12 is inode number of balloon file as reported by "ls -i". +It's assumed that initially, e.g. while constructing container, someone +mounted ext4 on ploop device w/o balloon_ino option, then created empty +balloon file there, found out its inode number and saved it for the future +use. + +Currently, only online ballooning is supported. The following command +performs this operation:: + + # ploop balloon change -s 1g -d /dev/ploop0 -m /mnt_ploop + + // 1g - desired new size of balloon file + // /dev/ploop0 - ploop block device + // /mnt_ploop - mount-point where ext4 residing on /dev/ploop0 is + mounted to + +If balloon file was empty, the command above simply inflates it to become +1GB size. If it was non-empty but smaller than 1GB, that command extends it +to given size (1GB). If it was non-empty but larger that 1GB, that command +truncates it down to given size. If it was exactly 1GB size, the command +does nothing. + +Along with "change" sub-command, "ploop balloon" supports a few auxiliary +ones:: + + # ploop balloon show -m /mnt_ploop + will show current ploop balloon size. + + # ploop balloon status -d /dev/ploop0 -m /mnt_ploop + will report current in-kernel status of maintenance like "merge in + progress", "grow in progress", "ballooning started", etc. This is + useful because on the one hand balloon operation can't be performed + while merge or grow is in progress, and on the other hand previous + "ploop balloon" could be killed by someone before its completion. + + # ploop balloon clear -d /dev/ploop0 -m /mnt_ploop + will flush stale in-kernel "BALLOON" state of maintenance. This is + useful if previous "ploop balloon" died early leaving in-kernel ploop + locked. + + # ploop balloon complete -d /dev/ploop0 -m /mnt_ploop + will complete previously interrupted balloon operation. An expectation + is that user monitors exit status of ploop commands he/she runs in some + way. If user issued "ploop balloon change" and it was killed in the + middle, the user knows that it didn't complete with zero exit status. + Then user should inquire current maintenance state with "ploop balloon + status" command, and, if it reported "FBLOAD" or "RELOC", the user + should use "ploop balloon complete" before proceeding with any other + maintenance operations (snapshot, merge, grow, balloon). + + # ploop balloon check -d /dev/ploop0 -m /mnt_ploop + will check whether existent balloon file was properly processed. This + is useful if previous "ploop balloon" was interrupted, but "ploop + balloon status" reports "OFF" or "BALLOON" maintenance state. In this + case it's possible that balloon file was inflated but no further + processing happened. + + # ploop balloon check + reports total number of free blocks in existent balloon file. If it's + not zero, the user should use the following command to repair balloon: + + # ploop balloon repair -d /dev/ploop0 -m /mnt_ploop + will do essentially the same as "ploop balloon change" but w/o + inflating balloon. + +https://wiki.openvz.org/Ploop/readme#Ballooning diff --git a/Documentation/Virtuozzo/FeatureDescriptions/fs-xfs-fast_online_shrink_support.rst b/Documentation/Virtuozzo/FeatureDescriptions/fs-xfs-fast_online_shrink_support.rst new file mode 120000 index 000000000000..092cf351b9b6 --- /dev/null +++ b/Documentation/Virtuozzo/FeatureDescriptions/fs-xfs-fast_online_shrink_support.rst @@ -0,0 +1 @@ +fs-ext4-fast_online_shrink_support.rst \ No newline at end of file -- 2.43.5 _______________________________________________ Devel mailing list Devel@openvz.org https://lists.openvz.org/mailman/listinfo/devel
