Copy page

Tutorials

KraftKit To Unikraft

This tutorial shows how to migrate from the legacy kraft cloud CLI to the new unikraft CLI for Unikraft Cloud. It focuses on the differences that matter during day-to-day work: authentication, profiles, deployment flow, common commands, and flag behaviour.

Prerequisites

Make sure you have the new CLI installed. See the unikraft CLI overview for installation instructions. If you still need the legacy syntax during the migration, keep the legacy CLI overview nearby for reference.

Main mental shift

The biggest change is that the legacy CLI combines packaging and deployment into a single command, while the new CLI treats them as separate operations.

In the legacy flow:

kraft
kraft cloud deploy -p 443:8080/http+tls -M 512Mi --rootfs-type erofs .

the CLI reads the local project, builds the root filesystem and image if needed, pushes it, and starts an instance.

In the new flow, the CLI splits the same work into two clearer stages:

unikraft
unikraft build . --output <my-org>/my-app:latest
unikraft run --metro=fra -p 443:8080/http+tls -m 512M --image=<my-org>/my-app:latest

This split has two practical consequences:

• unikraft build is where you package the image and store it in a registry.
• unikraft run is where you create an instance from an existing image and set runtime options such as ports, memory, scale-to-zero, volumes, and environment variables.

That separation makes the deployment flow more explicit. It also means you need to think about whether a flag belongs to image creation time or instance runtime.

Login and authentication

Public Unikraft Cloud

For the public service, the new CLI uses an interactive login flow that opens a browser window to authenticate with the Unikraft Cloud dashboard. The legacy CLI relies on environment variables to store the access token and metro selection.

The environment variables UKC_TOKEN and UKC_METRO are only supported by the legacy CLI. They aren't the normal way to authenticate with the new CLI.

Profile management

The new CLI uses profiles to manage authentication and configuration for different environments. The default profile contains all the publicly available metros:

Code
unikraft profile list

Code
NAME     ACTIVE  METROS
default  true    ["fra0", "dal0", "sin0", "was1", "fra", "dal", "sin", "was", "sfo"]

Thus, listing instances with unikraft is more convenient than with kraft cloud:

Write operations require an explicit metro selection with --metro:

unikraft
unikraft run --metro=fra -p 443:8080/http+tls -m 512MiB --image=<my-org>/my-app:latest

For custom or private metros, define a profile in ~/.config/unikraft/config.yaml:

config.yaml
profiles:
  <metro_subdomain>:
    type: cloud
    token: <ukc_token>
    organization: <ukc_user>
    metros:
      - name: <metro_subdomain>
        endpoint: https://api.<metro_subdomain>.unikraft.cloud
        country: <country_code>

Then select it explicitly:

unikraft
unikraft profile use <metro_subdomain>
unikraft profile list

Translate the most common commands

Use the following mappings as a quick migration reference.

Log in

Select a configured environment

Build and push an image

Run an instance from an image

List instances

Remove an instance

Create a volume

Flags differences

Memory units

Memory units behave differently in the new CLI.

unikraft only accepts units in the binary system, for example, 512M or 512MiB for Mebibytes. The legacy kraft cloud works with the decimal system as well—so 512M would mean 512 Megabytes, which is about 488 Mebibytes, while 512Mi would mean 512 Mebibytes, which is about 536 Megabytes.

Scale-to-zero

The new CLI folds three legacy switches into one structured flag:

Not specifying any scale-to-zero configuration means don't scale-to-zero. Note that, besides policy, each of the options for scale-to-zero are optional.

Filtering and waiting

The new CLI adds a rich filter language for many commands. For example:

Code
unikraft instances list --filter 'state==running,metro==fra'

and:

Code
unikraft instance wait my-instance --until state==running

These --filter and --until expressions are features of the new CLI. They aren't available in the legacy kraft cloud CLI. See Filters for the full syntax.

A side-by-side migration example

Suppose your old workflow looked like this:

kraft
# do this once in every terminal session
export UKC_TOKEN=token
export UKC_METRO=fra

kraft cloud deploy -n my-app -p 443:8080/http+tls -M 512Mi -e APP_ENV=production .
kraft cloud instance get my-app
kraft cloud instance logs my-app -f
kraft cloud instance remove my-app

The migrated workflow is:

unikraft
unikraft build . --output <my-org>/my-app:latest
unikraft run --metro=fra -n my-app -p 443:8080/http+tls -m 512M -e APP_ENV=production --image=<my-org>/my-app:latest
unikraft instances get my-app
unikraft instance logs my-app -f
unikraft instances delete my-app

Note the absence of environment variable exports in the new CLI, which uses persistent profiles instead.

Migration checklist

When moving an existing guide, script, or workshop from kraft cloud to unikraft, check the following:

• Replace kraft cloud deploy with unikraft build plus unikraft run;
• Move the local path such as . to unikraft build;
• Add an explicit image reference with --output on build and --image on run;
• Replace legacy authentication environment variables with unikraft login or a configured profile;
• Move run-time flags such as memory, ports, env vars, volumes, and scale-to-zero settings to unikraft run;
• Translate legacy scale-to-zero flags into the structured --scale-to-zero syntax;
• Update instance management commands such as list and delete to the new command names;
• Take advantage of new --filter and --until flags where they simplify scripts.

When to keep using the legacy CLI

The unikraft CLI is the recommended default for new workflows leveraging the latest features and improvements. That said, the legacy CLI can still make sense if you depend on existing Compose-oriented flows (kraft cloud compose) or you need time to migrate automation gradually.

Another reason to keep using kraft is for local development. Through kraft pkg and kraft run, you can run Unikraft unikernels locally, and it remains the preferred CLI for that use case.

Learn more

Use the --help option for detailed information on using Unikraft Cloud:

For more details, check the following references:

• The unikraft CLI overview.
• The legacy CLI overview.
• The Filters reference for the new filtering language.
• The Environment Variables tutorial for runtime configuration patterns.