Skip to content

Unikernel

Unikernels are single-purpose machine images that package an application with only the OS primitives it needs, resulting in a minimal footprint. In Sherpa, unikernels run on the KVM hypervisor using the QEMU emulator and the Libvirt API — the same pathway used for virtual machines.

Unikernel architecture: sherpad drives libvirtd, which runs one QEMU process per unikernel on KVM; the kernel ELF or boot disk is a copy in sherpa-pool

Sherpa supports three unikernel models. generic takes other kinds too, so its nodes set kind = "unikernel":

Model Boot Mode Description
generic (kind = "unikernel") DirectKernel Generic type for custom unikernels
unikraft_unikernel DirectKernel Unikraft-based unikernels
nanos_unikernel DiskBoot NanoVMs-based unikernels

Boot Modes

Unikernels support two boot modes that determine how the hypervisor loads the application:

  • DirectKernel — The kernel ELF binary is loaded directly by QEMU via the <kernel> libvirt XML element. An optional kernel command line can be passed via <cmdline> using the unikernel.cmdline manifest parameter. The ELF is copied into the storage pool for each node, so the original image is never used directly.
  • DiskBoot — The unikernel boots from a copy of its disk image in the storage pool, the same way as a traditional VM (<boot dev='hd'/>).

How it Works

When a lab is created, Sherpa performs the following for each unikernel node:

  1. Copy the kernel ELF from the image store into the storage pool
  2. Generate a libvirt domain XML definition with the copied kernel path and optional unikernel.cmdline
  3. Define and start the domain via the Libvirt API
  1. Copy the disk image from the image store into the storage pool
  2. Resize the boot disk if boot_disk.size is specified in the manifest
  3. Generate a libvirt domain XML definition from the node's parameters
  4. Define and start the domain via the Libvirt API

All unikernel nodes are created in parallel after VM nodes have been provisioned.

Resource Allocation

Default parameters for unikernel nodes:

Property Default
CPU 1 vCPU
RAM 512 MiB
Data Interfaces 0
Interface Driver virtio
ZTP disabled

These defaults can be overridden in the manifest.

Image Management

Unikernel images are stored in the same images_dir directory as VM images (default: /opt/sherpa/images/), organised by model and version, for example /opt/sherpa/images/unikraft_unikernel/1.0.0/kernel.elf. The file name depends on the boot mode:

Boot Mode Filename Format
DirectKernel kernel.elf ELF binary
DiskBoot disk.qcow2 QCOW2 disk image

Images are imported via sherpa server image import:

sherpa server image import \
  --src <path-to-image> \
  --version <version> \
  --model <model_name>

Use --kind unikernel with sherpa server image list or sherpa server image scan to filter for unikernel images. To build an image, see the Unikraft and Nanos pages.

Networking

Unikernels use the same networking as virtual machines — virtio interfaces attached to the management network and data plane links as defined in the manifest. See Virtual Machine — Networking for details.

Console Access

Each unikernel provides a serial console for access:

  • Serial Console — a UNIX socket that libvirt binds under /opt/sherpa/run/console/. Connect with sherpa console <node> from any machine with the CLI; the connection goes through sherpad and only the lab's owner can open it. See Serial Console.

Info

Unikernels do not include a VNC graphics adapter. Serial console is the only access method.

Manifest Configuration

Unikernel nodes support the following unikernel-specific manifest parameters:

  • unikernel.cmdline — Kernel command line arguments passed to QEMU for DirectKernel unikernels. This overrides any auto-injected command line. Use this to specify the application entry point or pass runtime configuration to the unikernel.
  • ready_check.port — TCP port to probe on the node's management IP to verify readiness. By default, a unikernel is considered ready when its libvirt domain reaches the running state. When ready_check.port is set, Sherpa additionally waits for a successful TCP connection to the specified port.
[[nodes]]
name = "web01"
model = "unikraft_unikernel"
version = "v1.0.0"

[nodes.ready_check]
port = 80

[nodes.unikernel]
cmdline = "/usr/bin/nginx"

See the manifest documentation for all available node parameters.

Lifecycle

Operation Description
Create Domain XML is defined and the unikernel is started
Stop Unikernel is shut down via Libvirt
Resume Stopped unikernel is restarted
Destroy Domain is undefined and all associated disks are removed

Power behaviour:

  • On poweroff — unikernel is destroyed
  • On reboot — unikernel is restarted
  • On crash — unikernel is destroyed

Note

Unikernel nodes do not support the redeploy operation.