README
¶
urunc
Welcome to urunc, the "runc for unikernels".
Table of Contents
- Introduction
- Quick start
- Installation guide
- Documentation
- Supported platforms
- Publications and talks
- Bug Reporting
- Community & Meetings
- Roadmap
- Contributing
- Security Policy
- Changelog
- License
- Contact
Introduction
The main goal of urunc is to bridge the gap between traditional unikernels
and containerized environments, enabling seamless integration with cloud-native
architectures. Designed to fully leverage the container semantics and benefits
from the OCI tools and methodology, urunc aims to become “runc for
unikernels”, while offering compatibility with the Container Runtime Interface
(CRI). Unikernels are packaged inside OCI-compatible images and urunc launces
the unikernel on top of the underlying Virtual Machine or seccomp monitors.
Thus, developers and administrators can package, deliver, deploy and manage
unikernels using familiar cloud-native practices.
For the above purpose urunc acts as any other OCI runtime. The main
difference of urunc with other container runtimes is that instead of spawning
a simple process, it uses a Virtual Machine Monitor (VMM) or a Sandbox Monitor
to run the unikernel. It is important to note that urunc does not require any
particular software running alongside the user's application, inside or outside
the unikernel. As a result, urunc manages the user's application running
inside the unikernel through the respective VM process.
Quick start
The easiest and fastest way to try out urunc would be with docker
Before doing so, please make sure that the host system satisfies the
following dependencies:
Install Docker:
$ curl -fsSL https://get.docker.com -o get-docker.sh
$ sudo sh get-docker.sh
$ rm get-docker.sh
$ sudo groupadd docker
$ sudo usermod -aG docker $USER
Install urunc:
$ sudo apt-get install -y git
$ git clone https://github.com/urunc-dev/urunc.git
$ docker run --rm -ti -v $PWD/urunc:/urunc -w /urunc golang:latest bash -c "git config --global --add safe.directory /urunc && make"
$ sudo make -C urunc install
Install QEMU:
$ sudo apt install -y qemu-kvm
Now we are ready to run nginx as a Unikraft unikernel using Docker and urunc:
$ docker run --rm -d --runtime io.containerd.urunc.v2 harbor.nbfc.io/nubificus/urunc/nginx-qemu-unikraft-initrd:latest
67bec5ab9a748e35faf7c2079002177b9bdc806220e59b6b413836db1d6e4018
We can inspect the container and get its IP address:
$ docker inspect 67bec5ab9a748e35faf7c2079002177b9bdc806220e59b6b413836db1d6e4018 | grep IPAddress
"SecondaryIPAddresses": null,
"IPAddress": "172.17.0.2",
"IPAddress": "172.17.0.2",
At last we can curl the Nginx server running inside Unikraft with:
$ curl 172.17.0.2
<!DOCTYPE html>
<html>
<head>
<title>Hello, world!</title>
</head>
<body>
<h1>Hello, world!</h1>
<p>Powered by <a href="http://unikraft.org">Unikraft</a>.</p>
</body>
</html>
Installation guide
For a detailed installation guide please check Documentation and particularly the installation guide page.
Documentation
We keep an up to date documentation for urunc at
https://urunc.io/ . We use mkdocs to
render urunc's documentation. Hence, you can also have a local preview of
documentation by running either make docs or make docs_container.
In the first case, make docs will execute mkdocs serve. Take a note of the
url, where the docs will be served in the output of the command
(i.e. http://127.0.0.1:8000). It is important to note, that material-mkdocs
must be installed. For more information, please check the installation
guide.
Moreover, the pip packages mkdocs-literate-nav and mkdocs-section-index
should also be installed.
In the second case, a container with all dependencies will start serving the documentation at http://127.0.0.1:8000.
Supported platforms
At the moment, urunc is available on GNU/Linux for x86_64 and arm64 architectures.
In addition, the following table provides an overview of the currently
supported VM/Sandbox monitors and unikernels:
| Unikernel | VM/Sandbox Monitor | Arch | Storage |
|---|---|---|---|
| Rumprun | Solo5-hvt, Solo5-spt | x86,aarch64 | Block/Devmapper |
| Unikraft | QEMU, Firecracker | x86 | Initrd, 9pfs |
| MirageOS | QEMU, Solo5-hvt, Solo5-spt | x86,aarch64 | Block/Devmapper |
| Mewz | QEMU | x86 | In-memory |
| Linux | QEMU, Firecracker | x86 | Initrd, Block/Devmapper, 9pfs, Virtiofs |
We plan to add support for more unikernel frameworks and other platforms too.
Feel free to contact us for a specific unikernel framework or similar
technologies that you would like to see in urunc.
Running on k8s
To use urunc with an existing Kubernetes cluster, please follow the
instructions in the
docs.
Publications and talks
A part of our work in urunc has been published in EuroSys'24 SESAME workshop,
under the title Sandboxing Functions for Efficient and Secure Multi-tenant
Serverless Deployments. Feel
free to ask us if you can not have access to the paper.
Furthermore, urunc has appeared in various open source summits and events,
such as:
- Open Source Summit 2023
- FOSDEM 2024 -- Containers devroom
- KubeCon 2024
- FOSDEM 2025 -- Containers devroom
- FOSDEM 2025 -- WASM devroom
Bug reporting
Please use github issues to report any bug. For more info please check the reporting bugs section in the Contributing guide.
Roadmap
We track planned features, improvements, and milestones using GitHub Issues. You can view the Roadmap for each one of the next (or previous) releases by filtering based on the respective milestone.
Have a feature in mind or want to contribute? Open an issue or fire-up a discussion!
Community and Meetings
Join us for our monthly open meetings, held every last Wednesday of the month. These sessions are a great opportunity to share ideas, ask questions, and stay connected with the project team and other contributors.
- Meeting Frequency: Monthly (last Wednesday of the month)
- Time: 15:00 UTC
- Format: Open agenda + roadmap review Minutes & Agenda
- Platform: LF meetings
- Invitation: link
- Slack channel
Contributing
We will be very happy to receive any feedback and any kind of contributions for
urunc. For more details please take a look in urunc's contributing
document.
Security policy
In case of a security vulnerability, please refer to the Security Policy document. for guidelines on how to report it responsibly.
Changelog
See CHANGELOG.md for more information on what changed in the latest and previous releases.
License
Contact
We kindly invite everyone interested in urunc to join our
Slack channel.
To directly communicate with the maintainers, feel free to drop an email At
urunc's maintainers' mailing list
Directories