[Devel] [PATCH vz9 10/10] FD: fs/ext4: fast online shrink support

[Konstantin Khorenko]

Signed-off-by: Konstantin Khorenko <khorenko at 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