Cloud Platform

Images

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

1. build: kraft builds the app locally according to a Dockerfile.
2. pkg: kraft packages the app locally into an OCI image.
3. push: kraft pushes the OCI image to the Unikraft Cloud registry.
4. create: The controller instantiates your app from the image according to a Kraftfile.

The simplest way to run this workflow is to use kraft cloud deploy, which combines all steps into one command. Internally, the deploy 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:

(bash)
 
git clone https://github.com/unikraft-cloud/examples
cd examples/http-python3.12

The directory contains the following Kraftfile:

Kraftfile(yaml)
 
spec: v0.6

runtime: python:3.12

rootfs: ./Dockerfile

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

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
 
FROM scratch

# Python HTTP server
COPY ./server.py /src/server.py

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.

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 (following the Python app guide) and start an instance from it with a single kraft cloud deploy command:

(bash)
 
git clone https://github.com/unikraft-cloud/examples
cd examples/http-python3.12
kraft cloud deploy -p 443:8080 -M 512 .

The output should look like:

(ansi)
 
[●] Deployed successfully!
 │
 ├────────── name: http-python312-ma2i9
 ├────────── uuid: e7389eee-9808-4152-b2ec-1f3c0541fd05
 ├───────── state: running
 ├─────────── url: https://young-night-5fpf0jj8.fra.unikraft.app
 ├───────── image: [username]]/http-python312@sha256:278cb8b14f9faf9c2702dddd8bfb6124912d82c11b4a2c6590b6e32fc4049472
 ├───── boot time: 15.09 ms
 ├──────── memory: 512 MiB
 ├─────── service: young-night-5fpf0jj8
 ├── private fqdn: http-python312-ma2i9.internal
 ├──── private ip: 172.16.3.3
 └────────── args: /usr/bin/python /src/server.py

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:

(bash)
 
kraft cloud image ls

You should see output like:

(text)
 
IMAGE                       TAG     SIZE
[username]]/http-python312  latest  77 MB

And you can remove an image from the registry via:

(bash)
 
kraft cloud img rm http-python312

Create an image and many instances from it

For the next workflow, use kraft cloud deploy again, this time with the -R flag to start many instances:

(bash)
 
git clone https://github.com/unikraft-cloud/examples
cd examples/http-python3.12
kraft cloud deploy -p 443:8080 -M 512 -R 2 .

(ansi)
 
[●] Deployed successfully!
 │
 ├────────── name: http-python312-8mxq5
 ├────────── uuid: 37f5b23c-0996-45fa-8d7f-e6b2942eb6fb
 ├───────── state: running
 ├─────────── url: https://small-darkness-4t9y8n5s.fra.unikraft.app
 ├───────── image: http-python312@sha256:5b922dfa1632af38c476b98fdd9f4314fb9c5e587d3d31255e6479108c057e88
 ├───── boot time: 153.65 ms
 ├──────── memory: 512 MiB
 ├─────── service: small-darkness-4t9y8n5s
 ├── private fqdn: http-python312-8mxq5.internal
 ├──── private ip: 172.16.6.7
 └────────── args: /usr/bin/python3 /src/server.py

Check that it worked by listing all instances with:

(bash)
 
kraft cloud instance list

(text)
 
NAME                  FQDN                                      STATE    CREATED AT      IMAGE                     MEMORY   ARGS                             BOOT TIME
http-python312-w4bcp  sparkling-surf-qphxdk0j.fra.unikraft.app  running  45 seconds ago  http-python312@sha256...  512 MiB  /usr/bin/python3 /src/server.py  153794us
http-python312-juvv4  old-brook-v3bf7h7z.fra.unikraft.app       running  45 seconds ago  http-python312@sha256...  512 MiB  /usr/bin/python3 /src/server.py  154744us
http-python312-8mxq5  small-darkness-4t9y8n5s.fra.unikraft.app  running  45 seconds ago  http-python312@sha256...  512 MiB  /usr/bin/python3 /src/server.py  153646us

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 using the kraft cloud instance command:

(bash)
 
kraft cloud instance create \
   --start \
   --port 443:8080 \
   -M 512 \
   [username]/http-python312@sha256:1b815914eb568a06ca4bbfdfb7d6cf484a9e9a0947ba8e0e0f1664d972a25bca

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

Learn more

• The kraft cloud CLI reference
• Unikraft Cloud's REST API reference