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.

1. build: You execute unikraft build with the --output flag. This single command reads your Dockerfile or Kraftfile, compiles the app locally, packages the resulting files into an OCI image, and uploads that image directly to the Unikraft Cloud registry.

2. run: You execute unikraft run and provide the uploaded image name. The Unikraft Cloud controller pulls the image from the registry, allocates the necessary system resources, and starts your app as a running instance.

Dockerfiles, Kraftfiles and runtimes

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:

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

The directory contains the following Kraftfile:

Kraftfile
spec: v0.7

runtime: base-compat:latest

rootfs:
  source: ./Dockerfile
  format: erofs

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

The file is simple. It defines the start command, instructs the unikraft CLI to build the root filesystem, and specifies the base-compat runtime. On Unikraft Cloud, a runtime provides a base image containing the minimal code your app needs to execute. The unikraft 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. The erofs format decompresses data block-by-block only when the system accesses it. This selective approach saves RAM and improves boot times. In contrast, the cpio format must remove its entire contents into memory on startup. Check out this tutorial comparing rootfs types to understand why Unikraft favors erofs. For a more in depth explanation of the Kraftfile you can check the reference

The Dockerfile itself for the app looks as follows:

Dockerfile
FROM python:3.12 AS build

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

FROM scratch

# copy the dependencies from the base image
COPY --from=build /usr/local/lib /usr/local/lib
COPY --from=build /usr/local/bin/python3 /usr/bin/python3
COPY --from=build /lib/x86_64-linux-gnu/libc.so.6 /lib/x86_64-linux-gnu/libc.so.6
COPY --from=build /lib/x86_64-linux-gnu/libm.so.6 /lib/x86_64-linux-gnu/libm.so.6
COPY --from=build /usr/lib/x86_64-linux-gnu/libz.so.1 /usr/lib/x86_64-linux-gnu/libz.so.1
COPY --from=build /usr/lib/x86_64-linux-gnu/libcrypto.so.3 /usr/lib/x86_64-linux-gnu/libcrypto.so.3
COPY --from=build /lib64/ld-linux-x86-64.so.2 /lib64/ld-linux-x86-64.so.2
COPY --from=build /etc/ld.so.cache /etc/ld.so.cache

# 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 container. 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.

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 controller 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.

REST API reference

List images from local registry

Base address: https://api.<node-name>.unikraft.cloud/v1

Code
GET /image-store

Returns all images accessible for your account and known by the platform from the local registry. Each image object includes:

Field	Type	Description
created_at	timestamp	Creation time.
owner	string	Owner of the image (omitted if not root account).
url	string	Full image address (includes digest).
tags	array of strings	List of shortened tags.
initrd_or_rom	bool	Whether the image includes an initrd or ROM component.
size_in_bytes	int64	Total image size in bytes.
args	array of strings	Default arguments (omitted if none).
env	map of strings	Default environmental variables (omitted if none).
users	array of strings	Users with access to the image (omitted if not root account).

List images from central registry

Base address https://controlplane.unikraft.cloud/v1

Code
GET /images

Returns all images accessible for your account and known by the platform from the central registry.

Field	Type	Description
name	string	Image reference ({owner}/{registry}/{image}). Excludes digest and tag.

Learn more

• The CLI reference and the legacy CLI reference.
• Unikraft Cloud's REST API reference.