From af6a154e7f429feca1719398278cdb7b5397e955 Mon Sep 17 00:00:00 2001 From: Charalampos Mainas Date: Fri, 26 Jun 2026 07:57:24 +0000 Subject: [PATCH 1/3] docs: Small update in the docs for cloud-hypervisor support Update all the pages in the docs for the cloud-hypervisor support. Previosuly we only had references for cloud-hypervisor in the "VMM/Sandbox" page. This commit updates all other pages where cloud-hypervisor needs to be mentioned. Furthermore, we add the existing built images for cloud-hypervisor in Sample images. PR: https://github.com/urunc-dev/urunc/pull/786 Signed-off-by: Charalampos Mainas Reviewed-by: Anastassios Nanos Approved-by: Anastassios Nanos --- README.md | 12 +++---- docs/Sample-images.md | 2 ++ docs/design/seccomp.md | 4 ++- docs/developer-guide/debugging.md | 4 +-- docs/index.md | 2 +- docs/installation.md | 37 +++++++++++++++++++--- docs/package/index.md | 4 +-- docs/tutorials/existing-container-linux.md | 8 +++-- docs/unikernel-support.md | 13 ++++++-- docs/variables/versions.yml | 1 + 10 files changed, 66 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 6dc4ba2f..37d1083a 100644 --- a/README.md +++ b/README.md @@ -141,12 +141,12 @@ 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 | -| Hermit | QEMU | x86 | Initrd | +| 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, Cloud-HYpervisor | x86,aarch64 | Initrd, Block/Devmapper, 9pfs, Virtiofs | +| Hermit | QEMU | x86 | Initrd | We plan to add support for more unikernel frameworks and other platforms too. Feel free to [contact](#Contact) us for a specific unikernel framework or similar diff --git a/docs/Sample-images.md b/docs/Sample-images.md index 0dea15e2..6a9e6b72 100644 --- a/docs/Sample-images.md +++ b/docs/Sample-images.md @@ -30,6 +30,7 @@ We plan to create and maintain multi-platform images soon, as well as enrich thi - harbor.nbfc.io/nubificus/urunc/nginx-firecracker-unikraft-initrd:latest - harbor.nbfc.io/nubificus/urunc/nginx-firecracker-linux-raw:latest - harbor.nbfc.io/nubificus/urunc/nginx-firecracker-linux-block:latest +- harbor.nbfc.io/nubificus/urunc/nginx-cloud-hypervisor-linux-raw:latest - harbor.nbfc.io/nubificus/urunc/hello-server-qemu-mewz:latest - harbor.nbfc.io/nubificus/urunc/httpreply-firecracker-unikraft:latest - harbor.nbfc.io/nubificus/urunc/redis-hvt-rumprun-raw:latest @@ -50,4 +51,5 @@ We plan to create and maintain multi-platform images soon, as well as enrich thi - harbor.nbfc.io/nubificus/urunc/whoami-firecracker-linux-initrd:latest - harbor.nbfc.io/nubificus/urunc/busybox-qemu-linux-raw:latest - harbor.nbfc.io/nubificus/urunc/busybox-firecracker-linux-raw:latest +- harbor.nbfc.io/nubificus/urunc/busybox-cloud-hypervisor-linux-raw:latest - harbor.nbfc.io/nubificus/urunc/hello-world-qemu-hermit-initrd:latest diff --git a/docs/design/seccomp.md b/docs/design/seccomp.md index 00995fc5..f1ff2137 100644 --- a/docs/design/seccomp.md +++ b/docs/design/seccomp.md @@ -26,9 +26,11 @@ VMM before attacking the host. To further limit the exposure of the host kernel to the VMM, 'urunc' uses seccomp filters for each supported VMM. In particular, in the case of: - Firecracker, 'urunc' does not have to do anything more, since Firecracker by - default makes uses seccomp filters. + default makes use of seccomp filters. - Qemu, 'urunc' makes use of Qemu's sandbox command line options to activate all possible seccomp filters in Qemu. +- Cloud-Hypervisor, 'urunc' makes use of the `--seccomp true` command line + options to enable Cloud-Hypervisor's seccomp filters. - Solo5-hvt, 'urunc' applies the seccomp filters before executing 'Solo5-hvt'. - Solo5-spt, 'urunc' can not do anything since solo5-spt makes use of seccomp by diff --git a/docs/developer-guide/debugging.md b/docs/developer-guide/debugging.md index d951e320..62b212a8 100644 --- a/docs/developer-guide/debugging.md +++ b/docs/developer-guide/debugging.md @@ -85,7 +85,7 @@ Using `cntr` with a urunc container gives: - Working PTY devices (`/dev/pts`, `/dev/ptmx`, `/dev/console`) - A debugging environment with common tools (e.g., `ls`, `ps`, `strace`) -- Visibility into the container namespace where the monitor process (qemu/firecracker/solo5) runs +- Visibility into the container namespace where the monitor process (qemu/rirecracker/cloud-hypervisor/solo5) runs > **Note:** `cntr` does **not** enter the unikernel VM — it only provides access to the container namespace hosting the monitor. @@ -103,4 +103,4 @@ sudo tee /usr/local/bin/urunc > /dev/null <<'EOT' exec /usr/local/bin/urunc.default --debug "$@" EOT sudo chmod +x /usr/local/bin/urunc -``` \ No newline at end of file +``` diff --git a/docs/index.md b/docs/index.md index 7dd2ec6a..c9fc2f26 100644 --- a/docs/index.md +++ b/docs/index.md @@ -59,7 +59,7 @@ Sandbox monitors, along with the unikernels that can run on top of them. | [Unikraft](./unikernel-support#unikraft)| [Qemu](./hypervisor-support#qemu), [Firecracker](./hypervisor-support#aws-firecracker) | x86 | Initrd, 9pfs | | [MirageOS](./unikernel-support#mirage)| [Qemu](./hypervisor-support#qemu), [Solo5-hvt](./hypervisor-support#solo5-hvt), [Solo5-spt](./hypervisor-support#solo5-spt) | x86, aarch64 | Block/Devmapper | | [Mewz](./unikernel-support#mewz)| [Qemu](./hypervisor-support#qemu) | x86 | In-memory | -| [Linux](./unikernel-support#linux)| [Qemu](./hypervisor-support#qemu), [Firecracker](./hypervisor-support#aws-firecracker) | x86, aarch64 | Initrd, Block/Devmapper, 9pfs, Virtiofs | +| [Linux](./unikernel-support#linux)| [Qemu](./hypervisor-support#qemu), [Firecracker](./hypervisor-support#aws-firecracker), [Cloud-Hypervisor](./hypervisor-support#cloud-hypervisor) | x86, aarch64 | Initrd, Block/Devmapper, 9pfs, Virtiofs | | [Hermit](./unikernel-support#hermit)| [Qemu](./hypervisor-support#qemu) | x86 | Initrd | diff --git a/docs/installation.md b/docs/installation.md index fdfcea27..1f39a3cb 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -26,6 +26,7 @@ with virtiofsd. Specifically: - [solo5-{hvt|spt}](https://github.com/Solo5/solo5) - [qemu](https://www.qemu.org/) - [firecracker](https://github.com/firecracker-microvm/firecracker) +- [Cloud-Hypervisor](https://github.com/cloud-hypervisor/cloud-hypervisor) - [virtiofsd](https://virtio-fs.gitlab.io/) **3. Installation and configuration of `urunc`** @@ -314,20 +315,24 @@ in the [respective section of the repository's README file](https://github.com/urunc-dev/monitors-build?tab=readme-ov-file#how-to-use). As an example, the following commands use the -[`FC-v1.7.0_S5-v0.9.3_VFS_-v1.13.0_QM-v10.1.1-9a44e` -release](https://github.com/urunc-dev/monitors-build/releases/tag/FC-v1.7.0_S5-v0.9.3_VFS_-v1.13.0_QM-v10.1.1-9a44e) +[`FC-v1.7.0_CLH-v50.0_S5-v0.9.3_VFS_-v1.13.0_QM-v10.1.1-9a44e` +release](https://github.com/urunc-dev/monitors-build/releases/tag/FC-v1.7.0_CLH-v50.0_S5-v0.9.3_VFS_-v1.13.0_QM-v10.1.1-9a44e) which contains the following monitors and tools in the specified versions: - Firecracker v1.7.0 +- Cloud Hypervisor v50.0 - Solo5 v0.9.3 - Virtiofsd v1.13.0 - Qemu v10.1.1 To download and install the monitors in `/tmp`: ``` -wget https://github.com/urunc-dev/monitors-build/releases/download/FC-v1.7.0_S5-v0.9.3_VFS_-v1.13.0_QM-v10.1.1-9a44e/release-amd64-FC-v1.7.0_S5-v0.9.3_VFS_-v1.13.0_QM-v10.1.1-9a44e.tar.gz -sudo tar Cxzvf /opt release-amd64-FC-v1.7.0_S5-v0.9.3_VFS_-v1.13.0_QM-v10.1.1-9a44e.tar.gz -rm -f release-amd64-FC-v1.7.0_S5-v0.9.3_VFS_-v1.13.0_QM-v10.1.1-9a44e.tar.gz +ARCH="$(dpkg --print-architecture)" +VERSION="FC-v1.7.0_CLH-v50.0_S5-v0.9.3_VFS_-v1.13.0_QM-v10.1.1-9a44e" +release_url="https://github.com/urunc-dev/monitors-build/releases/download" +wget ${release_url}/${VERSION}/release-${ARCH}-${VERSION}.tar.gz +sudo tar Cxzvf /opt release-${ARCH}-${VERSION}.tar.gz +rm release-${ARCH}-${VERSION}.tar.gz ``` After downloading all the binaries, we need to instruct `urunc` about the @@ -349,6 +354,9 @@ data_path = "/opt/urunc/share/qemu" [monitors.firecracker] path = "/opt/urunc/bin/firecracker" +[monitors.cloud-hypervisor] +path = "/opt/urunc/bin/cloud-hypervisor" + [monitors.hvt] path = "/opt/urunc/bin/solo5-hvt" @@ -405,6 +413,25 @@ sudo mv release-${VERSION}-${ARCH}/firecracker-${VERSION}-${ARCH} /usr/local/bin rm -fr release-${VERSION}-${ARCH} ``` +### Cloud-Hypervisor + +[Cloud-Hypervisor](https://github.com/cloud-hypervisor/cloud-hypervisor) +provides releases with statically-built binaries. To get a specific version +(e.g. "v[[ versions.clh ]]": + +```bash +ARCH="$(uname -m)" +VERSION="v50.0" +release_url="https://github.com/cloud-hypervisor/cloud-hypervisor/releases" +if [ "$ARCH" = "x86_64" ]; then + curl -L ${release_url}/download/${VERSION}/cloud-hypervisor-static -o cloud-hypervisor +else + curl -L ${release_url}/download/${VERSION}/cloud-hypervisor-static-${ARCH} -o cloud-hypervisor +fi +chmod +x cloud-hypervisor +sudo mv cloud-hypervisor /usr/local/bin/ +``` + ### Virtiofsd As an alternative to 9pfs, `urunc` can configure Qemu to use diff --git a/docs/package/index.md b/docs/package/index.md index 2e772414..311eb98a 100644 --- a/docs/package/index.md +++ b/docs/package/index.md @@ -52,8 +52,8 @@ required annotations are the following: - `com.urunc.unikernel.unikernelType`: The type of the unikernel. Currently supported values: a) unikraft, b) rumprun, c) mirage. - `com.urunc.unikernel.hypervisor`: The VMM or sandbox monitor to run the - unikernel Currently supported values: a) `qemu`, b) `firecracker`, c) `spt`, - d) `hvt`. + unikernel Currently supported values: a) `qemu`, b) `firecracker`, c) + `cloud-hypervisor`, d) `spt`, e) `hvt`. - `com.urunc.unikernel.binary`: The path to the unikernel binary inside the container's rootfs - `com.urunc.unikernel.cmdline`: The application's cmdline to pass to the diff --git a/docs/tutorials/existing-container-linux.md b/docs/tutorials/existing-container-linux.md index 31260705..d597f7fc 100644 --- a/docs/tutorials/existing-container-linux.md +++ b/docs/tutorials/existing-container-linux.md @@ -23,8 +23,10 @@ Overall, we need to do the following: The main requirement for running existing containers on top of `urunc` is a Linux kernel. From `urunc`'s side there are no specific kernel configuration options required, but since Linux will run on virtual machine monitors like -[Qemu](https://qemu.org) or -[Firecracker](https://github.com/firecracker-microvm/firecracker), the kernel +[Qemu](https://qemu.org), +[Firecracker](https://github.com/firecracker-microvm/firecracker), or +[Cloud-Hypervisor](https://www.cloudhypervisor.org/), +the kernel should be configured with the necessary drivers (e.g., virtio devices). To simplify this, you can find @@ -40,6 +42,8 @@ Alternatively, prebuilt kernels are available via the following container images - `harbor.nbfc.io/nubificus/urunc/linux-kernel-qemu:v6.14` - `harbor.nbfc.io/nubificus/urunc/linux-kernel-firecracker:v6.14` +> NOTE: For cloud-hypervisor users can use the Linux kernel image of Firecracker. + Each image contains the Linux kernel binary at `/kernel`. ## Init process diff --git a/docs/unikernel-support.md b/docs/unikernel-support.md index ef2c7b7f..6c225505 100644 --- a/docs/unikernel-support.md +++ b/docs/unikernel-support.md @@ -311,8 +311,9 @@ emulated devices etc.). Focusing on the single-application notion of using the [Linux](https://github.com/torvalds/linux) kernel, `urunc` provides support for -both [Qemu](https://qemu.org) and -[Firecracker](https://github.com/firecracker-microvm/firecracker). For network, +both [Qemu](https://qemu.org), +[Firecracker](https://github.com/firecracker-microvm/firecracker) and +[Cloud-Hypervisor](https://www.cloudhypervisor.org/). For network, `urunc` will make use of virtio-net either through PCI or MMIO, depending on the monitor. In the case of storage, `urunc` can use initrd, virtio-block, 9pfs or Virtiofs. In particular, `urunc` takes advantage of the extensive filesystem @@ -342,6 +343,14 @@ An example of a Redis alpine image transformed to a block file on top of sudo nerdctl run --rm -ti --runtime io.containerd.urunc.v2 harbor.nbfc.io/nubificus/urunc/redis-firecracker-linux-block:latest ``` +An example of a Nginx alpine image on top of +[Cloud-Hypervisor](https://www.cloudhypervisor.org/) and +[Linux](https://github.com/torvalds/linux) with 'urunc': + +```bash +sudo nerdctl run --rm -ti --runtime io.containerd.urunc.v2 harbor.nbfc.io/nubificus/urunc/nginx-cloud-hypervisor-linux-raw:latest +``` + ## Hermit [Hermit](https://hermit-os.org/) is a unikernel designed for diff --git a/docs/variables/versions.yml b/docs/variables/versions.yml index cba6e951..946401a2 100644 --- a/docs/variables/versions.yml +++ b/docs/variables/versions.yml @@ -5,6 +5,7 @@ versions: containerd: "2.1.3" qemu: "8.2.2" firecracker: "1.7.0" + clh: "50.0" solo5: "0.9.0" cni_plugins: "1.7.1" knative: "1.17.0" From 51e349513710d13f8b60b7b289ac4e8bc5b66568 Mon Sep 17 00:00:00 2001 From: Charalampos Mainas Date: Fri, 26 Jun 2026 07:59:55 +0000 Subject: [PATCH 2/3] feat(cloud-hypervisor): Add support for block-based rootfs in Linux Add support for bloc-based rootfs of Linux guests over cloud-hypervisor. The support was missing because we simply had to update the respective function in the linux.go file. PR: https://github.com/urunc-dev/urunc/pull/786 Signed-off-by: Charalampos Mainas Reviewed-by: Anastassios Nanos Approved-by: Anastassios Nanos --- pkg/unikontainers/unikernels/linux.go | 7 +++++++ tests/e2e/test_cases.go | 16 ++++++++++++++++ 2 files changed, 23 insertions(+) diff --git a/pkg/unikontainers/unikernels/linux.go b/pkg/unikontainers/unikernels/linux.go index d6bb8095..94e5b53e 100644 --- a/pkg/unikontainers/unikernels/linux.go +++ b/pkg/unikontainers/unikernels/linux.go @@ -179,6 +179,13 @@ func (l *Linux) MonitorBlockCli() []types.MonitorBlockArgs { Path: aBlock.Source, }) } + case "cloud-hypervisor": + for _, aBlock := range l.Blk { + blkArgs = append(blkArgs, types.MonitorBlockArgs{ + ID: aBlock.ID, + Path: aBlock.Source, + }) + } default: return nil } diff --git a/tests/e2e/test_cases.go b/tests/e2e/test_cases.go index 31bec3d8..ad51fabb 100644 --- a/tests/e2e/test_cases.go +++ b/tests/e2e/test_cases.go @@ -456,6 +456,22 @@ func nerdctlTestCases() []containerTestArgs { Skippable: false, TestFunc: pingTest, }, + { + Image: "harbor.nbfc.io/nubificus/urunc/nginx-cloud-hypervisor-linux-raw:latest", + Name: "CloudHypervisor-linux-nginx-devmapper", + Devmapper: true, + Seccomp: true, + UID: 0, + GID: 0, + Groups: []int64{}, + Memory: "512M", + Cli: "", + Volumes: []containerVolume{}, + StaticNet: false, + SideContainers: []string{}, + Skippable: false, + TestFunc: pingTest, + }, } } From 4e94e4b9c90984c641950f302ce3a2c053e7635d Mon Sep 17 00:00:00 2001 From: Charalampos Mainas Date: Fri, 26 Jun 2026 13:07:28 +0000 Subject: [PATCH 3/3] chore(urunc-deploy): Update to install cloud-hypervisor Update all necessary files to also install and configure cloud-hypervisor when using urunc-deploy. PR: https://github.com/urunc-dev/urunc/pull/786 Signed-off-by: Charalampos Mainas Reviewed-by: Anastassios Nanos Approved-by: Anastassios Nanos --- deployment/urunc-deploy/Dockerfile | 13 +++++++++++++ deployment/urunc-deploy/config.toml | 5 +++++ deployment/urunc-deploy/scripts/install.sh | 6 +++++- .../urunc-deploy/base/urunc-deploy.yaml | 2 +- 4 files changed, 24 insertions(+), 2 deletions(-) diff --git a/deployment/urunc-deploy/Dockerfile b/deployment/urunc-deploy/Dockerfile index 609964e3..de6fe1e6 100644 --- a/deployment/urunc-deploy/Dockerfile +++ b/deployment/urunc-deploy/Dockerfile @@ -60,6 +60,18 @@ RUN ARCH=$(uname -m) && \ WORKDIR /artifacts RUN cp /firecracker . +FROM alpine:3.21@sha256:b6a6be0ff92ab6db8acd94f5d1b7a6c2f0f5d10ce3c24af348d333ac6da80685 AS cloud-hypervisor-builder +RUN apk update && apk add --no-cache curl tar +RUN ARCH=$(uname -m) && \ + VERSION="v50.0" && \ + RELEASE_URL="https://github.com/cloud-hypervisor/cloud-hypervisor/releases" && \ + if [ "${ARCH}" = "x86_64" ]; then BIN=cloud-hypervisor-static; fi && \ + if [ "${ARCH}" = "aarch64" ]; then BIN=cloud-hypervisor-static-aarch64; fi && \ + curl -L -o cloud-hypervisor ${RELEASE_URL}/download/${VERSION}/${BIN} && \ + chmod +x cloud-hypervisor +WORKDIR /artifacts +RUN cp /cloud-hypervisor . + FROM quay.io/kata-containers/kata-deploy:3.15.0@sha256:fbab8bdbe910b52cf9396261f887f894cd3e71f86abe68ec11595ab7628b4a10 AS qemu-builder WORKDIR /artifacts RUN ARCH=$(uname -m) && \ @@ -73,6 +85,7 @@ COPY --from=qemu-builder /artifacts /urunc-artifacts/hypervisors COPY --from=qemu-builder /opt/kata-artifacts/opt/kata/share/kata-qemu/qemu /urunc-artifacts/opt/kata/share/kata-qemu/qemu COPY --from=qemu-builder /opt/kata-artifacts/opt/kata/libexec/virtiofsd /urunc-artifacts/libexec/virtiofsd COPY --from=firecracker-builder /artifacts /urunc-artifacts/hypervisors +COPY --from=cloud-hypervisor-builder /artifacts /urunc-artifacts/hypervisors COPY --from=urunc-builder /artifacts/dist /urunc-artifacts RUN apk update && \ diff --git a/deployment/urunc-deploy/config.toml b/deployment/urunc-deploy/config.toml index 8eeffaf4..3d37ac5b 100644 --- a/deployment/urunc-deploy/config.toml +++ b/deployment/urunc-deploy/config.toml @@ -18,6 +18,11 @@ default_memory_mb = 256 default_vcpus = 1 path = "/opt/urunc/bin/firecracker" +[monitors.cloud-hypervisor] +default_memory_mb = 256 +default_vcpus = 1 +path = "/opt/urunc/bin/cloud-hypervisor" + [monitors.spt] default_memory_mb = 256 default_vcpus = 1 diff --git a/deployment/urunc-deploy/scripts/install.sh b/deployment/urunc-deploy/scripts/install.sh index 0ab13bd0..92f3b01b 100644 --- a/deployment/urunc-deploy/scripts/install.sh +++ b/deployment/urunc-deploy/scripts/install.sh @@ -32,7 +32,7 @@ urunc_libexec_dir="${urunc_install_dir}/libexec" urunc_config_dir="/etc/urunc" urunc_config_file="${urunc_config_dir}/config.toml" -HYPERVISORS="${HYPERVISORS:-"firecracker qemu solo5-hvt solo5-spt"}" +HYPERVISORS="${HYPERVISORS:-"firecracker cloud-hypervisor qemu solo5-hvt solo5-spt"}" IFS=' ' read -a hypervisors <<< "$HYPERVISORS" function host_systemctl() { @@ -78,6 +78,10 @@ function install_artifacts() { echo "Installing firecracker" install_artifact /urunc-artifacts/hypervisors/firecracker /host${urunc_bin_dir}/firecracker ;; + cloud-hypervisor) + echo "Installing cloud-hypervisor" + install_artifact /urunc-artifacts/hypervisors/cloud-hypervisor /host${urunc_bin_dir}/cloud-hypervisor + ;; solo5-spt) echo "Installing solo5-spt" install_artifact /urunc-artifacts/hypervisors/solo5-spt /host${urunc_bin_dir}/solo5-spt diff --git a/deployment/urunc-deploy/urunc-deploy/base/urunc-deploy.yaml b/deployment/urunc-deploy/urunc-deploy/base/urunc-deploy.yaml index 07081620..db6d886e 100644 --- a/deployment/urunc-deploy/urunc-deploy/base/urunc-deploy.yaml +++ b/deployment/urunc-deploy/urunc-deploy/base/urunc-deploy.yaml @@ -45,7 +45,7 @@ spec: fieldRef: fieldPath: spec.nodeName - name: HYPERVISORS - value: "firecracker qemu solo5-hvt solo5-spt" + value: "firecracker cloud-hypervisor qemu solo5-hvt solo5-spt" - name: DEBUG value: "false" securityContext: