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.
- build:
kraftbuilds the app locally according to aDockerfile. - pkg:
kraftpackages the app locally into an OCI image. - push:
kraftpushes the OCI image to the Unikraft Cloud registry. - create: The controller instantiates your app from the image according to a
Kraftfile.
The simplest way to run this workflow is to use a single deploy or run command, which combines all steps into one flow. Internally, the command calls other subcommands. The service in the diagram is the mechanism to connect apps to the Internet. Read more in the services guide.
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:
The directory contains the following Kraftfile:
Kraftfile
The file is simple: it defines the start cmd, instructs kraft to build the root filesystem with a Dockerfile, and specifies the python3.12 runtime.
On Unikraft Cloud, a runtime is a base image that contains the (minimal) code needed for the app (in this case the Python interpreter) to run.
Unikraft Cloud then overlays your app code on top of it during the packaging step.
The Dockerfile itself for the app looks as follows:
Dockerfile
If you're familiar with Dockerfiles there is nothing unusual here, other than that by default Unikraft Cloud uses FROM scratch to keep images lean.
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 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 (following the Python app guide) and start an instance from it:
The output should look like:
This command builds an image named http-python312@sha256:278cb8b1... using the Kraftfile and Dockerfile.
It then packages it, pushes it to the registry, and starts an instance named http-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 registry via the legacy CLI:
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.
REST API reference
List images
Code
Returns all images accessible for your account and known by the platform. Each image object includes:
| Field | Type | Description |
|---|---|---|
uuid | string | Image UUID. |
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). |
Look up by UUID
Code
Returns one or more images by UUID.
Look up by digest
Code
Pass a digest string in the request body to return the image matching that digest:
GET /images
The response includes url, tags, initrd_or_rom, size_in_bytes, argsandenv`.
Look up by tag
Code
Pass a tag string in the request body to return the image matching that tag:
GET /images
The response includes url, tags, initrd_or_rom, size_in_bytes, argsandenv`.
Learn more
- The CLI reference and the legacy CLI reference.
- Unikraft Cloud's REST API reference.