Package management with
kraft is handled through the
pkg subcommand which
offers convenient mechanisms for retrieving, packaging and distributing
components used during the formation of unikernels based on Unikraft.
kraft pkg can also help retrieve or distribute completely pre-built unikernels ready
To get started building unikernels or accessing pre-built unikernels, we must
first learn how we can retrieve one or many of these components using
By default and when left unconfigured,
kraft will retrieve a list of official
Unikraft library components that can be used later on when building a
unikernel. The first step is to retrieve the latest information about these
components. Simply run:
kraft pkg update
It is recommended to regularly run
kraft pkg update as Unikraft regularly
updates its components with new features, bug fixes, newly supported
applications, libraries, etc. See Unikraft's release schedule.
In some cases, such as with
kraft build, updating is done implicitly before the command's main functionality is executed. Because of this, in some subcommands, a
--no-updateflag is offered to prevent this operation from occurring.
Unikraft ships (and
kraft allows you to ship) packages of different component
types. A component is a building block, and ultimately a code base, repository
or distributable archive or binary, which is used within the Unikraft ecosystem.
Components are one of 5 unique types:
|A repository containing the Unikraft core codebase which consists of a Make and KConfig-based build system. The Unikraft core provides the glue for stiching other components as well as your application together.
|The component that defines behavior and hardware interactions specific to the target architecture.
|A repository containing code that defines the interaction with the underlying hardware, depending on whether a hypervisor is present or not, and which hypervisor is present.
|A repository containing a Unikraft external library, that defines an user-space functionality.
|The final component type is that of a fully functioning unikernel. The
app component defines the use of the
plat combination, as well as a list of
kraft are programmable package managers that allows you to fetch
resources that either comprise of library components (distributed through the
KraftKit manifest specification) of a unikernel or
fully pre-built unikernels (distributed using the OCI Image
A manifest-based package is a simple representation of a component that is one of three distributable types:
It is possible to access pre-built and to distribute yourself unikernel images using the OCI Image Specification. This feature enables you to use existing registries to store and distribute unikernel images quickly and easily.
Built in to
kraft is a reference to our public-access OCI registry which is
hosted simply at
unikraft.org. To access unikernel images in another
registry, simply add it as a source.
You can configure different backends for OCI images, the default is
directory-based and will store the artifacts locally on disk. Alternatively,
you can use containerd as a backend by setting
containerd_addr to the daemon socket in the global
You can list all packages and components with:
kraft pkg list
To view the latest applications distributed as OCI images that are provided by the Unikraft OSS Project's registry, simply run the following:
kraft pkg ls -u --apps
The above command lists components by
--apps and requests an update
-u|--update) such that it queries the remote registry.
By default, you do not need to source any additional repositories or manifests if you have a freshly installed version of
kraftand simply wish to get started using existing applications, libraries or the Unikraft core based on the publicly available and official channels.
To manage components with
kraft, we must first know where we can find them.
This is done by "sourcing" them from a remote location with:
kraft pkg source SOURCE
SOURCE is, for example:
# Source a component represented as a public Git repositorykraft pkg source https://github.com/unikraft/lib-lwip.git# Sourcing a private Git repositorykraft pkg source email@example.com:unikraft/lib-mylib.git# Sourcing a manifest (index) of packageskraft pkg source https://manifests.kraftkit.sh/index.yaml# Sourcing a manifest of a single packagekraft pkg source https://manifests.kraftkit.sh/lib/lwip.yaml# Source an OCI registrykraft pkg source localhost:3000
In the above example, there are three types of sources:
Git repositories representing a component: When sourcing repositories
directly, e.g. when you wish to use a git repository representing a
kraft pkg source will attempt to determine the component type
with the naming convention
kraft pkg source --help for more information about how to correctly
annotate sources with unconventional names.
Manifests: It is possible to pass
kraft pkg source a local path on disk
or a remote URL to a Manifest file which
represents either a list of components or a single component.
The officially maintained manifest for all Unikraft components (and default manifest if KraftKit is left unconfigured) is:
OCI Registries: It is possible to add a reference to a remote OCI registry to view pre-built unikernel images.
To remove a source, you can unsource it by invoking:
kraft pkg unsource [SOURCE]
kraft pkg unsource without the optional
argument (which must be an exact match) you will be prompted to interactively
select which source(s) you would like to remove from KraftKit.
To cache a package locally on your machine either for multiple uses or within the context of a project's build, you can use:
kraft pkg pull [PACKAGE]
Without any flags, the above command will store a copy in the manifest cache
directory. When used with
-w, it will save it in the context of a
Once you have successfully built a Unikraft unikernel and
you wish to distribute your application, you can use the top-level
subcommand. Left without any arguments, the command will use information
supplied in the
Kraftfile to determine how to package the artifact(s):
# Simply invoke kraft pkg within the application directorykraft pkg# Or pass a path to a an application directorykraft pkg path/to/my/app
To package your image as an OCI image, you can force the type and OCI Image Reference name (or tag) to be used:
kraft pkg --as oci --name unikraft.org/helloworld:latest
In the above example, a "Hello, world!"
project with a single target
qemu/x86_64) is packaged as an OCI image with the name
If your project has multiple targets, each built target will be packaged together to produce a multi-platform image.
Once packaged, it is possible to push the resulting image to the remote registry. Simply invoke:
kraft pkg push unikraft.org/helloworld:latest
Feel free to ask questions, report issues, and meet new people.