Managing Unikraft Ecosystem

Once kraft is installed, you can use it to manage dependencies for applications, including finding and retrieving existing applications, libraries, platforms and architectures.

Libraries are additional software components that will be linked with Unikraft for the final image. Each unikernel image is using its specific libraries. They are typically common libraries (such as OpenSSL or LWIP) that have been ported on top of Unikraft. The libraries, also called external libraries are located in specialized repositories in the Unikraft organization, those whose names start with lib-.

The application is the actual application code. It typically provides the main() function (or equivalent) and is reliant on Unikraft and external libraries. The avalaible applications that have been ported on top of Unikraft are located in repositories in the Unikraft organization, those whose names start with app-.

An important role of the core Unikraft component is providing support for different platforms and architectures. A platform is the virtualization / runtime environment used to run the resulting unikernel image.

Unikraft directories structure

By default, all components pulled by kraft are saved to ~/.unikraft/ directory, which is also the default value for the UK_WORKDIR environment variable used by kraft. This is the usual layout of the ~/.unikraft directory:

|-- apps - This is where you would normally place existing app builds
|-- archs - Here we place our custom arch's files
|-- libs - This is where the build system looks for external library pool sources
|-- plats - The files for our custom plats are placed here
`-- unikraft - The core source code of the Unikraft Unikernel

If you want to keep your unikraft components in a different location, you can do that and export the environment variable UK_WORKDIR. Apart from that, there are also environment variables available for the above subdirectories:

Environment Variable Purpouse Default
UK_ROOT The directory for Unikraft’s core source code $UK_WORKDIR/unikraft
UK_LIBS The directory of all the external Unikraft libraries $UK_WORKDIR/libs
UK_APPS The directory of all the template applications $UK_WORKDIR/apps

kraft list

You can find a list of all aplication, libraries and platforms by using:

$ kraft list

You can see the component name, current version, release date and the time of the last check. All the components already avalaible on your system, in your UK_WORKDIR directory will be shown green. All the other components will be colored red.

APPLICATIONS    	VERSION 	RELEASED  	LAST CHECKED
helloworld      	0.6     	22 Jan 22 	17 hours ago
httpreply       	0.6     	02 Dec 21 	17 hours ago
python3         	0.6     	2 days ago	17 hours ago
duktape         	0.6     	02 Dec 21 	17 hours ago
helloworld-cpp  	0.6     	02 Dec 21 	17 hours ago

You can add origins for kraft to use in the .kraftrc file, under [list]. If you create a new library using the kraft lib command shown below, you can add the new local library to the .kraftrc file by using:

$ kraft lib add ~/path/to/local/lib
$ kraft list update

You can check that everything worked fine and view basic informations about the new library by using:

$ kraft list show LIBNAME

You can manually add URLs, git, git+ssh and wildcards in the .kraftrc file:

[list]
origins = [
	"https://github.com/unikraft/unikraft.git",
	"https://github.com/unikraft/plat-*",
	"https://github.com/unikraft/app-*",
	"https://github.com/unikraft/lib-*",
]

After every update to .kraftrc, run:

$ kraft list update

You may get the following error when running kraft update:

GitHub rate limit exceeded. You can tell kraft to use a personal access token by setting the UK_KRAFT_GITHUB_TOKEN environmental variable.

In this case, create a GitHub personal access token and use the following command:

$ UK_KRAFT_GITHUB_TOKEN=<your_GitHub_token_here> kraft list update

Overview of kraft list command

Usage: kraft list [OPTIONS] COMMAND [ARGS]...

  Retrieves lists of available architectures, platforms, libraries and
  applications supported by unikraft.  Use this command if you wish to
  determine (and then later select) the possible targets for your unikraft
  application.

By default, this subcommand will list all possible targets.

Options:
  -i, --installed   Display only installed components.
  -c, --core        Display information about Unikraft's core repository.
  -p, --plats       List supported platforms.
  -l, --libs        List supported libraries.
  -a, --apps        List supported application runtime execution environments.
  -d, --show-local  Show local source path.
  -n, --paginate    Paginate output.
  -t, --this        Show the components for this application (default is cwd).
  --this=PATH       Show the components for this application.
  -j, --json        Return output as JSON.
  -h, --help        Show this message and exit.

Commands:
  add     Add a remote manifest or repository.
  pull    Pull the remote component to disk.
  remove  Remove a remote manifest or repository.
  show    Show a unikraft component.
  update  Update the list of remote components.

kraft init

If you want to initiate an existing application, you can use:

$ kraft init -t TEMPLATE_NAME [TARGET_NAME]

Overview of kraft init command

Usage: kraft init [OPTIONS] [NAME]

  Initializes a new unikraft application.

  Start here if this is your first time using (uni)kraft.

Options:
  -t, --template NAME  Use an existing application as a template.
  -p, --plat PLAT      Target platform.
  -m, --arch ARCH      Target architecture.
  -w, --workdir PATH   Specify an alternative directory for the application
                       [default is cwd].
  -M, --with-makefile  Create a Unikraft compatible Makefile.
  -D, --no-deps        Do not download additional dependencies for application
                       components.
  -d, --dump           Dump dependencies into project directory.
  -F, --force          Overwrite any existing files.
  -h, --help           Show this message and exit.

kraft up

You can retreive, build and run an existing appliication from the list above by using only one command:

$ kraft up -t TEMPLATE_NAME TARGET_NAME

Overview of kraft up command

Usage: kraft up [OPTIONS] NAME

  Configures, builds and runs an application for a selected architecture and
  platform.

Options:
  -w, --workdir PATH         Specify an alternative directory for the
                             application [default is cwd].
  -t, --template NAME        Use an existing application as a template.
                             [required]
  -p, --plat TEXT            Target platform.
  -m, --arch TEXT            Target architecture.
  -i, --initrd TEXT          Provide an init ramdisk.
  -B, --background           Run in background.
  -P, --paused               Run the application in paused state.
  -g, --gdb INTEGER          Run a GDB server for the guest on specified port.
  -d, --dbg                  Use unstriped unikernel
  -n, --virtio-nic TEXT      Attach a NAT-ed virtio-NIC to the guest.
  -b, --bridge TEXT          Attach a NAT-ed virtio-NIC an existing bridge.
  -V, --interface TEXT       Assign host device interface directly as virtio-
                             NIC to the guest.
  -D, --dry-run              Perform a dry run.
  -M, --memory INTEGER       Assign MB memory to the guest.
  -s, --cpu-sockets INTEGER  Number of guest CPU sockets.
  -c, --cpu-cores INTEGER    Number of guest cores per socket.
  -F, --force                Overwrite any existing files in current working
                             directory.
  -j, --fast                 Use all CPU cores to build the application.
  -M, --with-makefile        Create a Unikraft compatible Makefile.
  -h, --help                 Show this message and exit.

kraft lib

You can also use kraft to manage Unikraft libraries. You can add and remove libraries from the project:

$ kraft lib add NAME
$ kraft lib remove NAME

Or you can initialize a new Unikraft library using:

$ kraft lib init [OPTIONS] [NAME]

Overview of kraft lib command

Usage: kraft lib [OPTIONS] COMMAND [ARGS]...

  Unikraft library sub-commands are useful for maintaining and working directly with Unikraft libraries.

Options:
  -h, --help  Show this message and exit.

Commands:
  add     Add a library to the project.
  bump    Update a library's version (experimental).
  init    Initialize a new Unikraft library.
  remove  Remove a library from the project.