youki is an implementation of the OCI runtime-spec in Rust, similar to runc.
Your ideas are welcome here.
youki is pronounced as /joʊki/ or yoh-key. youki is named after the Japanese word 'youki', which means 'a container'. In Japanese language, youki also means 'cheerful', 'merry', or 'hilarious'.
Tip
You can immediately set up your environment with youki on GitHub Codespaces and try it out.
just builddocker run --runtime youki hello-worldsudo podman run --cgroup-manager=cgroupfs --runtime /workspaces/youki/youki hello-worldHere is why we are writing a new container runtime in Rust.
Rust is one of the best languages to implement the oci-runtime spec. Many very nice container tools are currently written in Go. However, the container runtime requires the use of system calls, which requires a bit of special handling when implemented in Go. This is tricky (e.g. namespaces(7), fork(2)); with Rust too, but it's not that tricky. And, unlike in C, Rust provides the benefit of memory safety. While Rust is not yet a major player in the container field, it has the potential to contribute a lot: something this project attempts to exemplify.
youki has the potential to be faster and use less memory than runc, and therefore work in environments with tight memory usage requirements. Here is a simple benchmark of a container from creation to deletion.
Runtime Time (mean ± σ) Range (min … max) vs youki(mean) Version youki 111.5 ms ± 11.6 ms 84.0 ms ± 142.5 ms 100% 0.3.3 runc 224.6 ms ± 12.0 ms 190.5 ms ± 255.4 ms 200% 1.1.7 crun 47.3 ms ± 2.8 ms 42.4 ms ± 56.2 ms 42% 1.15 Details about the benchmark
A command used for the benchmark
hyperfine --prepare 'sudo sync; echo 3 | sudo tee /proc/sys/vm/drop_caches' --warmup 10 --min-runs 100 'sudo ./youki create -b tutorial a && sudo ./youki start a && sudo ./youki delete -f a'
Environment
$ ./youki infoVersion 0.3.3Commit 4f3c8307Kernel-Release 6.5.0-35-genericKernel-Version #35~22.04.1-Ubuntu SMP PREEMPT_DYNAMIC Tue May 7 09:00:52 UTC 2Architecture x86_64Operating System Ubuntu 22.04.4 LTSCores 16Total Memory 63870Cgroup setup unifiedCgroup mountsNamespaces enabled mount enabled uts enabled ipc enabled user enabled pid enabled network enabled cgroup enabledCapabilitiesCAP_BPF availableCAP_PERFMON availableCAP_CHECKPOINT_RESTORE available
I have fun implementing this. In fact, this may be the most important.
youki has aced real-world use cases, including containerd's e2e test, and is now adopted by several production environments. See Adopters and Use Cases for public examples. We have our roadmap.
- youki-dev/oci-spec-rs - OCI Runtime and Image Spec in Rust
The User and Developer Documentation for youki is hosted at https://youki-dev.github.io/youki/
Local build is only supported on Linux. For other platforms, please use the Vagrantfile that we have prepared. You can also spin up a fully preconfigured development environment in the cloud with GitHub Codespaces.
- Rust(See here), edition 2024
- linux kernel ≥ 5.3
To install just, follow the instruction here.
sudo apt-get install \ pkg-config \ libsystemd-dev \ build-essential \ libelf-dev \ libseccomp-dev \ libclang-dev \ libssl-devsudo dnf install \ pkg-config \ systemd-devel \ elfutils-libelf-devel \ libseccomp-devel \ clang-devel \ openssl-develgit clone git@github.com:youki-dev/youki.git
cd youki
just youki-dev # or youki-release
./youki -h # you can get information about youki command- Docker(See here)
Let's try to run a container that executes sleep 30 with youki. This tutorial may need root permission.
git clone git@github.com:youki-dev/youki.git
cd youki
just youki-dev # or youki-release
mkdir -p tutorial/rootfs
cd tutorial
# use docker to export busybox into the rootfs directory
docker export$(docker create busybox)| tar -C rootfs -xvf -Then, we need to prepare a configuration file. This file contains metadata and specs for a container, such as the process to run, environment variables to inject, sandboxing features to use, etc.
../youki spec # will generate a spec file named config.jsonWe can edit the config.json to add customized behaviors for container. Here, we modify the process field to run sleep 30.
"process": {
..."args": [
"sleep", "30"
],
...
}Then we can explore the lifecycle of a container:
cd .. # go back to the repository root
sudo ./youki create -b tutorial tutorial_container # create a container with name `tutorial_container`
sudo ./youki state tutorial_container # you can see the state the container is `created`
sudo ./youki start tutorial_container # start the container
sudo ./youki list # will show the list of containers, the container is `running`
sudo ./youki delete tutorial_container # delete the containerChange the command to be executed in config.json and try something other than sleep 30.
youki provides the ability to run containers as non-root user(rootless mode). To run a container in rootless mode, we need to add some extra options in config.json, other steps are same with above:
mkdir -p tutorial/rootfs
cd tutorial
# use docker to export busybox into the rootfs directory
docker export$(docker create busybox)| tar -C rootfs -xvf -
../youki spec --rootless # will generate a spec file named config.json with rootless mode## Modify the `args` field as you like
../youki run rootless-container # will create and run a container with rootless modeStart the docker daemon.
dockerd --experimental --add-runtime="youki=$(pwd)/youki"If you get an error like the below, that means your normal Docker daemon is running, and it needs to be stopped. Do that with your init system (i.e., with systemd, run sudo systemctl stop docker, as root if necessary).
failed to start daemon: pid file found, ensure docker is not running or delete /var/run/docker.pidNow repeat the command, which should start the docker daemon.
You can use youki in a different terminal to start the container.
docker run -it --rm --runtime youki busyboxAfterwards, you can close the docker daemon process in other the other terminal. To restart normal docker daemon (if you had stopped it before), run:
sudo systemctl start dockerGo and node-tap are required to run integration tests. See the opencontainers/runtime-tools README for details.
git submodule update --init --recursive
just test-ociYou can try youki on platforms other than Linux by using the Vagrantfile we have prepared. We have prepared two environments for vagrant, namely rootless mode and rootful mode
git clone git@github.com:youki-dev/youki.git
cd youki
# If you want to develop in rootless mode, and this is the default mode
vagrant up default
vagrant ssh default
# or if you want to develop in rootful mode
vagrant up rootful
vagrant ssh rootful
# in virtual machinecd youki
just youki-dev # or youki-releasePlease refer to our community page.
Thanks to all the people who already contributed!
We are a Cloud Native Computing Foundation sandbox project.
The Linux Foundation® (TLF) has registered trademarks and uses trademarks. For a list of TLF trademarks, see Trademark Usage.
Copyright Contributors to youki, established as youki a Series of LF Projects, LLC.
