To bridge the gap between traditional unikernels and containerized environments, enabling seamless integration with cloud-native architectures, we introduce urunc. Designed to fully leverage the container semantics and benefit from the OCI tools and methodology, urunc aims to become “runc for unikernels”, while offering compatibility with the Container Runtime Interface (CRI). By relying on underlying hypervisors, urunc launches unikernels provided by OCI-compatible images, allowing developers and administrators to package, deliver, deploy, and manage their software using familiar cloud-native practices.

To delve into the inner workings of urunc, the process of starting a new unikernel "container" via containerd involves the following steps:

• Containerd unpacks the image onto a devmapper block device and invokes urunc.
• urunc parses the image's rootfs and annotations, initiating the required setup procedures. These include creating essential pipes for stdio and verifying the availability of the specified vmm.
• Subsequently, urunc spawns a new process within a distinct network namespace and awaits the completion of the setup phase.
• Once the setup is finished, urunc executes the vmm process, replacing the container's init process with the vmm process. The parameters for the vmm process are derived from the unikernel binary and options provided within the "unikernel" image.
• Finally, urunc returns the process ID (PID) of the vmm process to containerd, effectively enabling it to handle the container's lifecycle management.

At the moment, urunc is available on x86_64 and arm64 architectures.

To build and install urunc binaries, you need:

• make
• Go version 1.18 or greater

A urunc installation requires two binary files: containerd-shim-urunc-v2 and urunc. To build and install those:

make
sudo make install

You can download the binaries from the latest release and install in your PATH.

To run a simple urunc example locally, you need to address a few dependencies:

• containerd version 1.7 or higher (for installation instructions, see here, here and here)
• devmapper snapshotter (for setup and configuration instructions, see here, here and here)
• runc (installation instructions can be found here)
• nerdctl (installation instructions can be found here)
• solo5-hvt as the backend (installation instructions can be found here)
• urunc and containerd-shim-urunc-v2 binaries
• containerd needs to be configured to use devmapper and register urunc as a runtime

If you already have these requirements, you can run a test container using nerdctl:

sudo nerdctl run --rm -ti --snapshotter devmapper --runtime io.containerd.urunc.v2 harbor.nbfc.io/nubificus/urunc/redis-hvt-rump:latest unikernel

The setup process may differ depending on your system and requirements. A full setup process for Ubuntu 22.04 can be found at docs/Installation.md.

Additional instructions on how to setup the various supported hypervisors can be found at docs/Urunc-Hypervisors.md.

The following table provides an overview of the currently supported hypervisors and unikernels:

To use urunc with an existing Kubernetes cluster, you can follow the instructions in the docs.

To locally lint the source code using Docker, run:

git clone https://github.com/nubificus/urunc.git
cd urunc
docker run --rm -v $(pwd):/app -w /app golangci/golangci-lint:v1.53.3 golangci-lint run -v --timeout=5m
# OR
sudo nerdctl run --rm -v $(pwd):/app -w /app golangci/golangci-lint:v1.53.3 golangci-lint run -v --timeout=5m

Apache License 2.0