Images

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

As images deployed to KraftCloud 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, KraftCloud computes a SHA256-based digest of the image to uniquely identify it. Whenever you create a new instance from an image, KraftCloud 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 KraftCloud which are accessible by just their name:

<APP>:<TAG>

API Endpoints

The KraftCloud Images REST 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.

Batching

For the body parameters you can specify an array of objects to get information about multiple digests or tags in the same call.

Request

Endpoints:
GET /v1/images/list

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

¹Set the namespace to your KraftCloud 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, ${KRAFTCLOUD_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 ${KRAFTCLOUD_TOKEN}" \
     "https://api.fra0.kraft.cloud/v1/images/list"

Example of looking up all your tagged images:

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

Example of looking up the image for a specific digest:

curl -X GET \
     -H "Authorization: Bearer ${KRAFTCLOUD_TOKEN}" \
     -H "Content-Type: application/json" \
     "https://api.fra0.kraft.cloud/v1/images/list" \
     -d "{
        'digest': '${KRAFTCLOUD_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 KraftCloud

Status: 200 OK

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