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.
Limited Access
The local registry is only available in BYOC or on-prem Unikraft Cloud installations.
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
The directory contains the following Kraftfile:
Kraftfile
The file is simple.
It defines the start command, instructs the CLI to build the root filesystem, and specifies the base-compat:latest runtime.
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:
Dockerfile
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.
You can also try a standard base image (for example, FROM python:alpine).
This is a good start for porting existing Dockerfiles to Unikraft Cloud.
Be aware that this choice may increase image size, memory use, and boot time.
Example workflows
This guide uses a Python app as an example to show three workflows:
- How to create an image and launch an instance from it.
- How to create an image and launch many instances from it.
- 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:
There may be a delay of a few minutes between removing an image from the registry and the image list reflecting the change.
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.