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:latest
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:latest
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