Images

On Unikraft Cloud, an image is comprised of your application files and binaries, as well as a highly specialized and performant unikernel or Linux kernel. We store these together as an OCI image and distribute them worldwide using low-latency metro interconnects.

As images deployed to Unikraft Cloud are lightweight; transport is fast, and distributing new and updated production-ready applications takes only milliseconds to propagate (caveat: clearly if the application itself is large, the overall image will be large as well).

Image Name Reference

We follow the OCI Distribution Specification for naming and referencing images. When referencing an image you can either reference it by its tag:

<USER>/<APP>:<TAG>

or by its SHA256 checksum:

<USER>/<APP>@sha256:<CHECKSUM>

Where <USER> is the name of your user account, <APP> is the name of the application you want to start, <TAG> specifies a label applied to this application (e.g., latest), and <CHECKSUM> represents the digest of a specific version of the image.

Since the latest version of an application may change when an update is pushed, Unikraft Cloud computes a SHA256-based digest of the image to uniquely identify it. Whenever you create a new instance from an image, Unikraft Cloud translates the tag to the image’s digest and pins the instance to this particular version. That is why GET /v1/instances reports a digest instead of the tag originally used to create the instance.

Applications under the namespace of your user account can only be accessed by your user and are private to you. In addition to private images, there are official images published by Unikraft Cloud which are accessible by just their name:

<APP>:<TAG>

API Endpoints

The Unikraft Cloud Images API provides the following endpoints:

Method	Endpoint	Description
`GET`	`/v1/images/list`	List existing images

In the following, the API endpoints are specified relative to this base URL:

https://api.X.kraft.cloud/

With X being the IATA metro code. We use fra0 as an example in the documentation. See the introduciton for more information on how to connect to the API.

List Existing Images

Lists existing images. You can filter by various aspects such as showing only your personal images or one or more specific digests or tags. The returned images fulfill all provided filter criteria. No particular value is assumed if a filter is not part of the request.

Request

Endpoints:
GET /v1/images/list

Query Parameter	Type	Default	Required	Description
`namespace`¹	string			Filter images by namespace
`tagged`	flag			List only tagged images

¹Set the namespace to your Unikraft Cloud account name to list only your personal images. It can be official for listing only the official ones. In addition, the namespace can include the app name. For example, ${UKC_USER}/myapp to list all your myapp images.

Body Parameter	Type	Default	Required	Description
`digest`	string			Image digest to lookup
`tag`	string			Image tag to lookup

Example of listing all available images:

curl -X GET \
     -H "Authorization: Bearer ${UKC_TOKEN}" \
     "https://api.fra0.kraft.cloud/v1/images/list"

Example of looking up all your tagged images:

curl -X GET \
     -H "Authorization: Bearer ${UKC_TOKEN}" \
     "https://api.fra0.kraft.cloud/v1/images/list?namespace\=${UKC_USER}\&tagged" \

Example of looking up the image for a specific digest:

curl -X GET \
     -H "Authorization: Bearer ${UKC_TOKEN}" \
     -H "Content-Type: application/json" \
     "https://api.fra0.kraft.cloud/v1/images/list" \
     -d "{
        'digest': '${UKC_USER}/myapp@sha256:c4c2919...f03db26'
     }"

Response

The response is embedded in a JSON object as described in API Responses.

Field	Type	Description
`digest`	string	Image digest to uniquely identify this image
`tags`	array of strings	Tags referencing this image
`initrd`	bool	Indicates if the image comes with an init ramdisk
`size_in_bytes`	int	Total size of the image on disk in bytes including the initrd, if any
`args`	string	Default application arguments of the image. Dismissed if the instance specifies application arguments
`kernel_args`	string	Unikraft kernel arguments hardcoded into the image. Prepended to the kernel arguments set by Unikraft Cloud
`labels`	object	Key value pairs of image labels (e.g., used as defaults for instance configuration)

{
  "status": "success",
  "data": {
    "images": [
      {
        "digest": "${UKC_USER}/myapp@sha256:c4c2919...f03db26",
        "tags": [
          "${UKC_USER}/myapp:latest",
          "${UKC_USER}/myapp:v1.0"
        ],
        "initrd": true,
        "size_in_bytes": 2487552
      },
      {
        ...
      }
    ]
  }
}