Skip to content

Packaging pre-built unikernels for urunc

In this page we will explain the process of packaging an existing / pre-built unikernel as an OCI image with the necessary annotations for urunc. As an example, we will use a network example over MirageOS from mirage-skeleton targeting Solo5-hvt.

For simply packaging pre-built unikernel images, we can use both bunny and bunix.

NOTE: The below steps can be easily adjusted to any pre-built unikernel image.

Using bunny

In the case of bunny and pre-built unikernel images, we can use both supported file syntaxes: a) bunnyfile and b) the Dockerfile-like syntax.

Using a bunnyfile

In order to package an existing pre-built unikernel image with bunny and a bunnyfile we can define the bunnyfile as:

#syntax=harbor.nbfc.io/nubificus/bunny:0.0.2
version: v0.1

platforms:
  framework: mirage
  monitor: hvt
  architecture: x86

kernel:
  from: local
  path: network.hvt

cmdline: ""

In the above file we specify the following:

  • We want to package a MirageOS unikernel that will execute on top of Solo5-hvt over x86 architecture.
  • We want to use the network.hvt binary as the unikernel to boot.
  • We do not specify any command line, since the unikernel does not necessarily require one.

We can build the OCI image with the following command:

docker build -f bunnyfile -t urunc/prebuilt/network-mirage-hvt:test .

Using a Dockerfile-like syntax

In order to package an existing pre-built unikernel image with bunny and a Dockerfile-like syntax file, we can define the Containerfile as:

#syntax=harbor.nbfc.io/nubificus/bunny:0.0.2
FROM scratch

COPY network.hvt /unikernel/network.hvt

LABEL com.urunc.unikernel.binary=/unikernel/network.hvt
LABEL "com.urunc.unikernel.cmdline"=""
LABEL "com.urunc.unikernel.unikernelType"="mirage"
LABEL "com.urunc.unikernel.hypervisor"="hvt"
LABEL "com.urunc.unikernel.useDMBlock"="false"

In the above file:

  • We directly copy the unikernel binary in the OCI's image rootfs.
  • We manually specify through labels the urunc annotations.

We can build the OCI image with the following command:

docker build -f Containerfile -t urunc/prebuilt/network-mirage-hvt:test .

Using bunix

In the case of bunix we need to clone the whole repository in the same directly as the unikernel. Then, we simply need to edit the args.nix file as:

{
  name = "urunc/prebuilt/network-mirage-hvt";
  tag = "test";
  files = {
    "./network.hvt" = "/unikernel/network.hvt";
  };
  annotations = {
    unikernelType = "mirage";
    hypervisor = "hvt";
    binary = "/unikernel/network.hvt";
    cmdline = "";
    unikernelVersion = "";
    initrd = "";
    block = "";
    blkMntPoint = "";
    useDMBlock = "false";
  };
}

In the above file:

  • We directly specify the files to copy inside the OCI's image rootfs.
  • We manually specify all urunc annotations.

We can build the OCI image by simply running the following command:

nix-build default.nix

The above command will create a container image in a tar inside Nix's store. For easier access of the tar, Nix creates a symlink of the tar file in the CWD. The symlink will be named as result. Therefore, we can load the container image with:

docker load < result