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
For example:
Code
The <my-org> segment is your Unikraft Cloud organization, available as the UKC_USER environment variable in most guides.
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 new CLI uses profiles, while the legacy CLI reads UKC_TOKEN directly.
The UKC_TOKEN and UKC_METRO environment variables are only used by the legacy CLI.
You will also need to use the legacy CLI login command for kraft pkg operations:
Pushing images
Via the CLI (recommended)
The simplest way to push an image is to use the CLI to build, package, push, and start an instance in one flow:
During deployment you will see output confirming the push:
Via kraft pkg --push
For more control, for example when packaging ROMs or base images, use the legacy CLI with the --push flag:
Listing images
There may be a delay of a few minutes between pushing or removing an image and the image list reflecting the change.
Removing images
Kernel layer deduplication
An image has two OCI layers: a kernel layer and a rootfs layer.
When you push an update to an existing image, kraft checks whether the kernel layer is already present in the registry and skips re-uploading it if so.
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.
Image addresses in instance creation
When creating an instance directly from an existing image, reference it by tag or digest:
Learn more
- Images: build, package, and deploy workflow.
- The CLI reference and the legacy CLI reference.
- Unikraft Cloud's REST API reference.