DOCSEARCHbyAlgolia
Submit Docs

youki Documentation

repository·main·Indexed 27 days ago

https://github.com/youki-dev/youki

youki is a memory-safe, lightweight implementation of the OCI runtime-spec written in Rust, designed as an alternative to runc. It includes support for rootless mode, WebAssembly (WASM) modules, and integration as a Docker runtime. The project contains several crates, including liboci-cli for parsing OCI runtime command line arguments and libcgroups for managing cgroup statistics, PSI, and systemd CPU set restrictions.

Tokens
25.8K
Snippets
57
Records
208
Agent score
92%

What's inside youki

  3. Use the libcontainer crate for container management

    main

    The libcontainer crate is a core component of the youki workspace. It provides the fundamental functions and structs required to create and manage container processes by leveraging Linux kernel mechanisms such as control groups (cgroups), namespaces, and pivot_root.

    Key features include:

    • Youki Config: A lightweight subset of the OCI specification containing only the essential data required for running containers, optimized for efficient parsing and passing.
    • Socket Wrappers: Provides wrappers over basic Linux sockets used for communication between the main youki process, the container process, and intermediate processes.
    • AppArmor Interface: An interface to apply security profiles to programs via the AppArmor Linux Kernel module.

  5. Use the seccomp Rust FFI bindings

    main

    The seccomp crate provides Rust Foreign Function Interface (FFI) bindings for the Linux kernel'//seccomp feature. It allows processes to transition into a secure mode where syscalls and file descriptor interactions are restricted (e.g., limiting to exit, sigreturn, and read/write on existing descriptors).

    These bindings are generated via rust-bindgen from the seccomp C headers and manually adjusted for correctness. This crate is a low-level binding layer and does not implement high-level seccomp features itself.

  6. Understand the youki container lifecycle

    main

    The youki crate provides the main binary and user interface for container management. It orchestrates other crates to perform container creation and management through a multi-stage process involving an intermediate process and an init process.

    Container Creation Flow (youki create)

    1. Main Process: Loads specification, configuration, and sockets. Uses the clone syscall to create an intermediate process.
    2. Intermediate Process: Sets cgroups and capabilities, then forks to create the init process. It handles the transition into the PID namespace (since clone cannot enter an existing PID namespace directly). It also requests UID/GID mappings from the main process, applies them, and returns the init process PID to the main process before exiting.
    3. Init Process:
      • Transitions into the new namespace setup.
      • Changes the root mountpoint using pivot_root.
      • Sets up capabilities and seccomp.
      • Sends a seccomp notify FD to the main process.
      • Waits for a 'ready' signal from the host's seccomp agent.
      • Sends a 'ready' notification to the main process and waits for a 'start' signal.
    4. Main Process: Receives 'ready' signals, updates the container's PID file, and exits.

    Container Execution Flow (youki start)

    1. Main Process: Executed with the container ID. It sends a 'start' signal to the waiting init process and then exits.
    2. Init Process: Receives the 'start' signal, execs the target program inside the container, and exits.

  7. Use liboci-cli to parse OCI-compliant command line arguments

    main
    The liboci-cli crate provides a standalone implementation of the structures required to parse command-line arguments for an OCI-spec compliant runtime interface. While it is used by youki to handle its own CLI, it can be integrated into any other project that needs to implement an OCI-compliant command-line interface. It is built on top of the clap-v4 crate.

  8. Build libcontainer with musl

    main

    To build libcontainer using musl, you must disable the default features to remove the libseccomp dependency, as libseccomp references shared libraries that are incompatible with musl builds.

    When building, use the --no-default-features flag followed by -F and the specific feature you wish to build (e.g., -F v2). You must also use the +nightly flag with rustup and cargo.

  9. Find beginner-friendly tasks in youki

    main

    To start contributing to youki, you can look for specific entry points designed for beginners:

    1. GitHub Issues: Search the GitHub repository issues for labels good first issue or help wanted.
    2. Source Code Comments: Search the codebase for TODO or FIXME comments to find pending tasks or known bugs.
    3. Documentation: Improve the public-facing API and struct documentation. Adding doc comments and usage examples helps users of the cargo doc generated documentation.
    4. Integration Tests: Contribute to the porting of OCI-runtime integration tests from Go to Rust. This is located in the integration_test crate and aims to provide a pure Rust implementation of OCI spec compliance tests.

  11. Build youki from source

    main

    To build youki locally on Linux, clone the repository and use the just command to build the development or release version.

    git clone git@github.com:youki-dev/youki.git
cd youki
just youki-dev # or youki-release
./youki -h # view help information
    git 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

  12. Use liboci-cli to parse OCI runtime command line arguments

    main

    The liboci-cli module provides Rust structures that implement the OCI (Open Container Initiative) Runtime Command Line Interface specification. These structures derive clap::Parser, allowing you to integrate OCI-compliant command-line argument parsing directly into your own Rust applications or CLI tools.

    Supported subcommands implemented in liboci-cli include:

    • create
    • start
    • state
    • kill
    • delete
    • events
    • exec
    • list
    • pause
    • ps
    • resume
    • run
    • spec