Images
Unikraft Cloud (UKC) uses a registry to store the images used to instantiate
apps from. At a high level, a user uses kraft to build and push an image to
the registry, and then to ask the controller to start an app from it.
- build: The app is built, locally, according to a
Dockerfile. - pkg: The app is packaged, locally, into an OCI image.
- push: The OCI image is pushed to the UKC registry.
- create: Your app is instantiated from the image accoring to a
Kraftfile.
The simplest way to run this workflow is to use kraft cloud deploy, which
subsumes all of these steps into a single command. Under the hood, the deploy
command uses other sub-commands to carry out the work of the different steps,
though we won't bother you with them here 😀. Note that the service in the
diagram is UKC's mechanism to connect apps to the Internet; read more about that
in this guide.
Dockerfiles, Kraftfiles and Runtimes
On Unikraft Cloud, the process of building images is guided by a Dockerfile,
and the process of deploying the resulting image by a Kraftfile.
Let's use once again our Python running example:
The directory contains the following Kraftfile:
Kraftfile
The file is pretty simple, stating what the cmd for starting the application
should be, that a Dockerfile should be used to build its root filesystem, and
that the python3.12 runtime should be used. On UKC, a runtime is a base
image that contains the (minimal) code needed for the application (in this case
the Python interpreter) to run; your application code is then overlayed on top
of it during the packaging step.
The Dockerfile itself for our app looks as follows:
Dockerfile
If you're familiar with Dockerfiles there shouldn't be anything too mysterious
in them, other than by default we use FROM scratch to ensure that the
resulting images are as lean as possible. To add your app's code to the build
modify the COPY commands as needed.
All guides on UKC, and the
examples they rely on underneath
come with Kraftfiles and Dockerfiles for you to easily get started.
Feel entirely free to try a more standard Dockerfile (e.g., not using from
scratch but rather something like FROM python:alpine). Note, however, that
this may lead to larger images, more memory consumption and longer boot times.
Example Workflows
In this guide we'll use a Python app as a running example to show a number of workflows:
- How to create an image and launch an instance from it.
- How to create an image and launch multiple instances from it.
- How to launch instances from an existing image.
Create an Image and an Instance from it
We will start with the simplest workflow: create an image from a Python app, as
per the Python app guide, and start an instance from it,
all with a single kraft cloud deploy command:
The output should be similar to:
This command uses the Kraftfile and Dockerfile files in the directory to build an image named http-python312@sha256:278cb8b1..., package it, push it to the registry and request Unikraft Cloud to start an instance named http-python312-ma2i9 from it (causing the controller in the diagram at the top to fetch the image from the registry in order to start the instance).
You can see your images by running the following command:
You should see output similar to:
And you can remove an image from the registry via:
There may be a delay of a few minutes between removing an image from the
registry and kraft cloud image ls reflecting the change.
Create an Image and Multiple Instances from it
For the next workflow, we'll once again use kraft cloud deploy but this time
we'll use the -R flag to start multiple instances from it:
You can check that it worked by listing all instances with:
Note there are 3 running instances in total: the one we created plus the 2 replicas.
Create Instances from an Existing Image
In this final workflow, we'll take the image we created above and use it to start new instances using the kraft cloud instance command:
That's it, now you have a shiny new instance from the image you had previously created.
Learn More
- The
kraft cloudCLI reference - Unikraft Cloud's REST API reference