Skip to content

Commit 6e3e5de

Browse files
committed
Doc: add usage for nydus compression type
Introduce nydus image and show that how to export nydus image, and add known limitations. Signed-off-by: Yan Song <imeoer@linux.alibaba.com>
1 parent 5ba8aee commit 6e3e5de

File tree

1 file changed

+36
-0
lines changed

1 file changed

+36
-0
lines changed

docs/nydus.md

+36
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
## Nydus image formats
2+
3+
Nydus is an OCI/Docker-compatible accelerated image format provided by the [Dragonfly image-service project](https://github.com/dragonflyoss/image-service), which offers the ability to pull image data on-demand, without waiting for the entire image pull to complete and then start the container. It has been put in production usage and shown vast improvements to significantly reduce the overhead costs on time, network, disk IO of pulling image or starting container.
4+
5+
Nydus image can be flexibly configured as a FUSE-based user-space filesystem or in-kernel [EROFS](https://www.kernel.org/doc/html/latest/filesystems/erofs.html) (from Linux kernel v5.16) with Nydus daemon in user-space, integrating with VM-based container runtime like [KataContainers](https://katacontainers.io/) is much easier.
6+
7+
## Creating Nydus images
8+
9+
### Building Nydus with BuildKit
10+
11+
On buildkitd side, download `nydus-image` binary from [nydus release page](https://github.com/dragonflyoss/image-service/releases/download/v2.0.0-rc.0/nydus-static-v2.0.0-rc.0-x86_64.tgz) (require v2.0.0 or higher), then put the binary path into $PATH or specifying it to `NYDUS_BUILDER` environment variable for buildkitd:
12+
13+
```
14+
env NYDUS_BUILDER=/path/to/nydus-image buildkitd ...
15+
```
16+
17+
On buildctl side, export Nydus image as the one of compression types by specifying `compression=nydus` option:
18+
19+
```
20+
buildctl build ... \
21+
--output type=image,name=docker.io/username/image,push=true,compression=nydus,oci-mediatypes=true
22+
```
23+
24+
### Known limitations
25+
26+
- The export of Nydus image and runtime (e.g. [docker](https://github.com/dragonflyoss/image-service/tree/master/contrib/docker-nydus-graphdriver), [containerd](https://github.com/containerd/nydus-snapshotter), etc.) is currently only supported on linux platform.
27+
- Nydus image layers cannot be mixed with other compression types in the same image, so the `force-compression=true` option is automatically enabled when exporting both Nydus compression type and other compression types.
28+
- Specifying a Nydus image as a base image in a Dockerfile is not currently supported (i.e. lazily pull using a Nydus image).
29+
30+
### Other ways to create Nydus images
31+
32+
Pre-converted Nydus images are available at [`ghcr.io/dragonflyoss/image-service` repository](https://github.com/orgs/dragonflyoss/packages?ecosystem=container) (mainly for testing purpose).
33+
34+
[`Nydusify`](https://github.com/dragonflyoss/image-service/blob/master/docs/nydusify.md) The Nydusify CLI tool pulls & converts an OCIv1 image into a Nydus image, and pushes Nydus image to registry.
35+
36+
[`Harbor Acceld`](https://github.com/goharbor/acceleration-service) Harbor acceld provides a general service to convert OCIv1 image to acceleration image like [Nydus](https://github.com/dragonflyoss/image-service) and [eStargz](https://github.com/containerd/stargz-snapshotter) etc.

0 commit comments

Comments
 (0)