umoci’s workflow is based around an unpack-repack cycle, with some separate configuration steps. Most users are going to be primarily using the unpack and repack subcommands for most uses of umoci.
Each image consists of a set of layers and a configuration that describes how
the image should be used.
umoci unpack allows you to take an image and
extract its root filesystem and configuration into an runtime
bundle. This bundle can be used by an OCI compliant container
runtime to spawn a container, but also can be used directly by non-containers
(as it is just a directory).
% sudo umoci unpack --image opensuse:42.2 bundle % ls -l bundle total 720 -rw-r--r-- 1 root root 3247 Jul 3 17:58 config.json drwxr-xr-x 1 root root 128 Jan 1 1970 rootfs -rw-r--r-- 1 root root 725320 Jul 3 17:58 sha256_8eac95fae2d9d0144607ffde0248b2eb46556318dcce7a9e4cc92edcd2100b67.mtree -rw-r--r-- 1 root root 270 Jul 3 17:58 umoci.json % cat bundle/rootfs/etc/os-release NAME="openSUSE Leap" VERSION="42.2" ID=opensuse ID_LIKE="suse" VERSION_ID="42.2" PRETTY_NAME="openSUSE Leap 42.2" ANSI_COLOR="0;32" CPE_NAME="cpe:/o:opensuse:leap:42.2" BUG_REPORT_URL="https://bugs.opensuse.org" HOME_URL="https://www.opensuse.org/"
% sudo runc run -b bundle ctr-name sh-4.3# grep NAME /etc/os-release NAME="openSUSE Leap" sh-4.3# uname -n mrsdalloway
After making some changes to the root filesystem of your extracted image, you may want to create a new delta layer from the changes. Note that the way you modified the image does not matter, you can create a container using the extracted root filesystem or just modify it directly.
umoci repack will create a derived image based on the image originally
extracted to create the runtime bundle. Even if the original image
has been “modified”,
umoci repack will still use the original. Note that in
--image refers to the new tag that will be used to reference
the modified image (which may be the same tag used to extract the original
umoci repack does not work across different images – both the source
and destination must be in the same image (and the original blobs must not have
been garbage collected).
% echo "some change" > bundle/rootfs/my_change % sudo umoci repack --image opensuse:new bundle % sudo umoci unpack --image opensuse:new bundle2 % cat bundle2/rootfs/my_change some change
Note that any changes to
bundle/config.json will not change the image’s
configuration. You can change an image’s configuration using the dedicated
In order to change the configuration of an image,
umoci config can be used. A
full description of what each configuration option means is beyond the scope of
this document, but you can read the spec for more
umoci config will override the tag given with
--image but you
can force the change to create a new tag (leaving the original unchanged) with
% umoci config --author="Aleksa Sarai <email@example.com>" --image opensuse
Note that both
umoci config and
umoci repack include entries in the history
of the image. You can change what the history entry contains for a particular
operation by using the
--history. set of flags (for both
umoci repack and