Youki follows the CNCF Code of Conduct.
Youki is governed by Maintainers who are elected from active contributors. -Youki will remain vendor-nutral. +Youki will remain vendor-neutral. Maintainers are here.
Maintainers consist of the following roles:
diff --git a/developer/e2e/test_framework.html b/developer/e2e/test_framework.html index 81ee07459..620e1e06d 100644 --- a/developer/e2e/test_framework.html +++ b/developer/e2e/test_framework.html @@ -177,7 +177,7 @@Note that these tests resides in /tests/test_framework at the time of writing.
This crate contains the testing framework specifically developed for porting the OCI integration test to rust. This contains structs to represent the individual tests, group of tests and a test manager that has responsibility to run tests. This Also exposes traits which can be used to implement custom test structs or test group structs if needed.
By default the test groups are run in parallel using the crossbeam crate, and the default test_group implementation also runs individual tests parallelly.
-Sometimes you might need to run the tests in a test group serially or in certain order, for example in case of testing container lifecycle, a container must be created and started before stopping it. In such cases, you will need to implement the respective traits on your own structs, so that you can have fine control over thr running of tests. Check the readme of the test_framework crate to see the struct and trait documentation here.
+Sometimes you might need to run the tests in a test group serially or in certain order, for example in case of testing container lifecycle, a container must be created and started before stopping it. In such cases, you will need to implement the respective traits on your own structs, so that you can have fine control over the running of tests. Check the readme of the test_framework crate to see the struct and trait documentation here.
diff --git a/print.html b/print.html index 972bcd241..174254da6 100644 --- a/print.html +++ b/print.html @@ -735,7 +735,7 @@Youki is governed by Maintainers who are elected from active contributors. -Youki will remain vendor-nutral. +Youki will remain vendor-neutral. Maintainers are here.
Maintainers consist of the following roles:
@@ -1242,7 +1242,7 @@Sometimes you might need to run the tests in a test group serially or in certain order, for example in case of testing container lifecycle, a container must be created and started before stopping it. In such cases, you will need to implement the respective traits on your own structs, so that you can have fine control over thr running of tests. Check the readme of the test_framework crate to see the struct and trait documentation here.
+Sometimes you might need to run the tests in a test group serially or in certain order, for example in case of testing container lifecycle, a container must be created and started before stopping it. In such cases, you will need to implement the respective traits on your own structs, so that you can have fine control over the running of tests. Check the readme of the test_framework crate to see the struct and trait documentation here.
Note that these tests resides in /tests/runtimetest at the time of writing.
This crate provides a binary which is used by integration tests to verify that the restrictions and constraints applied to the container are upheld by the container process, from inside the container process. This runs the tests one-by-one, and the failing test prints the error to the stderr.
diff --git a/searchindex.js b/searchindex.js index 62ea34fb1..69f9b4419 100644 --- a/searchindex.js +++ b/searchindex.js @@ -1 +1 @@ -Object.assign(window.search, {"doc_urls":["youki.html#youki","youki.html#about-the-name","youki.html#motivation","user/introduction.html#user-documentation","user/basic_setup.html#basic-setup","user/basic_setup.html#build-requirements","user/basic_setup.html#build-with-cross-rs","user/basic_setup.html#build-without-cross-rs","user/basic_setup.html#runtime-requirements","user/basic_setup.html#running-youki","user/basic_setup.html#quick-install","user/basic_setup.html#getting-the-source","user/basic_setup.html#installing-the-source","user/basic_setup.html#using-sub-crates-as-dependency","user/basic_setup.html#using-vagrant-to-run-youki-on-non-linux-platform","user/basic_usage.html#basic-usage","user/crates.html#crates-provided","user/libcgroups.html#libcgroups","user/libcgroups.html#common","user/libcgroups.html#stats","user/libcgroups.html#systemd","user/libcgroups.html#test_manager","user/libcgroups.html#v1-and-v2","user/libcontainer.html#libcontainer","user/liboci_cli.html#liboci-cli","user/liboci_cli.html#implemented-subcommands","user/libseccomp.html#libseccomp","user/webassembly.html#webassembly","user/webassembly.html#build-youki-with-wasm-wasmedge-wasm-wasmer-or-wasm-wasmtime-feature-flag-enabled","user/webassembly.html#build-a-container-image-with-the-webassembly-module","user/webassembly.html#compile-a-sample-wasm-module","user/webassembly.html#build-a-container-image-with-the-module","user/webassembly.html#run-the-wasm-module-with-youki-and-podman","community/introduction.html#community","community/maintainer.html#current-maintainers","community/governance.html#code-of-conduct","community/governance.html#maintainership","community/governance.html#roles","community/governance.html#addition-and-promotion-of-maintainers","community/governance.html#removal-and-demotion-of-maintainers","community/contributing.html#contributing","community/contributing.html#developer-certificate-of-origin","community/contributing.html#licensing","community/contributing.html#sending-pull-requests","community/contributing.html#merging-pull-requests","developer/introduction.html#developer-documentation","developer/basics.html#basics","developer/basics.html#youki","developer/basics.html#testing-while-developing","developer/basics.html#resources","developer/unwritten_rules.html#unwritten-rule","developer/unwritten_rules.html#conventions-to-follow","developer/good_places_to_start.html#good-places-to-start","developer/documentation_mdbook.html#this-documentation","developer/repo_structure.html#repository-structure","developer/repo_structure.html#github","developer/repo_structure.html#crates","developer/repo_structure.html#docs","developer/repo_structure.html#hack","developer/repo_structure.html#scripts","developer/repo_structure.html#tests","developer/debugging.html#debugging","developer/debugging.html#bpftrace","developer/crate_specific_information.html#crate-specific-information","developer/libcgroups.html#libcgroups","developer/libcgroups.html#dbus-native","developer/libcontainer.html#libcontainer","developer/libcontainer.html#notes","developer/liboci_cli.html#liboci-cli","developer/libseccomp.html#libseccomp","developer/youki.html#youki","developer/youki.html#notes","developer/e2e/e2e_tests.html#e2e-tests","developer/e2e/rust_oci_test.html#contest","developer/e2e/rust_oci_test.html#how-to-run","developer/e2e/rust_oci_test.html#how-to-write","developer/e2e/integration_test.html#integration_test","developer/e2e/integration_test.html#notes","developer/e2e/integration_test.html#about-the-create-container-function","developer/e2e/integration_test.html#how-test-inside-container-works","developer/e2e/test_framework.html#test_framework","developer/e2e/runtimetest.html#runtime-test","developer/e2e/runtimetest.html#notes","developer/e2e/containerd_integration_test_using_youki.html#containerd-integration-test-using-youki","developer/e2e/containerd_integration_test_using_youki.html#local","developer/e2e/runtime_tools.html#runtime-tools","developer/e2e/runtime_tools.html#local"],"index":{"documentStore":{"docInfo":{"0":{"body":8,"breadcrumbs":2,"title":1},"1":{"body":19,"breadcrumbs":2,"title":1},"10":{"body":15,"breadcrumbs":6,"title":2},"11":{"body":45,"breadcrumbs":6,"title":2},"12":{"body":27,"breadcrumbs":6,"title":2},"13":{"body":26,"breadcrumbs":8,"title":4},"14":{"body":64,"breadcrumbs":11,"title":7},"15":{"body":618,"breadcrumbs":6,"title":2},"16":{"body":68,"breadcrumbs":6,"title":2},"17":{"body":34,"breadcrumbs":6,"title":1},"18":{"body":100,"breadcrumbs":6,"title":1},"19":{"body":127,"breadcrumbs":6,"title":1},"2":{"body":298,"breadcrumbs":2,"title":1},"20":{"body":66,"breadcrumbs":6,"title":1},"21":{"body":10,"breadcrumbs":6,"title":1},"22":{"body":59,"breadcrumbs":7,"title":2},"23":{"body":233,"breadcrumbs":6,"title":1},"24":{"body":25,"breadcrumbs":8,"title":2},"25":{"body":24,"breadcrumbs":8,"title":2},"26":{"body":26,"breadcrumbs":6,"title":1},"27":{"body":22,"breadcrumbs":4,"title":1},"28":{"body":36,"breadcrumbs":14,"title":11},"29":{"body":48,"breadcrumbs":8,"title":5},"3":{"body":72,"breadcrumbs":4,"title":2},"30":{"body":42,"breadcrumbs":7,"title":4},"31":{"body":26,"breadcrumbs":7,"title":4},"32":{"body":19,"breadcrumbs":8,"title":5},"33":{"body":3,"breadcrumbs":2,"title":1},"34":{"body":27,"breadcrumbs":4,"title":2},"35":{"body":5,"breadcrumbs":4,"title":2},"36":{"body":12,"breadcrumbs":3,"title":1},"37":{"body":54,"breadcrumbs":3,"title":1},"38":{"body":57,"breadcrumbs":5,"title":3},"39":{"body":72,"breadcrumbs":5,"title":3},"4":{"body":73,"breadcrumbs":6,"title":2},"40":{"body":0,"breadcrumbs":3,"title":1},"41":{"body":15,"breadcrumbs":5,"title":3},"42":{"body":7,"breadcrumbs":3,"title":1},"43":{"body":7,"breadcrumbs":5,"title":3},"44":{"body":13,"breadcrumbs":5,"title":3},"45":{"body":83,"breadcrumbs":4,"title":2},"46":{"body":22,"breadcrumbs":4,"title":1},"47":{"body":63,"breadcrumbs":4,"title":1},"48":{"body":93,"breadcrumbs":5,"title":2},"49":{"body":112,"breadcrumbs":4,"title":1},"5":{"body":27,"breadcrumbs":6,"title":2},"50":{"body":25,"breadcrumbs":6,"title":2},"51":{"body":171,"breadcrumbs":6,"title":2},"52":{"body":189,"breadcrumbs":8,"title":3},"53":{"body":159,"breadcrumbs":4,"title":1},"54":{"body":27,"breadcrumbs":6,"title":2},"55":{"body":6,"breadcrumbs":5,"title":1},"56":{"body":11,"breadcrumbs":5,"title":1},"57":{"body":16,"breadcrumbs":5,"title":1},"58":{"body":15,"breadcrumbs":5,"title":1},"59":{"body":25,"breadcrumbs":5,"title":1},"6":{"body":44,"breadcrumbs":7,"title":3},"60":{"body":21,"breadcrumbs":5,"title":1},"61":{"body":33,"breadcrumbs":4,"title":1},"62":{"body":271,"breadcrumbs":4,"title":1},"63":{"body":28,"breadcrumbs":8,"title":3},"64":{"body":290,"breadcrumbs":7,"title":1},"65":{"body":67,"breadcrumbs":8,"title":2},"66":{"body":118,"breadcrumbs":7,"title":1},"67":{"body":282,"breadcrumbs":7,"title":1},"68":{"body":57,"breadcrumbs":9,"title":2},"69":{"body":67,"breadcrumbs":7,"title":1},"7":{"body":57,"breadcrumbs":8,"title":4},"70":{"body":213,"breadcrumbs":7,"title":1},"71":{"body":64,"breadcrumbs":7,"title":1},"72":{"body":39,"breadcrumbs":6,"title":2},"73":{"body":10,"breadcrumbs":8,"title":1},"74":{"body":2,"breadcrumbs":8,"title":1},"75":{"body":211,"breadcrumbs":8,"title":1},"76":{"body":137,"breadcrumbs":9,"title":1},"77":{"body":0,"breadcrumbs":9,"title":1},"78":{"body":158,"breadcrumbs":11,"title":3},"79":{"body":53,"breadcrumbs":12,"title":4},"8":{"body":34,"breadcrumbs":6,"title":2},"80":{"body":96,"breadcrumbs":9,"title":1},"81":{"body":32,"breadcrumbs":10,"title":2},"82":{"body":252,"breadcrumbs":9,"title":1},"83":{"body":0,"breadcrumbs":12,"title":5},"84":{"body":2,"breadcrumbs":8,"title":1},"85":{"body":0,"breadcrumbs":8,"title":2},"86":{"body":7,"breadcrumbs":7,"title":1},"9":{"body":42,"breadcrumbs":6,"title":2}},"docs":{"0":{"body":"youki is an implementation of the OCI runtime-spec in Rust, similar to runc .","breadcrumbs":"Youki » Youki","id":"0","title":"Youki"},"1":{"body":"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'.","breadcrumbs":"Youki » About the name","id":"1","title":"About the name"},"10":{"body":"Install from the GitHub release as root: # curl -sSfL https://github.com/containers/youki/releases/download/v0.3.3/youki-0.3.3-$(uname -m)-musl.tar.gz | tar -xzvC /usr/bin/ youki","breadcrumbs":"User Documentation » Basic Setup » Quick install","id":"10","title":"Quick install"},"11":{"body":"Currently Youki can only be installed from the source code itself, so you will need to clone the Youki GitHub repository to get the source code for using it as a runtime. If you are using any crates of Youki as dependency you need to do this step, as Cargo will automatically clone the repository for you. To clone the repository, run $ git clone https://github.com/containers/youki.git This will create a directory named youki in the directory you ran the command in. This youki directory will be referred to as root directory throughout the documentation.","breadcrumbs":"User Documentation » Basic Setup » Getting the source","id":"11","title":"Getting the source"},"12":{"body":"Once you have cloned the source, you can build it with just : # go into the cloned directory\n$ cd youki\n$ just youki-dev # or youki-release\n$ ./youki -h # get information about youki command This will build the Youki binary, and put it at the root level of the cloned directory, that is in the youki/ .","breadcrumbs":"User Documentation » Basic Setup » Installing the source","id":"12","title":"Installing the source"},"13":{"body":"To use any of the sub-crate as a dependency in your own project, you can specify the dependency as follows, [dependencies]\n...\nliboci-cli = { git = \"https://github.com/containers/Youki.git\" }\n... Here we use liboci-cli as an example, which can be replaced by the sub-crate that you need. Then you can use it in your source as use liboci_cli::{...}","breadcrumbs":"User Documentation » Basic Setup » Using sub-crates as dependency","id":"13","title":"Using sub-crates as dependency"},"14":{"body":"As explained before, Youki only support Linux, and to build/use it on non-Linux Platforms, you will need to use some kind of virtualization. The repo provides a Vagrantfile to do the required VM setup using Vagrant, which can be installed from here . Once installed and setup, you can run vagrant commands in the cloned directory to run Youki inside the VM created by vagrant : # in the youki directory # for rootless mode, which is default\n$ vagrant up\n$ vagrant ssh # or if you want to develop in rootful mode\n$ VAGRANT_VAGRANTFILE=Vagrantfile.root vagrant up\n$ VAGRANT_VAGRANTFILE=Vagrantfile.root vagrant ssh # in virtual machine\n$ cd youki\n$ just youki-dev # or youki-release","breadcrumbs":"User Documentation » Basic Setup » Using Vagrant to run Youki on non-Linux Platform","id":"14","title":"Using Vagrant to run Youki on non-Linux Platform"},"15":{"body":"This explains using Youki as a low-level container runtime. Youki can be used by itself to create, start and run containers, but doing so can be tedious, and thus you might want to use a higher-level runtime with Youki set as its runtime, so that you can get a convenient and easy interface. You can use Youki with Docker, or Podman, but for the purpose of the examples, we will illustrate using Docker. Youki can run in two modes, namely rootful mode, and rootless mode. The primary difference from the user-perspective in these is that as the name suggests, rootless mode does not require root/admin permissions, while rootful mode needs the root permissions. Both of these are shown in the examples below. Using youki with a high-level runtime We will first see how to use Youki with a high-level runtime such as Docker. You can install Docker from here . By default, after installation the docker sets up so that its daemon process will start running in background after booting up. By default, this configures Docker to use its default low-level runtime, and to use Youki instead , we will first need to stop the running Docker daemon. As Youki needs systemd to compile, this assumes that you are running on a systemd based system. So you an first check if the docker daemon is running or not by running systemctl status docker This will print a message showing if the daemon is active or not. If it is active, then you will need to stop it by running sudo systemctl stop docker After this you need to manually restart the docker daemon, but with Youki as its runtime. To do this, run following command in the youki/ directory after building youki dockerd --experimental --add-runtime=\"youki=$(pwd)/youki\" # run in the youki/scripts directory This will start the daemon and hang up the console. You can either start this as a background process to continue using the same terminal, or use another terminal, which will make it easier to stop the docker daemon later. In case you don't stop the original daemon, you can get an error message after previous command failed to start daemon: pid file found, ensure docker is not running or delete /var/run/docker.pid Now that the docker daemon is running, you can use docker normally as you will, but you will be able to specify Youki as its low-level runtime to actually create, start and stop the containers. You can try running a container such as docker run -it --rm --runtime youki busybox # run a container This will start a busybox container, and give access to terminal inside it. After you are done, you can stop the docker daemon by sending it a signal, either by using Ctrl + C if you are running the process in another terminal, or by using kill command with the pid of it, if you have started it as a background process. Then to start the original/normal Docker daemon, you can run sudo systemctl start docker Let docker permanently know youki as a runtime With newer versions of docker, you can update file /etc/docker/daemon.json to let docker know youki ( source ). You may need to create this file, if it does not yet exist. A sample content of it: { \"default-runtime\": \"runc\", \"runtimes\": { \"youki\": { \"path\": \"/path/to/youki/youki\", \"runtimeArgs\": [ \"--debug\", \"--systemd-log\" ] } }\n} After this (need to restart docker at the first time), you can use youki with docker: docker run --runtime youki .... You can verify the runtime includes youki: $ docker info|grep -i runtime Runtimes: youki runc Default Runtime: runc Using Youki Standalone Youki can also be used directly, without a higher-level runtime such as Docker to create, start, stop and delete the container, but the process can be tedious. Here we will show how you can do that, to run a simple container with desired program running in it. Note that we will still be using Docker to generate the rootfs required for running the container. To start, in the youki/scripts directory, make another directory named tutorial, and create a sub-directory rootfs inside it mkdir -p tutorial/rootfs After that, you will need to use docker to create the required directory structure cd tutorial\ndocker export $(docker create busybox) | tar -C rootfs -xvf - This will create the required directory structure for using it as a root directory inside the container. Now the any container runtime gets the information about the permissions, configurations and constraints for the container process by using a config.json file. Youki has a command which can generate the default config for you. To do this, run ../youki spec After this, you can manually edit the file to customize the behavior of the container process. For example, to run the desired program inside the container, you can edit the process.args \"process\": {\n...\n\"args\": [ \"sleep\", \"30\"\n],\n... } Here you can change the args to specify the program to be run, and arguments to be given to it. After this, go back to the youki/ directory cd .. As the setup is complete, you can now use youki to create the container, start the container, get its state etc. # create a container with name `tutorial_container`\nsudo ./youki create -b tutorial tutorial_container # you can see the state the container is `created`\nsudo ./youki state tutorial_container # start the container\nsudo ./youki start tutorial_container # will show the list of containers, the container is `running`\nsudo ./youki list # delete the container\nsudo ./youki delete tutorial_container The example above shows how to run Youki in a 'rootful' way. To run it without root permissions, that is, in rootless mode, few changes are required. First, after exporting the rootfs from docker, while generating the config, you will need to pass the rootless flag. This will generate the config withe the options needed for rootless operation of the container. ../youki spec --rootless After this, the steps are basically the same, except you do not need to use sudo while running youki. cd ..\n./youki create -b tutorial rootless_container\n./youki state rootless_container\n./youki start rootless_container\n./youki list\n./youki delete rootless_container Log level youki defaults the log level to error in the release build. In the debug build, the log level defaults to debug. The --log-level flag can be used to set the log-level. For least amount of log, we recommend using the error log level. For the most spammy logging, we have a trace level. For compatibility with runc and crun, we have a --debug flag to set the log level to debug. This flag is ignored if --log-level is also set.","breadcrumbs":"User Documentation » Basic Usage » Basic Usage","id":"15","title":"Basic Usage"},"16":{"body":"Youki repo itself is a Cargo workspace, comprising of several sub-crates, each one for some specific functionality. The youki binary depends on this to provide the low-level functionality, and you can use these crate as a dependency for your own projects as well. For more information on how to add a sub-crate as a dependency in your project, see Basic Usage . The subsection in this part briefly explains some of the crates, and some of the functionality they expose. This should be good enough to get a general idea of each crate. To get detailed information about the structs, functions and modules each crate exposes, unfortunately, for the time being, you will need to go through the source itself, but we are working on creating better docs.","breadcrumbs":"User Documentation » Crates provided » Crates provided","id":"16","title":"Crates provided"},"17":{"body":"libcgroups is the crate that contains functionality to work with Linux cgroups. This provide an easy to use interface over reading and writing cgroups files, as well as various structs that represent the cgroups data. The modules that it exposes are : common stats systemd test_manager v1 v2 Following is a short explanation of these modules.","breadcrumbs":"User Documentation » Crates provided » libcgroups » libcgroups","id":"17","title":"libcgroups"},"18":{"body":"This module contains functionality that is general to any type of cgroup. Some of the things it provides are: trait CgroupManager which gives and interface for the following: add a task to a cgroup apply resource restriction remove a cgroup control freezer cgroup state get stats from a cgroup get pids belonging to the cgroup functions write_cgroup_file_str and write_cgroup_file which write data to a cgroup file function read_cgroup_file which reads data from given cgroup file function get_cgroup_setup_with_root which returns setup of cgroups (v1,v2, hybrid) on the system with specified cgroup root path function get_cgroup_setup which returns setup of cgroups (v1,v2, hybrid) on the system with default cgroup root path /sys/fs/cgroup function create_cgroup_manager_with_root which returns corresponding cgroup manager on the system with specified cgroup root path, if the passed root_path argument is None, then it's same as function create_cgroup_manager function create_cgroup_manager which returns corresponding cgroup manager on the system with default cgroup root path /sys/fs/cgroup","breadcrumbs":"User Documentation » Crates provided » libcgroups » common","id":"18","title":"common"},"19":{"body":"This module has functionalities related to statistics data of the cgroups, and structs representing it. Some of the things it exposes are struct Stats which contains following structs: CpuStats : contains cpu usage and throttling information MemoryStats : contains usage of memory, swap and memory combined, kernel memory, kernel tcp memory and other memory stats PidStats : contains current number of active pids and allowed number of pids BlkioStats : contains block io related stats, such as number of bytes transferred from/to a device in cgroup, number of io operations done by a device in cgroup, device access and queue information etc. HugeTlbStats : containing stats for Huge TLB such as usage, max_usage, and fail count function supported_page_size which returns hugepage size supported by the system utility functions to operate with data in cgroups files such as: parse_single_value : reads file expecting it to have a single value, and returns the value parse_flat_keyed_data : parses cgroup file data which is in flat keyed format (key value) parse_nested_keyed_data : parses cgroup file data which is in nested keyed format (key list of values) parse_device_number : parses major and minor number of device","breadcrumbs":"User Documentation » Crates provided » libcgroups » stats","id":"19","title":"stats"},"2":{"body":"Here 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 too tricky (e.g. namespaces(7) , fork(2) ); with Rust, 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) youki 198.4 ms ± 52.1 ms 97.2 ms … 296.1 ms runc 352.3 ms ± 53.3 ms 248.3 ms … 772.2 ms crun 153.5 ms ± 21.6 ms 80.9 ms … 196.6 ms 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 console $ ./youki info Version 0.0.1 Kernel-Release 5.11.0-41-generic Kernel-Version #45-Ubuntu SMP Fri Nov 5 11:37:01 UTC 2021 Architecture x86_64 Operating System Ubuntu 21.04 Cores 12 Total Memory 32025 Cgroup setup hybrid Cgroup mounts blkio /sys/fs/cgroup/blkio cpu /sys/fs/cgroup/cpu,cpuacct cpuacct /sys/fs/cgroup/cpu,cpuacct cpuset /sys/fs/cgroup/cpuset devices /sys/fs/cgroup/devices freezer /sys/fs/cgroup/freezer hugetlb /sys/fs/cgroup/hugetlb memory /sys/fs/cgroup/memory net_cls /sys/fs/cgroup/net_cls,net_prio net_prio /sys/fs/cgroup/net_cls,net_prio perf_event /sys/fs/cgroup/perf_event pids /sys/fs/cgroup/pids unified /sys/fs/cgroup/unified CGroup v2 controllers cpu detached cpuset detached hugetlb detached io detached memory detached pids detached device attached Namespaces enabled mount enabled uts enabled ipc enabled user enabled pid enabled network enabled cgroup enabled $ ./youki --version youki version 0.0.1 commit: 0.0.1-0-0be33bf $ runc -v runc version 1.0.0-rc93 commit: 12644e614e25b05da6fd08a38ffa0cfe1903fdec spec: 1.0.2-dev go: go1.13.15 libseccomp: 2.5.1 $ crun --version crun version 0.19.1.45-4cc7 commit: 4cc7fa1124cce75dc26e12186d9cbeabded2b710 spec: 1.0.0 +SYSTEMD +SELINUX +APPARMOR +CAP +SECCOMP +EBPF +CRIU +YAJL 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.","breadcrumbs":"Youki » Motivation","id":"2","title":"Motivation"},"20":{"body":"This is the module used by youki to interact with systemd, and it exposes several functions to interact: function booted to check if the system was booted with systemd or not module controller_type, which contains enum ControllerType which is used to specify cgroup controllers available on a system module manager, which contains Manager struct, which is the cgroup manager, and contain information such as the root cgroups path, path for the specific cgroups, client to communicate with systemd etc. This also implements CgroupManager trait, and thus can be used for cgroups related operations. module dbus-native is the native implementation for dbus connection, which is used to interact with systemd in rootless mode.","breadcrumbs":"User Documentation » Crates provided » libcgroups » systemd","id":"20","title":"systemd"},"21":{"body":"This exposes a TestManager struct which can be used as dummy for cgroup testing purposes, which also implements CgroupManager.","breadcrumbs":"User Documentation » Crates provided » libcgroups » test_manager","id":"21","title":"test_manager"},"22":{"body":"These two modules contains functionalities specific to cgroups version 1 and version 2. Both of these expose respective cgroup managers, which can be used to manage that type of cgroup, as well as some utility functions related to respective cgroup version, such as get_mount_points (for v1 and v2), get_subsystem_mount points (for v1), and get_available_controllers (for v2) etc. The v2 module also exposes devices module, which provides functionality for working with bpf, such as load a bpf program, query info of a bpf program, attach and detach a bpf program to a cgroup, etc.","breadcrumbs":"User Documentation » Crates provided » libcgroups » v1 and v2","id":"22","title":"v1 and v2"},"23":{"body":"This crate provides functionality for creating and managing containers. Youki itself uses this crate to manage and control the containers. This exposes several modules, each dealing with a specific aspect of working with containers. apparmor : functions that deal with apparmor, which is a Linux Kernel security module to control program capabilities with per program profiles. capabilities : this has functions related to setting and resetting specific capabilities, as well as to drop extra privileges from container process. config : this exposes YoukiConfig struct, which contains a subset of the data in the config.json. This is the subset that is needed when starting or managing containers after creation, and rather than parsing and passing around whole config.json, the smaller YoukiConfig is passed, which is comparatively faster. container : This is the core of the container module, and contains sub-modules and structs that deal with the container lifecycle including creating, starting, stopping and deleting containers. hooks : exposes function run_hooks, which is used to run various container lifecycle hooks as specified in oci-spec. namespaces : exposes Namespaces struct, which deals with applying namespaces to a container process. notify_socket : this contains NotifyListener struct, which is used internally to communicate between the main youki process and the forked container processes. process : a module which exposes functions related to forking the process, setting up the namespaces and starting the container process with correct namespaces. rootfs : this contains modules which deal with rootfs, which is minimal filesystem that is provided to the container. user_ns : this deals with running containers in with new user namespace, usually rootless containers will use this, that is running containers without needing root permissions. seccomp : this deals with setting up seccomp for container process. It uses libseccomp crate in order to do that. signal : this provides simple wrappers for unix signal, so that parsing them from their names or signal numbers is easier. syscall : this provides a trait Syscall, which is used to abstract over several functionalities which need to call libc functions. This allows the other parts of library to use those functions without having to deal with implementation details. tty : this deals with setting up the tty for the container process. utils : provides various utility functions, such as parse_env to parse the env variables, get_cgroups_path, create_dir_all_with_mode etc.","breadcrumbs":"User Documentation » Crates provided » libcontainer » libcontainer","id":"23","title":"libcontainer"},"24":{"body":"This module provides the structs for command line arguments for OCI container runtimes as specified in the OCI Runtime Command Line Interface. The exposed structures derive clap::Parser, so that they can be directly used for parsing oci-commandline arguments.","breadcrumbs":"User Documentation » Crates provided » liboci-cli » liboci-cli","id":"24","title":"liboci-cli"},"25":{"body":"Command liboci-cli CLI Specification runc crun youki create ✅ ✅ ✅ ✅ ✅ start ✅ ✅ ✅ ✅ ✅ state ✅ ✅ ✅ ✅ ✅ kill ✅ ✅ ✅ ✅ ✅ delete ✅ ✅ ✅ ✅ ✅ checkpoint ✅ ✅ events ✅ ✅ ✅ exec ✅ ✅ ✅ ✅ list ✅ ✅ ✅ ✅ pause ✅ ✅ ✅ ✅ ps ✅ ✅ ✅ ✅ restore ✅ ✅ resume ✅ ✅ ✅ ✅ run ✅ ✅ ✅ ✅ spec ✅ ✅ ✅ ✅ update ✅ ✅","breadcrumbs":"User Documentation » Crates provided » liboci-cli » Implemented subcommands","id":"25","title":"Implemented subcommands"},"26":{"body":"This crate provides Rust FFI bindings to libseccomp . This is adapted from code generated using rust-bindgen from a C header file. This also manually fixes some of the issues that occur as rust-bindgen has some issues when dealing with C function macros.","breadcrumbs":"User Documentation » Crates provided » libseccomp » libseccomp","id":"26","title":"libseccomp"},"27":{"body":"There are 3 things you need to do to run a WebAssembly module with youki. Build youki with wasm-wasmer feature flag enabled Build a container image with the WebAssembly module Run the container with youki","breadcrumbs":"User Documentation » Webassembly » Webassembly","id":"27","title":"Webassembly"},"28":{"body":"Run build.sh with -f wasm-wasmedge option. ./scripts/build.sh -o . -r -f wasm-wasmedge Run build.sh with -f wasm-wasmer option. ./scripts/build.sh -o . -r -f wasm-wasmer Run build.sh with -f wasm-wasmtime option. ./scripts/build.sh -o . -r -f wasm-wasmtime","breadcrumbs":"User Documentation » Webassembly » Build youki with wasm-wasmedge, wasm-wasmer, or wasm-wasmtime feature flag enabled","id":"28","title":"Build youki with wasm-wasmedge, wasm-wasmer, or wasm-wasmtime feature flag enabled"},"29":{"body":"If you want to run a webassembly module with youki, your config.json has to include either runc.oci.handler or module.wasm.image/variant=compat\" . It also needs to specify a valid .wasm (webassembly binary) or .wat (webassembly test) module as entrypoint for the container. If a wat module is specified it will be compiled to a wasm module by youki before it is executed. The module also needs to be available in the root filesystem of the container obviously. \"ociVersion\": \"1.0.2-dev\",\n\"annotations\": { \"run.oci.handler\": \"wasm\"\n},\n\"process\": { \"args\": [ \"hello.wasm\", \"hello\", \"world\" ],\n...\n}\n...","breadcrumbs":"User Documentation » Webassembly » Build a container image with the WebAssembly module","id":"29","title":"Build a container image with the WebAssembly module"},"3":{"body":"This section provides documentation of youki and the sub crates that the youki repo contains for the users. So if you are using youki as a low level container runtime, or using any of the crates in youki workspace as dependencies for your own project, this section might be helpful for you. This is divided into following sub-sections : Basic Setup : This explains how the dependencies and setup required to compile and run youki Basic Usage : This explains using youki itself as a low-level container runtime, or using one of the crates as dependencies crates : This section provides brief explanation of the member crates of youki repo workspace libcgroups libcontainer liboci-cli libseccomp Webassembly : This explains how to use webassembly module with youki.","breadcrumbs":"User Documentation » User Documentation","id":"3","title":"User Documentation"},"30":{"body":"A simple wasm module can be created by running rustup target add wasm32-wasi\ncargo new wasm-module --bin\ncd ./wasm-module\nvi src/main.rs fn main() { println!(\"Printing args\"); for arg in std::env::args().skip(1) { println!(\"{}\", arg); } println!(\"Printing envs\"); for envs in std::env::vars() { println!(\"{:?}\", envs); } } Then compile the program to WASI. cargo build --target wasm32-wasi","breadcrumbs":"User Documentation » Webassembly » Compile a sample wasm module","id":"30","title":"Compile a sample wasm module"},"31":{"body":"Create a Dockerfile. vi Dockerfile FROM scratch\nCOPY target/wasm32-wasi/debug/wasm-module.wasm /\nENTRYPOINT [\"wasm-module.wasm\"] Then build a container image with module.wasm.image/variant=compat annotation. [1] sudo buildah build --annotation \"module.wasm.image/variant=compat\" -t wasm-module .","breadcrumbs":"User Documentation » Webassembly » Build a container image with the module","id":"31","title":"Build a container image with the module"},"32":{"body":"Run podman with youki as runtime. [1] sudo podman --runtime /PATH/WHARE/YOU/BUILT/WITH/WASM-WASMER/youki run localhost/wasm-module 1 2 3 You might need sudo because of #719 .","breadcrumbs":"User Documentation » Webassembly » Run the wasm module with youki and podman","id":"32","title":"Run the wasm module with youki and podman"},"33":{"body":"Maintainer Governance Contributing","breadcrumbs":"Community » Community","id":"33","title":"Community"},"34":{"body":"Name Role GitHub ID Toru Komatsu Committer @utam0k Thomas Schubart Committer @Furisto Yashodhan Committer @YJDoc2 Eric Fang Committer @yihuaf Sascha Grunert Committer @saschagrunert Jorge Prendes Committer @jprendes","breadcrumbs":"Community » Maintainer » Current Maintainers","id":"34","title":"Current Maintainers"},"35":{"body":"Youki follows the CNCF Code of Conduct .","breadcrumbs":"Community » Governance » Code of Conduct","id":"35","title":"Code of Conduct"},"36":{"body":"Youki is governed by Maintainers who are elected from active contributors. Youki will remain vendor-nutral . Maintainers are here .","breadcrumbs":"Community » Governance » Maintainership","id":"36","title":"Maintainership"},"37":{"body":"Maintainers consist of the following roles: Committer (Full maintainership) Committers have full write accesses to repos. Committers’ commits should still be made via GitHub pull requests (except for urgent security fixes), and should not be pushed directly to the default branch. Reviewer (Limited maintainership) Reviewers may moderate GitHub issues and pull requests (such as adding labels and cleaning up spams), but they do not have any access to merge pull requests nor push commits. A Reviewer is considered as a candidate to become a Committer.","breadcrumbs":"Community » Governance » Roles","id":"37","title":"Roles"},"38":{"body":"A contributor who have made significant contributions in quality and in quantity can be directly invited as a Committer. A proposal to add or promote a Maintainer must be approved by 2/3 of the Committers who vote within 7 days. Voting needs a minimum of 2 approvals. The proposer can vote too. Votes from the same company will be counted as one vote. A proposal should be made via a GitHub pull request to the file containing the list of Maintainer defined above. Before submitting the pull request, the proposer should reach out to the Committers to check their willingness to support the proposal.","breadcrumbs":"Community » Governance » Addition and promotion of Maintainers","id":"38","title":"Addition and promotion of Maintainers"},"39":{"body":"A Maintainer who do not show significant activities for 12 months, or, who violated the Code of Conduct, may be demoted or removed from the project. A proposal to demote or remove a Maintainer must be approved by 2/3 of the Committers (excluding the person in question) who vote within 14 days. Voting needs a minimum of 2 approvals. The proposer can vote too. Votes from the same company will be counted as one vote. A proposal should be made via a GitHub pull request to the file containing the list of Maintainer defined above. In the special case of removing a harmful Maintainer, this process can take place via a private discussion. Before submitting the pull request, the proposer should reach out to the Committers to check their willingness.","breadcrumbs":"Community » Governance » Removal and demotion of Maintainers","id":"39","title":"Removal and demotion of Maintainers"},"4":{"body":"This explains the requirements for compiling Youki as a binary, to use it as a low-level container runtime, or to depend once of its crates as dependency for your own project. Youki currently only supports Linux Platform, and to use it on other platform you will need to use some kind of virtualization. The repo itself provides Vagrantfile that provides basic setup to use Youki on non-Linux system using Vagrant. The last sub-section explains using this vagrantfile. Also note that Youki currently only supports and expects systemd as init system, and would not work on other systems. There is currently work on-going to put systemd dependent features behind a feature flag, but till then you will need a systemd enabled system to work with Youki.","breadcrumbs":"User Documentation » Basic Setup » Basic Setup","id":"4","title":"Basic Setup"},"40":{"body":"","breadcrumbs":"Community » Contributing » Contributing","id":"40","title":"Contributing"},"41":{"body":"Every commit must be signed off with the Signed-off-by: REAL NAME