Cloud hypervisor block support and documentation updates

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

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 && \

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

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

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:

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

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

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
-```
+```

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 |
 
 <!-- ## urunc and the CNCF -->

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

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

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

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

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"

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
 	}

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,
+		},
 	}
 }