Copy page

Cloud Platform

Images

Unikraft Cloud uses a registry to store images used to instantiate apps. At a high level, you use the CLI to build and push an image to the registry, and then ask the controller to start an app from it.

This process utilizes two types of registries: central and local. Built images default to the central registry (index.unikraft.io). The platform pulls from this registry automatically upon starting an instance for the first time.

You can choose to push an image directly to a node's local registry instead. This bypasses the central registry entirely. Skipping this extra network round trip speeds up deployments. It also reduces bandwidth consumption. Read more about this in the registries documentation.

Dockerfile, Kraftfile and runtime

On Unikraft Cloud, a Dockerfile guides the process of building images, and a Kraftfile guides the process of deploying the resulting image.

Use the Python running example:

Code
git clone https://github.com/unikraft-cloud/examples
cd examples/httpserver-python3.12

The directory contains the following Kraftfile:

Code
spec: v0.7

runtime: base-compat:latest

targets:
  - kraftcloud/x86_64

rootfs:
  source: ./Dockerfile
  format: erofs

cmd: ["/usr/bin/python3", "/src/server.py"]

The file is simple. It defines the start command, instructs the CLI to build the root filesystem, specifies the base-compat:latest runtime, and targets kraftcloud on x86_64.

On Unikraft Cloud, a runtime provides a base image containing the minimal code your app needs to execute. The CLI combines your app files with this base image during the build step. It uses the Dockerfile as the source to generate the directory structure. When packaging these files into a root filesystem, Unikraft offers two main options: CPIO and EROFS. The file specifies the EROFS format to create a read-only disk image, which is the preferred format for Unikraft Cloud. For a more in depth explanation of the Kraftfile you can check the reference.

The Dockerfile itself for the app looks as follows:

Code
FROM python:3.12 AS build

RUN set -xe; \
    /usr/sbin/ldconfig /usr/local/lib

# copy the python image
COPY ./server.py /src/server.py

If you're familiar with Dockerfiles there is nothing unusual here, other than that Unikraft Cloud prefers usage of FROM scratch to keep images lean.

This multi-stage build creates a minimal image. First, the process loads a standard Python 3.12 image to configure system dependencies. Next, it starts an empty filesystem called scratch. The builder extracts the compiled Python binary and essential shared system libraries from the first stage. It moves these exact files into the empty environment. Finally, the builder copies your app script into the container. To add your app's code to the build, change the COPY commands as needed.

All guides on Unikraft Cloud, and the examples they rely on underneath come with Kraftfiles and Dockerfiles for you to get started.

Platform kernel

An image doesn't have to carry its own kernel. An image that ships only a rootfs boots on the kernel installed on the node, which your metro operator maintains as a separate package. Images that do ship a kernel keep working exactly as before.

This decouples the guest kernel from your app. A kernel update, including a security fix, becomes available to workloads that cold-boot after the operator rolls out the new kernel package. You no longer rebuild and re-push every image to pick one up. Images also get smaller, which shortens image pull times.

A new kernel on the node applies to the next instance that starts. Running instances keep the kernel they booted with until they fully shut down, and an instance resuming from a snapshot always boots the kernel that snapshot captured.

Architectures

The Unikraft Cloud platform runs on both x86_64 and arm64 hosts, and the hosted platform runs on x86_64. The architecture of the guest images must match the host architecture.

List the architectures you want under targets in the Kraftfile:

Code
spec: v0.7

runtime: base-compat:latest

targets:
  - kraftcloud/x86_64
  - kraftcloud/arm64

rootfs:
  source: ./Dockerfile
  format: erofs

cmd: ["/usr/bin/python3", "/src/server.py"]

A single unikraft build invocation then produces an image for every architecture in the list. The --arch flag names architectures on the command line instead, which is handy for narrowing a multi-architecture Kraftfile down to one architecture.

How the build resolves architectures depends on what the Kraftfile declares:

Kraftfile	Architectures used
runtime with no targets or --arch	Every architecture the runtime provides.
runtime with targets or --arch	Only the architectures listed in both targets and --arch, which must be ones the runtime provides.
roms with no runtime	Only the architectures listed in both targets and --arch, and the build fails when you supply neither.

Example workflows

This guide uses a Python app as an example to show three workflows:

1. How to create an image and launch an instance from it.
2. How to create an image and launch many instances from it.
3. How to launch instances from an existing image.

Create an image and an instance from it

Start with the simplest workflow: create an image from a Python app and start an instance from it:

The output should look like:

This command builds an image named httpserver-python312@sha256:278cb8b1... using the Kraftfile and Dockerfile. It then packages it, pushes it to the registry, and starts an instance named httpserver-python312-ma2i9 from it. The platform fetches the image from the registry to start the instance.

You can see your images by running the following command:

You should see output like:

And you can remove an image from the central registry with the following command:

Create an image and many instances from it

For the next workflow, start many instances:

Check that it worked by listing all instances with:

Three instances run—the original plus two replicas.

Create instances from an existing image

In this final workflow, take the existing image and start new instances from it:

You now have a new instance created from the existing image.

Learn more

• The CLI reference and the legacy CLI reference.
• Unikraft Cloud's REST API reference.
• Porting an existing container app to Unikraft Cloud.
• Tutorial explaining the difference of storage media on Unikraft Cloud.
• Rootfs image formats.
• Rootfs image compression.