Container runtime written in Rust
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
utam0k 884428a044
Merge pull request #330 from yihuaf/yihuaf/307
4 hours ago
.cargo first commit! 6 months ago
.github Fix Changes Job in CI 1 week ago
cgroups Add various refactorings (#341) 6 hours ago
docs Improve readme and docs (#335) 2 days ago
hack add rootful mode for vagrant 5 days ago
integration_test/src/github.com/opencontainers extract the integration tests writen in the ci file as a script file. 4 months ago
seccomp make clippy happy 2 weeks ago
src minor refactor 6 hours ago
test_framework Add various refactorings (#341) 6 hours ago
youki_integration_test Add resolution of runtime path using `which` crate 1 week ago
.codecov.yml add codecov 1 month ago
.gitignore tweak readme tutorial 1 month ago
.gitmodules add the tutorial on using youki. 4 months ago
CODE-OF-CONDUCT.md Add CODE-OF-CONDUCT.md and SECURITY.md 4 months ago
Cargo.lock Updated cgroups oci-spec-rs to 0.5.1 or later (#303) 1 day ago
Cargo.toml Updated cgroups oci-spec-rs to 0.5.1 or later (#303) 1 day ago
LICENSE Change the license from MIT to Apache 2.0 2 months ago
README.md add to README that all runtime_tools tests have been covered. (#336) 1 day ago
SECURITY.md Add CODE-OF-CONDUCT.md and SECURITY.md 4 months ago
Vagrantfile fix build error in vagrant 5 days ago
Vagrantfile.root add rootful mode for vagrant 5 days ago
build.sh remove the cargo-when dependency. 3 months ago
integration_test.sh Adds an explaination that runc also fails the test 3 days ago

README.md

youki: A container runtime in Rust

Discord GitHub commit activity GitHub contributors Github CI codecov

youki is an implementation of the OCI runtime-spec in Rust, similar to runc.

About the name

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'.

Motivation

Here is why we are writing a new container runtime in Rust.

  • Rust is one of the best languages to implement oci-runtime. Many container tools are written in Go. It's all very nice products. However, the container runtime requires the use of system calls, which requires a bit of special handling when implemented in Go. This is too tricky(e.g. namespaces(7), fork(2)); with Rust, it's not that tricky and you can use system calls. Also, unlike C, Rust provides the benefit of memory management. Rust is not yet a major player in the container field, and Rust has the potential to contribute more to this field. I hope to be one of the examples of how Rust can be used in this field.
  • youki has the potential to be faster and use less memory than runc. This means that it can work in environments with tight memory usage. I don't have any benchmarks, etc., as it is not yet fully operational, but I expect that it will probably perform better when implemented in Rust. In fact, crun, a container runtime implemented in C, is quite high performance. For example, it may be possible to experiment with asynchronous processing using async/await in some parts.
  • The development of railcar has been suspended. This project was very nice but is no longer being developed. This project is inspired by it.
  • I have fun implementing this. In fact, this may be the most important.

Related project

Status of youki

youki is not at the practical stage yet. However, it is getting closer to practical use, running with docker and passing all the default tests provided by opencontainers/runtime-tools. youki demo

Feature Description State
Docker Running via Docker
Podman Running via Podman It works, but cgroups isn't supported. WIP on #24
pivot_root Change the root directory
Mounts Mount files and directories to container
Namespaces Isolation of various resources
Capabilities Limiting root privileges
Cgroups v1 Resource limitations, etc
Cgroups v2 Improved version of v1 Support is complete except for devices. WIP on #78
Seccomp Filtering system calls
Hooks Add custom processing during container creation
Rootless Running a container without root privileges It works, but cgroups isn't supported. WIP on #77
OCI Compliance Compliance with OCI Runtime Spec 50 out of 50 test cases passing

Design and implementation of youki

sequence diagram of youki

More details are in the works #14

Getting Started

Local build is only supported on linux. For other platforms, please use Vagrantfile that we prepared.

Requires

Dependencies

$ sudo apt-get install   \
      pkg-config         \
      libsystemd-dev     \
      libdbus-glib-1-dev \
      build-essential    \
      libelf-dev \
      libseccomp-dev
$ sudo dnf install   \
      pkg-config     \
      systemd-devel  \
      dbus-devel     \
      elfutils-libelf-devel \
      libseccomp-devel

Build

$ git clone git@github.com:containers/youki.git
$ cd youki
$ ./build.sh
$ ./youki -h # you can get information about youki command

Tutorial

Let's try to run a container that executes sleep 30 with youki. This tutorial may need root permission.

$ git clone git@github.com:containers/youki.git
$ cd youki
$ ./build.sh

$ 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.json

We 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 container

Change the command to be executed in config.json and try something other than sleep 30.

Usage

Starting the docker daemon.

$ dockerd --experimental --add-runtime="youki=$(pwd)/target/x86_64-unknown-linux-gnu/debug/youki"

In case you get an error like :

failed to start daemon: pid file found, ensure docker is not running or delete /var/run/docker.pid

That means your normal Docker daemon is running, and it needs to be stopped. For that, open a new shell in same directory and run :

$ systemctl stop docker # might need root permission

Now in the same shell run the first 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 busybox

Afterwards, you can close the docker daemon process in other the other terminal. To restart normal docker daemon (if you had stopped it before), run :

$ systemctl start docker # might need root permission

Integration test

Go and node-tap are required to run integration test. See the opencontainers/runtime-tools README for details.

$ git submodule update --init --recursive
$ ./integration_test.sh
# run specific test_cases with pattern
$ ./integration_test.sh linux_*

Setting up Vagrant

You 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:containers/youki.git
$ cd youki

# If you want to develop in rootless mode, and this is the default mode
$ vagrant up
$ vagrant ssh

# or if you want to develop in rootful mode
$ VAGRANT_VAGRANTFILE=Vagrantfile.root vagrant up
$ VAGRANT_VAGRANTFILE=Vagrantfile.root vagrant ssh

# in virtual machine
$ cd youki
$ ./build.sh

Community

We also have an active Discord if you'd like to come and chat with us.

Contribution

This project welcomes your PR and issues. For example, refactoring, adding features, correcting English, etc. If you need any help, you can contact me on Twitter.

Thanks to all the people who already contributed!