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.
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 theunikernel.cmdlinemanifest 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:
- Copy the kernel ELF from the image store into the storage pool
- Generate a libvirt domain XML definition with the copied kernel path and optional
unikernel.cmdline - Define and start the domain via the Libvirt API
- Copy the disk image from the image store into the storage pool
- Resize the boot disk if
boot_disk.sizeis specified in the manifest - Generate a libvirt domain XML definition from the node's parameters
- 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 withsherpa console <node>from any machine with the CLI; the connection goes throughsherpadand 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. Whenready_check.portis 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.