giuseppe / crfs-plugin

crfs-plugin

A fuse-overlayfs plugin for using CRFS for loading lower layers.

This is still experimental, use at your own risk.

Build

You need to have both the Go toolchain and the C compiler installed. Use make from the upper directory for building crfs-plugin:

$ make

If everything worked correctly and all the needed dependencies were present, the build generates a single crfs-plugin.so artifact that can be directly used from fuse-overlayfs.

You need to use fuse-overlayfs with plugins support from:

containers/fuse-overlayfs#119

Build a CRFS image

Before using crfs-plugin, you need to have a CRFS image.

To create one, you can use:

stargzify.

You can install it with:

$ go get -u github.com/google/crfs/stargz/stargzify

Once stargzify is installed, you can convert a image to the .stargz format with:

$ stargzify docker.io/fedora localhost:5000/myimages/fedora:stargz

Usage

There are a few new options needed to pass to fuse-overlays to work with crfs-plugin:

• fast_ino=1: force fuse-overlayfs to stop looking for an inode number after the first one found during the lookup.
• plugins=/path/a.so:/path2/b.so: list of plugins that fuse-overlayfs loads and can be used to handle lower layers.
• lowerdir=//$PLUGIN/$CONF/lowerdirpath: when a lowerdir path starts with //, fuse-overlay uses the plugin $PLUGIN to manage lowerdir with the specified configuration $CONF, that is specific to the plugin. For crfs-plugin, the configuration is the image/layer to use in base64 encoding.

Accepted configuration strings are:

• https://www.example.com/layer.stargz: use directly the layer at the URL.
• docker://docker.io/image:stargz: use the image at the specified registry.
• /path/to/the/file.stargz: use the file as a .stargz layer.

The easiest way run fuse-overlayfs is from a user namespace (or if you like danger, directly as root user).

When an image docker:// is used, fuse-overlayfs will internally create more lower layers depending on how many there are present in the image.

podman unshare can be helpful to create a user+mount namespace that can be used by an unprivileged user.

$ podman unshare
# mkdir lower upper workdir merged
# fuse-overlayfs -o fast_ino=1,plugins=/path/to/crfs-plugin.so,lowerdir=//crfs/$(echo -n docker://localhost:5000/myimages/fedora:stargz | base64 -w0)/$(pwd)/lower,upperdir=upper,workdir=work merged
# podman run --rm -ti --rootfs $(pwd)/merged echo hello

It is possible to use directly a URL for retrieving a .stargz layer. When the lowerdir location starts with the https:// prefix, then the file at that URL will be used directly.

# fuse-overlayfs -o fast_ino=1,plugins=/path/to/crfs-plugin.so,lowerdir=//crfs/$(echo -n https://url/to/stargzified-layer.tar.gz | base64 -w0)/$(pwd)/lower,upperdir=upper,workdir=work merged

Alternatively, it is possible to use a local file:

# fuse-overlayfs -o fast_ino=1,plugins=/path/to/crfs-plugin.so,lowerdir=//crfs/$(echo -n /path/to/stargzified-layer.tar.gz | base64 -w0)/$(pwd)/lower,upperdir=upper,workdir=work merged

Installation

make install will install crfs-plugin.so under $PREFIX/libexec/fuse-overlayfs/.

fuse-overlayfs will automatically load the plugins from that location, without requiring the additional -oplugins=... configuration at run time.

crfs-plugin's Issues

error reading 2802 byte TOC targz

Thanks for this plugin!

I gave it a go, but when creating the overlay, I'm getting:

[root@strigazi-podman-crfs-001 ~]# export DATA=$(echo -n docker://gitlab-registry.cern.ch/strigazi/containers/busybox:1.31-stargz | base64 -w0)
[root@strigazi-podman-crfs-001 ~]# fuse-overlayfs -d -o fast_ino=1,plugins=/usr/local/libexec/crfs-plugin.so,lowerdir=//crfs/$DATA/$(pwd)/lower,upperdir=upper,workdir=workdir merged
cannot open stargz file [100 111 99 107 101 114 58 47 47 103 105 116 108 97 98 45 114 101 103 105 115 116 114 121 46 99 101 114 110 46 99 104 47 115 116 114 105 103 97 122 105 47 99 111 110 116 97 105 110 101 114 115 47 98 117 115 121 98 111 120 58 49 46 51 49 45 115 116 97 114 103 122]: error reading 2802 byte TOC targz: Invalid status code returned when fetching blob 400 (Bad Request)

The image is publicly accessible. Any hints?

podman hangs when trying to run a stargz image

Hi @giuseppe,
Thanks for the plugin!
I was able to fetch a stargzified image but as soon as I try to run it, podman gets stuck.
I'm attaching the output with --log-level debug and podman info.

podman_run.txt
podman_info.txt

Do you have any hints? Thanks in advance!

P.S. I tried with --net=host and with no luck