How containers/crun works
Main Components
• CLI & Orchestration Layer: Files like src/crun.c, src/create.c, src/start.c, src/exec.c, etc., form the command-line interface and process control layer for container operations.
• Core Container Runtime Library (libcrun): The most significant part is found under src/libcrun. This submodule includes modules for container lifecycle management, cgroup support, seccomp filtering, signal handling, mount management, and even specialized handlers for various container backends (like Mono, WASM runtimes, etc. in handlers/).
• OS Integration & System Interfaces: There is heavy interaction with Linux kernel features such as cgroups (files like cgroup-cgroupfs.c, cgroup-systemd.c, and related utilities), seccomp (seccomp.c, seccomp_notify.c), and namespace handling. This represents the interface that crun uses to create, monitor, and clean-up container processes.
• Build and Configuration Infrastructure: Scripts like autogen.sh, configure.ac, Makefile.am, cfg.mk, and directories like build-aux and m4 denote a conventional GNU autotools build system – highlighting configurable and modular build aspects.
• Contributed Plugins and Examples: Look at the contrib/ directory (e.g., seccomp-notify-plugin-example, terminal-receiver, etc.) which offer extensibility points and integration examples for notification and seccomp handling.
• Bindings / Language Integrations: The lua/ directory (including lua_crun.c and related rockspec files) shows that there is a Lua binding available, while the python/ directory supports Python integrations (evidenced by crun_python.c).
• Tests & Validation: The tests/ directory includes various Dockerfiles, shell scripts, and unit tests (including tests for capabilities, seccomp, mounts, etc.) to ensure system compliance with OCI specs and robust functionality.
Relationships and Interactions
• The CLI layer interacts with the core libcrun library to perform operations such as container creation, delete, exec, and update. These operations are all defined in corresponding source files (e.g., create.c, exec.c, etc.).
• libcrun then interacts directly with the Linux kernel interfaces (via cgroups, seccomp, namespaces, etc.) to enforce isolation, resource limits, and security policies.
• The plugin handlers (e.g., from handlers/ directory) allow for integration with additional functionalities like support for various container runtimes or extensions for languages (e.g., WASM runtimes).
• The build configuration and scripts manage how the overall project pieces are combined, enabling static and shared builds, and even integration with reproducible package systems like Nix.
• The tests simulate different runtime scenarios, ensuring that each component (from CLI processing to OS API interactions) meets the defined OCI specifications.
Architectural Patterns & Design Principles
• Modularization: There is a clear separation between the command interface and the core runtime library.
• Layered Design: Higher-level commands (CLI layer) call into lower-level, specialized modules (libcrun) that directly communicate with the OS.
• Extensibility: The presence of a plugins directory and bindings for multiple programming languages indicates an architectural intention to allow for future enhancements or integrations.
• Isolation and Abstraction: The runtime cleanly abstracts away complex interactions with kernel level features (cgroups, seccomp) from the user-facing operations.