KraftKit Documentation

KraftKit allows you to package and distribute Unikraft unikernels using the Open Container Image (OCI) Image Specification. This enables the use of existing container infrastructure for distributing pre-built unikernel images.

In the KraftKit OCI implementation, the top-level element is an index containing a list of manifests. Each manifest represents a pre-built unikernel image paired with its accompanying root filesystem.

kraft pkg --name helloworld:latest --with-kconfig --plat qemu

KraftKit supports two backends for manipulating and storing OCI images:

1. directory (default): Represents the OCI image as a directory structure on the host system. Artifacts are stored under /root/.local/share/kraftkit/runtime/oci (or the user's local share directory), organized into indexes/ and digests/ folders.
2. containerd: Uses the containerd content storage system. This requires specific configuration in the KraftKit config file.

KraftKit's Xen functionality relies on a specific relationship between the Xen hypervisor and the KraftKit library. While they are decoupled, they must remain within an acceptable version distance to function correctly.

Currently, KraftKit has confirmed integration with Xen 4.19 and potentially 4.20-rc versions. If you need to use a different version, KraftKit must be recompiled specifically for that version.

You can install KraftKit using an interactive shell script or by downloading binaries directly from the GitHub releases page. The shell script is the quickest way to get started on most systems.

curl --proto '=https' --tlsv1.2 -sSf https://get.kraftkit.sh | sh

You can build a unikernel by creating a Kraftfile in your repository that points to an existing Dockerfile. This allows you to leverage standard container definitions to produce a unikernel.

1. Create a Kraftfile with the following structure:

spec: v0.6

runtime: base:latest

rootfs: ./Dockerfile

cmd: ["/path/to/my-server-app"]

2. Run the build and execution command from the directory containing the Kraftfile:

kraft run .

The unikraft/export package provides C-bindings for Unikraft, allowing Go applications built on top of Unikraft to interact with Unikraft internal structures.

This package serves two primary purposes:

1. It allows KraftKit internals to reference Unikraft structures during unikernel manifestation (compile-time or runtime).
2. It enables Go developers to directly reference Unikraft internals, bypassing general-purpose syscall boundaries.

Note on Stability: This package is currently a work-in-progress. All exported libraries, constants, variables, and methods are prefixed with a v0 suffix to indicate they are unstable and subject to change. Once Unikraft reaches v1.0, these exports will transition to stable APIs.

import "kraftkit.sh/unikraft/export/v0"

If you prefer not to install dependencies directly on your host, you can use the KraftKit container build environment. This environment includes the kraft binary and all necessary tools/libraries for building Unikraft unikernels.

To use it, run the kraftkit.sh/base:latest image and mount your local working directory to /workspace inside the container.

docker run -it --rm -v $(pwd):/workspace --entrypoint bash kraftkit.sh/base:latest

If you need to use a Xen version older than 4.19 (e.g., 4.18), you must recompile the KraftKit build environment and the KraftKit binary itself.

Note: You must use sudo when interacting with Xen during runtime.

```console
# 1. Update version references in the source
find . -type f -exec sed -i 's/4.19/4.18/g' {} +

# 2. Fetch the corresponding library version
go get -u xenbits.xenproject.org/git-http/xen.git/tools/golang/xenlight@RELEASE-4.18.0 && go mod tidy

# 3. Rebuild the KraftKit build environment
make buildenv-xen buildenv-myself-full buildenv-myself

# 4. Start the build container
docker run --rm -it --entrypoint /bin/bash -v .:/tmp/kraftkit kraftkit.sh/myself-full:latest

# 5. Rebuild KraftKit inside the container
cd /tmp/kraftkit && make kraft

After completion, your binary will be located at dist/kraft.

To use the Hyperlight machine driver in KraftKit, you must satisfy host requirements and install the hyperlight-unikraft binary on your $PATH.

Requirements

• Linux: Requires read/write access to /dev/kvm.
• Windows: Requires the Windows Hypervisor Platform (WHP) to be enabled.
• Kernel: Unikraft kernels must be built specifically for the hyperlight platform target.

Installation

Install the hyperlight-unikraft binary using Cargo:

cargo install --git https://github.com/hyperlight-dev/hyperlight-unikraft \
    --branch main hyperlight-unikraft-host --bin hyperlight-unikraft

The Hyperlight driver registers two platform names that can be used with the --plat flag during kraft build or kraft run commands:

• hyperlight (canonical name)
• hl (shorthand)

Examples

# Build for hyperlight
kraft build --plat hyperlight --arch x86_64

# Run using the shorthand
kraft run --plat hl ...