Kraftfilewhich is used to configure, build and package your application as a Unikraft unikernel.
This document does NOT contain the latest
Kraftfilespecification information, please refer to this document for the latest information.
Kraftfile is the static configuration file used to programmatically build
and package a unikernel using
kraft. This file contains information about the
Unikraft core build system, third-party libraries, all configuration options
which are used for the build and a list of possible targets for the application.
Kraftfile is typically found at the top-level of a repository. It is
possible to change this location with additional flags found in
Kraftfile acts as the initialization for the configuration of the
unikernel, including the source location of the Unikraft core and any auxiliary
third-party libraries that are necessary for your application (e.g. OpenSSL).
For legacy reasons, the following file names are recognized by
Kraftfile is the latest preferred name:
Kraftfiles MUST include a top-level
specification attribute which is
kraft to both validate as well as correctly parse the rest of the
file. The latest specification number is
specification: v0.5name: helloworld
Finally, an application
name CAN specified. When no
name attribute is
specified, the directory's base name is used as the name.
unikraft attribute MUST be specified and is used to define the source
location of the Unikraft core which
contains the main build system and core primitives for connecting your
application as well as any third-party libraries or drivers.
In all cases, there are two forms of syntax that can be used in the
known as "short-hand" and "long-hand" depending on preference.
The attribute can be specified in multiple ways, the most common is simply to request the latest from a "stable" channel of Unikraft, e.g.:
specification: v0.5name: helloworld# Short-hand syntaxunikraft: stable# Long-hand syntaxunikraft:version: stable
The Unikraft project adopts two-channel release mode via
staging. Specifying the latter will provide to you bleeding-edge version of Unikraft.
To specify a specific version of Unikraft, including a specific Git commit, you simply set it as follows:
specification: v0.5name: helloworld# Short-hand for a specific version of Unikraftunikraft: v0.14.0# Long-hand for a specific version of Unikraftunikraft:version: v0.14.0# Short-hand for a specific commit of Unikraftunikraft: 70bc0af# Long-hand for a specific commit of Unikraftunikraft:version: 70bc0af
If you wish to use a copy of the Unikraft core code which is a remote fork or mirror, it is possible to set this as the entry for the attribute. When specified like so, the top of the HEAD of the default branch will be used:
specification: v0.5name: helloworld# Short-hand syntaxunikraft: https://github.com/unikraft/unikraft.git# Long-hand syntaxunikraft:source: https://github.com/unikraft/unikraft.git
Alternatively, a specific tag, branch or Git SHA can be specified by setting:
specification: v0.5name: helloworld# Short-hand syntax for a specific branchunikraft: https://github.com/unikraft/unikraft.git@staging# Long-hand syntax for a specific branchunikraft:source: https://github.com/unikraft/unikraft.gitversion: staging# Short-hand syntax for a specific tagunikraft: https://github.com/unikraft/unikraft.git@RELEASE-0.14.0# Long-hand syntax for a specific taunikraft:source: https://github.com/unikraft/unikraft.gitversion: RELEASE-0.14.0# Short-hand syntax for a specific commitunikraft: https://github.com/unikraft/unikraft.git@70bc0af# Long-hand syntax for a specific commitunikraft:source: https://github.com/unikraft/unikraft.gitversion: 70bc0af0bd1c74b3af3c0584d7b7373dc42b2ce7
It is possible to access remote repositories which requires authentication over SSH, simply set this as part of the scheme:
specification: v0.5name: helloworld# Short-hand syntax for specifying an authenticated Git repository over SSH,# which will select the default branchunikraft: ssh://email@example.com/unikraft/unikraft.git# Long-hand syntax for specifying an authenticated Git repository over SSH, and# specifying a specific branch (or tag)unikraft:source: ssh://firstname.lastname@example.org/unikraft/unikraft.gitversion: staging
To use Git authentication over SSH, you must start an SSH agent before invoking
kraft, for example:eval `ssh-agent`ssh-add ~/.ssh/id_ed25519
Finally, it is possible to set the location of Unikraft's core to a path on the host. This is useful when you are hacking at the core directly or working whilst traveling and do not have access to an internet connection:
specification: v0.5name: helloworld# Short-hand sytnax for a specific path on diskunikraft: path/to/unikraft# Long-hand syntax for a specific path on diskunikraft:source: path/to/unikraft
To declare any specific options from Unikraft's configuration system, you must
always use the long-hand syntax. All KConfig options start with
can be set in either list format with key and value delimetered with an equal
=) symbol or in map format:
specification: v0.5name: helloworld# Using list-style formattingunikraft:kconfig:- CONFIG_EXAMPLE=y# Using map-style formattingunikraft:kconfig:CONFIG_EXAMPLE: "y"
All three sub-attributes,
kconfig, can be used
together to generate a very specific definition of the Unikraft core:
specification: v0.5name: helloworldunikraft:source: https://github.com/unikraft/unikraft.gitversion: stablekconfig:CONFIG_EXAMPLE: "y"
Additional third-party libraries CAN be specified as part of the build and are
listed in map-format. Similar to the
unikraft attribute, each library can
version and a set of
kconfig options, for example:
specification: v0.5name: helloworldunikraft: stablelibraries:# Short-hand syntax for specifying the library "musl" on the stable channelmusl: stable# Long-hand syntax for specifying a library at a specified source, using a# specific Git branch, and specifying additional KConfig optionslwip:source: https://github.com/unikraft/lib-lwip.gitversion: stablekconfig:CONFIG_LWIP_AUTOIFACE: "y"CONFIG_LWIP_DHCP: "y"CONFIG_LWIP_DNS: "y"CONFIG_LWIP_IPV4: "y"CONFIG_LWIP_SOCKET: "y"CONFIG_LWIP_TCP_KEEPALIVE: "y"CONFIG_LWIP_TCP: "y"CONFIG_LWIP_THREADS: "y"CONFIG_LWIP_UKNETDEV: "y"CONFIG_LWIP_WND_SCALE: "y"
A target is defined as a specific destination that the resulting unikernel is
destined for and consists at minimum of a specific platform (e.g.
firecracker) and architecture (e.g.
arm64) tuple. A project can
have multiple targets depending on use case but MUST have at least one.
Each target consists of at minimum an architecture and platform combination,
therefore a project with two targets of
specification: v0.5name: helloworldunikraft: stabletargets:- platform: qemuarchitecture: x86_64- platform: xenarchitecture: arm64
When left without any flags,
kraft build will prompt you for the intended
target to build.
It is possible to define targets simply based on different runtime properties or
requirements. This is possible by setting both a
name sub-attribute and a set
kconfig options, for example the following two targets both target
qemu/x86_64 platform/architecture tuple but initialize the rootfs either based
on 9pfs or initrd, respectively:
specification: v0.5name: helloworldunikraft: stabletargets:- name: helloworld-qemu-x86_64-9pfsplatform: qemuarchitecture: x86_64kconfig:CONFIG_LIBVFSCORE_AUTOMOUNT_ROOTFS: "y"CONFIG_LIBVFSCORE_ROOTFS_9PFS: "y"CONFIG_LIBVFSCORE_ROOTFS: "9pfs"CONFIG_LIBVFSCORE_ROOTDEV: "fs0"- name: helloworld-qemu-x86_64-initrdplatform: qemuarchitecture: x86_64kconfig:CONFIG_LIBVFSCORE_AUTOMOUNT_ROOTFS: "y"CONFIG_LIBVFSCORE_ROOTFS_INITRD: "y"CONFIG_LIBVFSCORE_ROOTFS: "initrd"
Feel free to ask questions, report issues, and meet new people.