2021-05-16 09:47:06 +02:00
# youki: A container runtime in Rust
2021-03-27 12:08:13 +01:00
2021-06-10 19:39:25 +02:00
[![Discord ](https://img.shields.io/discord/849943000770412575.svg?logo=discord )](https://discord.gg/zHnyXKSQFD)
[![GitHub commit activity ](https://img.shields.io/github/commit-activity/m/containers/youki )](https://github.com/containers/youki/graphs/commit-activity)
[![GitHub contributors ](https://img.shields.io/github/contributors/containers/youki )](https://github.com/containers/youki/graphs/contributors)
[![Github CI ](https://github.com/containers/youki/actions/workflows/main.yml/badge.svg?branch=main )](https://github.com/containers/youki/actions)
2021-06-09 13:54:36 +02:00
2021-06-06 11:52:27 +02:00
< p align = "center" >
< img src = "docs/youki.png" width = "230" height = "230" >
< / p >
2021-03-27 12:08:13 +01:00
youki is an implementation of [runtime-spec ](https://github.com/opencontainers/runtime-spec ) in Rust, referring to [runc ](https://github.com/opencontainers/runc ).
2021-05-22 10:47:21 +02:00
# About the name
youki is pronounced as /joʊki/ or yoh-key.
2021-05-22 10:20:22 +02:00
youki is named after a Japanese word 'youki', which means 'a container'. In Japanese language, youki also means 'cheerful', 'merry', or 'hilarious'.
2021-03-27 12:08:13 +01:00
2021-05-16 11:24:30 +02:00
# Motivation
2021-05-18 16:30:11 +02:00
Here is why I am rewriting 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 ](https://github.com/containers/crun#performance ), 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.
2021-05-16 11:24:30 +02:00
- The development of [railcar ](https://github.com/oracle/railcar ) has been suspended. This project was very nice but is no longer being developed. This project is inspired by it.
2021-05-18 16:30:11 +02:00
- I have fun implementing this. In fact, this may be the most important.
2021-05-16 11:24:30 +02:00
2021-05-16 12:38:33 +02:00
# Status of youki
2021-05-18 16:30:11 +02:00
2021-05-24 22:56:05 +02:00
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 ](https://github.com/opencontainers/runtime-tools ).
2021-05-16 12:38:33 +02:00
![youki demo ](docs/demo.gif )
2021-03-29 17:23:45 +02:00
2021-06-22 14:52:39 +02:00
## Features
- [x] run with docker
- [ ] run with podman(WIP on [#24 ](https://github.com/containers/youki/issues/24 ))
- [x] pivot root
- [x] mount devices
- [x] namespaces
- [x] capabilities
- [x] rlimits
- [ ] cgroups v1(WIP on [#9 ](https://github.com/containers/youki/issues/9 ))
- [ ] cgroups v2(WIP on [#78 ](https://github.com/containers/youki/issues/78 ))
- [ ] seccomp(WIP on [#25 ](https://github.com/containers/youki/issues/25 ))
- [ ] hooks(WIP on [#13 ](https://github.com/containers/youki/issues/13 ))
- [ ] rootless(WIP on [#77 ](https://github.com/containers/youki/issues/77 ))
2021-05-16 12:38:33 +02:00
# Getting Started
2021-05-18 16:30:11 +02:00
2021-05-16 12:38:33 +02:00
Local build is only supported on linux.
2021-06-19 10:43:56 +02:00
For other platforms, please use [Vagrantfile ](#setting-up-vagrant ) that we prepared.
2021-05-18 16:30:11 +02:00
2021-05-16 12:38:33 +02:00
## Requires
2021-05-18 16:30:11 +02:00
2021-03-29 17:23:45 +02:00
- Rust(See [here ](https://www.rust-lang.org/tools/install ))
2021-06-06 10:01:35 +02:00
- Docker(See [here ](https://docs.docker.com/engine/install ))
2021-03-29 17:23:45 +02:00
2021-06-06 05:50:18 +02:00
## Dependencies
2021-06-22 14:52:39 +02:00
2021-06-06 05:50:18 +02:00
### Debian, Ubuntu and related distributions
2021-06-22 14:52:39 +02:00
2021-06-06 05:50:18 +02:00
```sh
2021-06-26 15:36:15 +02:00
$ sudo apt-get install \
2021-06-06 05:50:18 +02:00
pkg-config \
libsystemd-dev \
libdbus-glib-1-dev
```
### Fedora, Centos, RHEL and related distributions
2021-06-22 14:52:39 +02:00
2021-06-06 10:01:35 +02:00
```sh
2021-06-23 12:46:38 +02:00
$ sudo dnf install \
pkg-config \
systemd-devel \
2021-06-06 05:50:18 +02:00
dbus-devel
2021-06-06 10:01:35 +02:00
```
2021-06-09 13:54:36 +02:00
2021-06-06 05:50:18 +02:00
## Build
2021-06-09 13:54:36 +02:00
2021-03-29 17:23:45 +02:00
```sh
2021-06-04 13:22:05 +02:00
$ git clone git@github.com:containers/youki.git
2021-05-16 12:38:33 +02:00
$ cd youki
2021-05-30 11:30:40 +02:00
$ ./build.sh
2021-06-02 16:39:02 +02:00
$ ./youki -h # you can get information about youki command
2021-05-30 11:30:40 +02:00
```
## Tutorial
2021-06-09 13:54:36 +02:00
2021-05-30 11:30:40 +02:00
Let's try to run a container that executes `sleep 5` using youki.
Maybe this tutorial is need permission as root.
```sh
2021-06-04 13:22:05 +02:00
$ git clone git@github.com:containers/youki.git
2021-05-30 11:30:40 +02:00
$ cd youki
$ ./build.sh
$ mkdir tutorial
$ cd tutorial
$ mkdir rootfs
$ docker export $(docker create busybox) | tar -C rootfs -xvf -
2021-06-03 15:39:31 +02:00
```
Prepare a configuration file for the container that will run `sleep 5` .
```sh
2021-05-30 11:30:40 +02:00
$ curl https://gist.githubusercontent.com/utam0k/8ab419996633066eaf53ac9c66d962e7/raw/e81548f591f26ec03d85ce38b0443144573b4cf6/config.json -o config.json
$ cd ../
$ ./youki create -b tutorial tutorial_container
2021-06-02 16:39:02 +02:00
$ ./youki state tutorial_container # You can see the state the container is in as it is being generate.
2021-05-30 11:30:40 +02:00
$ ./youki start tutorial_container
2021-06-02 16:39:02 +02:00
$ ./youki state tutorial_container # Run it within 5 seconds to see the running container.
$ ./youki delete tutorial_container # Run it after the container is finished running.
2021-03-29 17:23:45 +02:00
```
2021-05-30 12:36:38 +02:00
Change the command to be executed in config.json and try something other than `sleep 5` .
2021-05-16 12:38:33 +02:00
## Usage
2021-05-18 16:30:11 +02:00
2021-05-16 12:38:33 +02:00
Starting the docker daemon.
2021-05-18 16:30:11 +02:00
2021-03-28 12:31:01 +02:00
```
2021-05-16 12:38:33 +02:00
$ dockerd --experimental --add-runtime="youki=$(pwd)/target/x86_64-unknown-linux-gnu/debug/youki"
2021-03-27 12:08:13 +01:00
```
2021-05-16 12:38:33 +02:00
You can use youki in a different terminal to start the container.
2021-05-18 16:30:11 +02:00
2021-03-27 12:08:13 +01:00
```
2021-05-16 12:38:33 +02:00
$ docker run -it --rm --runtime youki busybox
2021-03-27 12:08:13 +01:00
```
2021-05-16 12:38:33 +02:00
### Integration test
2021-05-18 16:30:11 +02:00
2021-06-13 16:18:17 +02:00
Go and node-tap are required to run integration test. See the [opencontainers/runtime-tools ](https://github.com/opencontainers/runtime-tools ) README for details.
2021-05-27 14:24:11 +02:00
```
$ git submodule update --init --recursive
$ ./integration_test.sh
```
2021-03-27 12:08:13 +01:00
2021-06-19 10:43:56 +02:00
### Setting up Vagrant
You can try youki on platforms other than linux by using the Vagrantfile we have prepared.
```
$ git clone git@github.com:containers/youki.git
$ cd youki
$ vagrant up
$ vagrant ssh
# in virtual machine
$ cd youki # in virtual machine
$ ./build.sh
```
2021-06-03 12:28:31 +02:00
# Community
2021-06-09 13:54:36 +02:00
2021-06-03 12:28:31 +02:00
We also have an active [Discord ](https://discord.gg/h7R3HgWUct ) if you'd like to come and chat with us.
2021-05-16 12:38:33 +02:00
# Design and implementation of youki
2021-05-18 16:30:11 +02:00
2021-06-04 13:22:05 +02:00
TBD(WIP on [#14 ](https://github.com/containers/youki/issues/14 ))
2021-03-27 12:08:13 +01:00
2021-03-29 17:23:45 +02:00
# Contribution
2021-05-18 16:30:11 +02:00
2021-03-27 12:08:13 +01:00
This project welcomes your PR and issues.
For example, refactoring, adding features, correcting English, etc.
2021-03-28 14:14:12 +02:00
If you need any help, you can contact me on [Twitter ](https://twitter.com/utam0k ).
2021-05-30 12:36:38 +02:00
Thanks to all the people who already contributed!
2021-06-04 13:22:05 +02:00
< a href = "https://github.com/containers/youki/graphs/contributors" >
< img src = "https://contributors-img.web.app/image?repo=containers/youki" / >
2021-06-02 16:39:02 +02:00
< / a >