Merge pull request #165 from WaberZhuang/main

add doc for standalone userspace image-convertor

Author: liulanzheng

README.md

@@ -38,12 +38,18 @@ Accelerated Container Image is a __non-core__ sub-project of containerd.
 
     It is a [containerd](https://containerd.io/) snapshotter plugin for overlaybd image. This snapshotter is compatible for OCI image, as well as overlayfs snapshotter.
 
-* image-convertor
+* embedded image-convertor
 
     We provide a modified CLI tool(ctr) to facilitate image pull, and custom conversion from traditional OCI tarball format to overlaybd format.
 
     The convertor supports layer deduplication, which prevents duplication of layer conversion for every image conversion.
 
+* standalone userspace image-convertor (Experimental)
+
+    Standalone userspace image-convertor has similar functionality to embedded image-convertor but runs in the userspace. It does not require root privilege and dependence on tcmu, configfs, snapshotter, or even on containerd. which makes it much more convenient to run in a container.
+
+    What's more, standalone userspace image-convertor is faster than embedded image-convertor when used with our [customized libext2fs](https://github.com/data-accelerator/e2fsprogs). See [USERSPACE_CONVERTOR](https://github.com/containerd/accelerated-container-image/blob/main/docs/USERSPACE_CONVERTOR.md) for more details.
+
 * [buildkit for overlaybd](https://github.com/data-accelerator/buildkit) (Experimental)
 
     It is a customized buildkit for overlaybd images. It fetches the data of base images on demand without pulling whole data and uses overlaybd writable layer to build new layers.
@@ -62,9 +68,9 @@ Accelerated Container Image is a __non-core__ sub-project of containerd.
 
 * See how to convert OCI image into overlaybd with specified file system at [MULTI_FS_SUPPORT](docs/MULTI_FS_SUPPORT.md).
 
-* See how to use layer deduplication for image conversion at [IMAGE_CONVERTOR](docs/IMAGE_CONVERTOR.md)
+* See how to use layer deduplication for image conversion at [IMAGE_CONVERTOR](docs/IMAGE_CONVERTOR.md).
 
-* See how to use overlaybd writable layer at [WRITABLE](docs/WRITABLE.md)
+* See how to use overlaybd writable layer at [WRITABLE](docs/WRITABLE.md).
 
 * Welcome to contribute! [CONTRIBUTING](docs/CONTRIBUTING.md)
 

docs/IMAGE_CONVERTOR.md

@@ -1,4 +1,4 @@
-# Image Convertor
+# Embedded Image Convertor
 
 We provide a ctr command tool to convert OCIv1 images into overlaybd format, which is stored in `bin` after `make` or downloading the release package.
 

docs/QUICKSTART.md

@@ -95,8 +95,9 @@ Install dependencies:
 - cmake 3.15+
 - gcc/g++ 7+
 - development dependencies:
-    - CentOS/Fedora: sudo yum install libaio-devel libcurl-devel openssl-devel libnl3-devel
-    - Debian/Ubuntu: sudo apt install libcurl4-openssl-dev libssl-dev libaio-dev libnl-3-dev libnl-genl-3-dev libgflags-dev
+    - CentOS 7/Fedora: `sudo yum install libaio-devel libcurl-devel openssl-devel libnl3-devel libzstd-static e2fsprogs-devel`
+    - CentOS 8: `sudo yum install libaio-devel libcurl-devel openssl-devel libnl3-devel libzstd-devel e2fsprogs-devel`
+    - Debian/Ubuntu: `sudo apt install libcurl4-openssl-dev libssl-dev libaio-dev libnl-3-dev libnl-genl-3-dev libgflags-dev libzstd-dev libext2fs-dev`
 
 Run the following commands to build:
 ```bash
@@ -196,13 +197,15 @@ There are several methods.
     sudo ctr run --net-host --snapshotter=overlaybd --rm -t registry.hub.docker.com/overlaybd/redis:6.2.1_obd demo
     ```
 
-- usr k8s/cri
+- use k8s/cri
 
     Run with k8s or crictl, refer to [EXAMPLES_CRI](https://github.com/containerd/accelerated-container-image/blob/main/docs/EXAMPLES_CRI.md).
 
 ## Image conversion
 
-Images can be convert from oci format to overlaybd format by the following commands.
+There are 2 ways to convert images from oci format to overlaybd format, by using embedded image-convertor or using standalone userspace image-convertor respectively.
+
+- use embedded image-convertor
 
 ```bash
 # pull the source image (nerdctl or ctr)
@@ -218,6 +221,13 @@ sudo nerdctl push registry.hub.docker.com/overlaybd/redis:6.2.1_obd_new
 sudo nerdctl rmi registry.hub.docker.com/overlaybd/redis:6.2.1_obd_new
 ```
 
+- use standalone userspace image-convertor
+
+```bash
+# userspace-image-convertor will automatically pull and push images from and to the registry
+sudo /opt/overlaybd/snapshotter/convertor -r registry.hub.docker.com/library -i redis:6.2.1 -o 6.2.1_obd_new
+```
+
 ## Image build
 
 Overlaybd images can be efficiently built from overlaybd images by using the [customized buildkit](https://github.com/data-accelerator/buildkit).

docs/USERSPACE_CONVERTOR.md

@@ -1,32 +1,28 @@
-# Userspace Image Convertor
+# Standalone Userspace Image Convertor
 
-We provide a tool to convert OCIv1 images into overlaybd format in userspace, without the dependences of containerd and tcmu. Only several ovelraybd tools binary are required.
+Standalone userspace image-convertor is a tool to convert OCIv1 images into overlaybd format in userspace, without the dependences of containerd and tcmu. Only several ovelraybd tools binary are required.
 
 This convertor is stored in `bin` after `make`.
 
 This is an experimental feature and will be continuously improved.
 
 
-# Requirement
+## Requirement
 
 There's no need to install containerd, no need to launch and mount tcmu devices, no need to run as root.
 Only several tools are required:
 
-- overlaybd-create and overlaybd-commit
+- overlaybd-create, overlaybd-commit and overlaybd-apply
 
-  Two overlaybd tools provided in [overlaybd](https://github.com/containerd/overlaybd), stored at `/opt/overlaybd/bin`.
-
-- overlaybd-apply
-
-  A tool to apply oci layers into overlaybd, provided in [overlaybd-apply](https://github.com/data-accelerator/overlaybd-apply), stored at `/opt/overlaybd/bin`.
+  Three overlaybd tools provided in [overlaybd](https://github.com/containerd/overlaybd), stored at `/opt/overlaybd/bin`.
 
 - baselayer
 
   stored at `/opt/overlaybd/baselayers/ext4_64` after installing [overlaybd](https://github.com/containerd/overlaybd). This is only required just for now. Once the automatic mkfs is implemented, it's no longer needed.
 
 Overall, the requirements are `/opt/overlaybd/bin/{overlaybd-create,overlaybd-commit,overlaybd-apply}` and `/opt/overlaybd/baselayers/ext4_64`.
 
-# Basic Usage
+## Basic Usage
 
 ```bash
 # usage
@@ -50,3 +46,20 @@ Flags:
 $ bin/convertor -r docker.io/overlaybd/redis -u user:pass -i 6.2.6 -o 6.2.6_obd
 
 ```
+
+## libext2fs
+
+Standalone userspace image-convertor is developed based on [libext2fs](https://github.com/tytso/e2fsprogs), and we have provided a [customized libext2fs](https://github.com/data-accelerator/e2fsprogs) to make the conversion faster. We used `standalone userspace image-convertor (with custom libext2fs)`, `standalone userspace image-convertor (with origin libext2fs)` and `embedded image-convertor` to convert some images and did a comparison for reference.
+
+### Performance
+
+| Image               | Image Size | with custom libext2fs | with origin libext2fs | embedded image-convertor |
+|:-------------------:|:----------:|:---------------------:|:---------------------:|:------------------------:|
+| jupyter-notebook    | 4.84 GB    | 93 s                  | 238 s                 | 101 s                    |
+| php-laravel-nginx   | 567 MB     | 13 s                  | 20 s                  | 15 s                     |
+| ai-cat-or-dog       | 1.81 GB    | 27 s                  | 54 s                  | 60 s                     |
+| cypress-chrome      | 2.73 GB    | 70 s                  | 212 s                 | 87 s                     |
+
+### Use with origin libext2fs
+
+Standalone userspace image-convertor uses customized libext2fs by default. If you want to use original libext2fs instead of it, see the cmake cache entry `-D ORIGIN_EXT2FS=1` of [overlaybd](https://github.com/containerd/overlaybd#build).