search

containers / youki

A container runtime written in Rust
https://containers.github.io/youki/
Apache License 2.0
5.99k stars 332 forks source link
containers docker kubernetes oci rust

readme

youki: A container runtime in Rust

Discord GitHub contributors Github CI codecov

youki is an implementation of the OCI runtime-spec in Rust, similar to runc.
Your ideas are welcome here.

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

🚀 Quick Start

[!TIP] You can immediately set up your environment with youki on GitHub Codespaces and try it out.

Open in GitHub Codespaces

$ just build
$ docker run --runtime youki hello-world
$ sudo podman run --cgroup-manager=cgroupfs --runtime /workspaces/youki/youki hello-world

User Documentation

🎯 Motivation

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

📍 Status of youki

youki has aced real-world use cases, including containerd's e2e test, and is now adopted by several production environments. We have our roadmap.

youki demo

🔗 Related project

🎨 Design and implementation of youki

The User and Developer Documentation for youki is hosted at https://containers.github.io/youki/

Architecture

🎬 Getting Started

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.

Requires

Dependencies

To install just, follow the instruction here.

Debian, Ubuntu and related distributions

$ sudo apt-get install    \
      pkg-config          \
      libsystemd-dev      \
      build-essential     \
      libelf-dev          \
      libseccomp-dev      \
      libclang-dev        \
      glibc-static        \
      libssl-dev

Fedora, CentOS, RHEL and related distributions

$ sudo dnf install          \
      pkg-config            \
      systemd-devel         \
      elfutils-libelf-devel \
      libseccomp-devel      \
      clang-devel           \
      openssl-devel

Build

git clone git@github.com:containers/youki.git
cd youki
just youki-dev # or youki-release
./youki -h # you can get information about youki command

Tutorial

Requires

Create and run a container

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

Rootless container

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 mode

Usage

Start 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 systemctl stop docker, as root if necessary).

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

Now 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 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 Tests

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

git submodule update --init --recursive
just test-oci

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
just youki-dev # or youki-release

👥 Community and Contributing

Please refer to our community page.

Thanks to all the people who already contributed!