kraft is a runtime manager which allows you to instantiate and
manage multiple unikernel instances locally.
kraftonly supports running instances that target the KVM hypervisor either through QEMU or Firecracker. We plan on adding support for additional hypervisors including Xen, VMware and Hyper-V. For more information the progress of these hypervisors, you can track the relevant GitHub issue.
There are multiple ways to instantiate a unikernel with
kraft run has been designed to be context-aware and can be used in different ways to launch unikernels depending on what is provided to it.
kraft run command, you are able to launch an instance using an underlying hypervisor solution.
kraft run will interface with QEMU directly to instantiate a unikernel.
In some circumstances, for example in nested virtualization environments, it may not be possible to access hardware-level instruction sets (ISAs) to execute the unikernel. In this scenario, hardware emulation will be used and it should be noted that this has a significant penalty on runtime performance of the application.
Following a successful build of a unikernel, you can simply invoke the following without any additional flags when
cd'd within a project directory to preview the unikernel instance in action:
For long-running applications, typing Ctrl + C will only detach you from the application's stdout. See more about stopping and removing the unikernel instance.
In the above example, the offical "Hello, world" application was run.
It has multiple targets with varying platforms and architecture tuples.
kraft run was invoked, it intelligently detected information about the host system and suggested two possible targets based on the availability of QEMU on the system.
It is possible to pass directly to
kraft run in its first positional argument the path to a binary image.
In the example below, we execute a pre-built unikernel binary:
kraft run KERNEL
In the above example, the provided kernel matched the host's architecture.
kraft will attempt to intelligently determine whether it can run the supplied unikernel binary and select the appropriate hypervisor.
kraft run BINARY
In the above example, a pre-built ELF Loader application was dynamically downloaded and used to launch the pre-built
You can set the path to the ELF Loader application, either as an OCI Image reference or to a path on disk to a kernel image via the
For example, we provide an
strace-like image which is packaged as an OCI image and available publicly at
loaders.unikraft.org/strace:latest which is useful for debugging:
kraft run --elfloader loaders.unikraft.org/strace:latest BINARY
You can reference an OCI image unikernel as a positional argument with
kraft run which, if not present on the host machine, will be downloaded before it is executed. For example, to build an execute the official "Hello, world!" application from Unikraft, you can run:
kraft run unikraft.org/helloworld:latest
In most cases, applications are intended to be accessible over a network.
kraft is a network manager which allows you to create, modify and remove networks of varying implementation types.
kraftonly supports networks on Linux based on bridge networking.
To view existing networks, simply run:
kraft net ls
To create a new network, specify the address and range in CIDR notation with the
-n flag and a first positional argument representing the new network name:
kraft net create -n 126.96.36.199/24 kraft0
The first address in the CIDR network will become the gateway.
Once a network has been identified, you can attach this network to the unikernel instance with the
kraft run --network bridge:kraft0 unikraft.org/nginx:latest
In the above command, the
--network flag requires both the underlying driver implementation name,
driver, as well as the name of the network supported by the driver, in this case
kraft0, separated by a colon
-n|--network allows you to connect multiple unikernels to the same network, it can be also useful to simply port-forward from your host to a unikernel instance.
For example, when an NGINX unikernel exposes port
80 and you wish to map port
8080 on your localhost.
You can use the
-p flag to achieve this affect as follows:
kraft run -p 8080:80 unikraft.org/nginx:latest
In the above example, the NGINX instance will be available at http://localhost:8080/.
Learn more about mounting filesystems to the unikernel instance in our related rootfs documentation.
The unikernel instance essentially has two types of command-lines:
-c flag which sets the path in the root filesystem to the configuration file.
To set command-line arguments for either Unikraft or the application is done as the second positional argument to
kraft run or via the
kraft run unikraft.org/nginx:latest -c /nginx/conf/nginx.conf
To set command-line arguments for Unikraft, you simply need to separate with two dashes as a delimeter
--, for example:
kraft run unikraft.org/nginx:latest netdev.ipv4_addr=188.8.131.52 -- -c /nginx/conf/nginx.conf
To view the state of previously instantiated unikernel instances you can use the following:
NAME KERNEL ARGS CREATED STATUS MEM PLATbeautiful_bintijua project://helloworld 1 hour ago exited 64M qemu/x86_64elastic_guy oci://unikraft.org/nginx:latest 2 hours ago running 64M qemu/x86_64
The above command will display a
ps-like output which displays the name, the "source" of the unikernel (whether from a project context, a binary context, an ELF Loader context or an OCI image context), any command-line arguments supplied to it, when it was created, its state, how much memory was assigned to the instance, and which platform/architecture it is.
To view more detailed information about all instances, supply the
kraft ps --long
Possible states of a unikernel instance are:
|The instance's state could not be determined.
|The instance has been created but not started.
|The instance could not be created.
|The instance is in the process of rebooting.
|The instance is active and executing.
|The instance has been paused and is no longer executing.
|The instance has gracefully exited (whether successful or not.)
|The instance has non-gracefully exited, e.g. crashed or panicked.
To stop an instance that is actively executing, you simply need to reference its name which was either automatically generated or set via the
kraft stop NAME
To stop all actively executing instances, you can simply pass the
kraft stop --all
To remove a specific instance:
kraft rm NAME
And to remove all instances, similarly pass the
kraft rm --all
kraft rmwill gracefully stop the unikernel instance(s) before it is removed.
Feel free to ask questions, report issues, and meet new people.