Copy page

Concepts

Registries

Unikraft Cloud uses a central OCI registry at index.unikraft.io to store images. Every image you build and push lands in this registry under your account's namespace. When you start an instance, the platform pulls the image from this registry automatically.

Each node has a local registry also running for directly pushing to a specific node. These registries have the address formatted as index.<node-name>.unikraft.cloud. The main advantage of pushing to a node's registry is that it avoids the round trip to the central registry. This speeds up deployments and reduces bandwidth usage.

Directly pushing to a node's registry or using the central registry is interchangeable. The platform handles synchronization between them.

Image naming

The platform addresses images using the standard OCI reference format:

Code
index.unikraft.io/<my-org>/<name>:<tag>
index.<node-name>.unikraft.cloud/<my-org>/<name>:<tag>

For example:

The <my-org> segment is your Unikraft Cloud organization. Tags are arbitrary strings. The platform defaults to latest when you don't specify a tag. You can also refer to images by digest to pin to an exact version.

Authentication

Registry authentication uses the same API token as the rest of the platform. The unikraft CLI uses profiles to manage the token.

Code
unikraft login

When using external registries (e.g. ghcr.io), authenticate explicitly:

Code
docker login ghcr.io -u <user> -p <token>

You don't need to login to the central or node registries.

Pushing images

Via unikraft build

The simplest way to push an image is to use the CLI to build, package, push, and start an instance in one flow:

External registries

unikraft build can also push to an external OCI registry, meaning registries other than index.unikraft.io or a node's local registry.

To work with Unikraft Cloud, a registry must:

• Support the Docker Registry HTTP API V2.
• Support bearer token authentication.
• Accept custom fields in the OCI manifest, which Unikraft Cloud uses to store image metadata.

Unikraft Cloud works with the following popular registries:

• Docker Hub
• GitHub Container Registry
• Amazon ECR
• Google Cloud Artifact Registry
• DigitalOcean Container Registry
• CNCF Distribution

Registries based on CNCF Distribution, such as Harbor, also work.

If you run into issues with a registry or want support for one not listed here, contact the Unikraft Cloud team.

Log in to the registry first, as shown in Authentication, then pass the full image reference. For example, with GitHub Container Registry and a personal access token that has the write:packages scope:

Code
echo <token> | docker login ghcr.io -u <github-username> --password-stdin
unikraft build . --output ghcr.io/<github-username>/my-app:latest

Listing images

Code
unikraft images list

Removing images

You can remove images with specific tags, or all tags at once:

Code
unikraft images delete <my-org>/<my-app>[:<tag>]

Kernel layer deduplication

An image typically has two OCI layers: a kernel layer and a rootfs layer. When you push an update to an existing image, the CLI checks whether the kernel layer is already present in the registry and skips re-uploading it. Only the rootfs layer travels over the wire. This makes iterative pushes faster and cheaper on bandwidth.

ROMs follow the same packaging system but go out without a kernel layer. They only have a rootfs. They appear in the image list alongside regular images. Images that boot on the platform kernel carry a rootfs layer alone in the same way.

Instance creation

When creating an instance directly from an existing image, reference it by tag or digest:

Code
# By tag
unikraft run --metro fra \
  -m 256M \
  -p 443:8080/http+tls \
  --image index.unikraft.io/alice/my-app:latest

# By digest (exact version pinning)
unikraft run --metro fra \
  -m 256M \
  -p 443:8080/http+tls \
  --image index.unikraft.io/alice/my-app@sha256:278cb8b1...

Learn more

• Images: build, package, and deploy workflow.
• The CLI reference.
• Unikraft Cloud's REST API reference.