Instances
This document describes the Unikraft Cloud Instances API (v1) for managing Unikraft instances. An instance is a MicroVM running a single instance of your app.
Instance states
An instance can be in one of the following states:
| State | Description |
|---|---|
stopped | The instance isn't running and doesn't count against live resource quotas. Connections can't establish. |
starting | The instance is booting up. This typically takes just a few milliseconds. |
running | Your app reached its main entry point. |
draining | The instance is draining connections before shutting down. No new connections can establish. |
stopping | The instance is shutting down. |
standby | The instance has scaled-to-zero. The instance isn't running, but will be automatically started when there are incoming requests. |
Unikraft Cloud reports these as instance state values via the endpoints.
You can visualize these states with the CLI.
Here is an example of an instance that's in stopped state:
You can retrieve even more instance details via the API:
GET /instances/bd281cc4-7640-4cbc-af48-5a44c2bd7b74
Stop reason
To understand why Unikraft Cloud stopped an instance or is shutting it down, it provides information about the stop reason.
You can retrieve this information via the GET /instances endpoint when an instance is in the draining, stopping, stopped or standby state.
The stop_reason contains a bitmask that tells you the origin of the shutdown:
| Bit | 5 [Z] | 4 [F] | 3 [U] | 2 [P] | 1 [A] | 0 [K] |
|---|---|---|---|---|---|---|
| Desc. | Stop due to scale-to-zero | This was a force stop1 | Stop initiated by user2 | Stop initiated by platform3 | App exited - exit_code available | Kernel exited - stop_code available |
For example, the stop_reason has the following values in these scenarios:
| Value | Bitmask | Scenario |
|---|---|---|
39 | 100111/Z--PAK | Scale-to-zero shutdown. The platform initiated the stop because the instance scaled to zero, and both the app and kernel exited. |
31 | 011111/-FUPAK | Forced user-initiated shutdown where the app and kernel still reported clean exits before the stop completed. |
28 | 011100/-FUP-- | Forced user-initiated shutdown without app or kernel exit information. |
15 | 001111/--UPAK | Regular user-initiated shutdown. The app and kernel have exited. The exit_code and stop_code show if the app and kernel shut down cleanly. |
13 | 001101/--UP-K | The user initiated a shutdown but the app was forcefully killed by the kernel during shutdown. This can happen if the image doesn't support a clean app exit or the app crashed after receiving a termination signal. In this case, ignore exit_code. |
7 | 000111/---PAK | Platform-initiated shutdown. The app and kernel have exited. The exit_code and stop_code show if they shut down cleanly. |
3 | 000011/----AK | The app exited. The exit_code and stop_code show if the app and kernel shut down cleanly. |
1 | 000001/-----K | The instance likely experienced a fatal crash and the stop_code contains more information about the cause of the crash. |
0 | 000000/------ | The stop reason is unknown. |
There can be a short delay of a few milliseconds between the instance reaching the stopped state and Unikraft Cloud updating the stop_reason (or vice versa).
The scale-to-zero shutdown is a special case where the platform initiates the stop because the instance scaled to zero, and both the app and kernel exited.
In the API, the instance appears in the standby state, instead of stopped.
Exitcode
The app exit code is what the app returns upon leaving its main entry point.
The encoding of the exit_code is app specific.
See the documentation of the app for more details.
An exit_code of 0 indicates success or no failure.
Stopcode
If bit 0 [K] is set in stop_reason, stop_code contains the 32-bit code reported by the guest kernel.
Unikraft Cloud also uses platform-defined values when the stop originates in the platform before the guest kernel can report its own code.
Currently the platform-defined values are:
| Value | Symbol | Scenario |
|---|---|---|
0 | UNKNOWN | No platform-specific stop code is available. |
1 | NOMEDIUM | The instance couldn't start because the image or another required medium wasn't available, for example because an image pull failed. |
When the guest kernel reports a stop code, it uses the following encoding:
| Bits | 31 - 24 (8 bits) | 23 - 16 (8 bits) | 15 [T] | 14 - 8 (7 bits) | 7 - 0 (8 bits) |
|---|---|---|---|---|---|
| Desc. | Reserved4 | errno | shutdown_bit | initlvl | reason |
Reason
The reason can be any of the following values:
| Value | Symbol | Scenario |
|---|---|---|
0 | OK | Successful shutdown. |
1 | EXP | The system detected an invalid state and actively stopped execution to prevent data corruption. |
2 | MATH | An arithmetic CPU error (for example, division by zero). |
3 | INVLOP | Invalid CPU instruction or instruction error (for example, wrong operand alignment). |
4 | PGFAULT | Page fault - see errno for further details. |
5 | SEGFAULT | Segmentation fault. |
6 | HWERR | Hardware error. |
7 | SECERR | Security violation (for example, violation of memory access protections). |
A reason of 0 indicates a clean shutdown.
Ignore the other bits of stop_code when checking for a crash.
Init level
initlvl indicates the initialization or shutdown phase at stop time.
A level of 127 means the instance was executing the app.
Shutdown bit
shutdown_bit indicates the system was shutting down.
Error number
errno is a Linux error code number that provides more detail about the root cause.
For example, an out-of-memory (OOM) situation triggers a page fault PGFAULT(4) with errno set to ENOMEM(12).
In that case the stop_code is 0x000C7F04=818948 and the stop_reason is -----K (1) if the stop occurred during app execution.
Restart policy
When an instance stops because the app exits or crashes, Unikraft Cloud can restart it automatically according to the restart policy. The policy can have the following values:
| Policy | Description |
|---|---|
never | Never restart the instance (default). |
always | Always restart the instance when Unikraft Cloud initiates the stop from within the instance (that is, the app exits or the instance crashes). |
on-failure | Only restart the instance if it crashes. |
When an instance stops, Unikraft Cloud evaluates the stop reason and the restart policy to decide whether to restart. It uses an exponential back-off delay (immediate, 5s, 10s, 20s, 40s, 5m) to slow down restarts in tight crash loops. If an instance runs without problems for 10s, Unikraft Cloud resets the back-off delay and the restart sequence ends.
The restart.attempt value in GET /instances counts restarts in the current sequence.
The number of completed restarts is restart_count.
The restart.next_at field indicates when the next restart occurs if a back-off delay is in effect.
A manual start or stop of the instance aborts the restart sequence and resets the back-off delay.
Creating instances
Replicas
The POST /instances request accepts a replicas field (default 0) that creates more copies of the instance alongside the base one.
| Value | Instances created |
|---|---|
0 | 1 (the base instance) |
1 | 2 (base + 1 replica) |
N | N + 1 |
All instances share the same image, memory, arguments, and service group configuration. Replicas receive independent names and UUIDs.
You can do this with the CLI as well:
GPUs
Limited Access
GPU support is currently only available as a preview for enterprise customers. The interface described here reflects the current implementation and may change before general availability.
Instances can run with an NVIDIA GPU attached.
Pass the gpus field in the POST /instances request to request one:
POST /instances
An instance can currently hold at most one GPU.
GPU instances are only available on GPU-provisioned hardware. Please get in touch if you need it.
Wait for running
By default POST /instances returns as soon as the platform queues the instance.
Set timeout_s non-zero to block until the instance reaches the running state or the timeout expires.
For example:
POST /instances
wait_timeout_ms is a deprecated compatibility field.
When set, the platform rounds the value up to the next full second.
Use timeout_s instead.
The unikraft CLI automatically waits for the instance to be running after creation, up until a preconfigured timeout of 10 seconds.
The kraft CLI doesn't support this feature yet.
Additionally, if you create an instance using kraft cloud instance create, you need to specify the --start flag to autostart the instance.
Delete on stop
Pass delete-on-stop in the features array to automatically delete the instance when it stops:
POST /instances
This is useful for ephemeral workloads—batch jobs, one-shot tasks—where you don't need to keep the stopped instance.
You can also use the CLI to set this up:
To use the "delete-on-stop" feature, set the restart_policy to never.
Stopping instances
Drain timeout
By default PUT /instances/stop stops the instance immediately.
Set drain_timeout_ms to allow the instance to finish serving in-flight connections before it stops.
| Value | Behaviour |
|---|---|
0 | Stop immediately (default). |
-1 | Use the platform's maximum drain timeout. |
N | Drain for up to N milliseconds, then stop. |
PUT /instances/stop
You can also use the CLI to set this up:
While draining, the instance enters the draining state.
The platform accepts no new connections.
The instance stops once all connections close or the timeout elapses.
You can't combine drain_timeout_ms with force: true.
Setting both returns a 400 error.
Instance templates
An instance template is a snapshotted instance that acts as a source for cloning new instances. Cloning a template creates a new instance that resumes from the exact original system state. It preserves memory contents, open files, and populated caches to bypass the standard boot sequence. Once you convert an instance into a template, you can't reverse the process.
To transition an actively running instance into a template, from the guest write the value 1 to /uk/libukp/template_instance:
Convert instance to template
This action instructs the controller to freeze running processes and save the instance as a reusable template. The write blocks until the platform has snapshotted the instance and created the new instance from the resulting template. When the write returns, the guest is already running as the freshly cloned instance, restored from the snapshot rather than continuing as the original.
This lets the guest finish any instance-specific setup—such as reading per-instance data from an attached inline ROM—immediately after the write completes.
If the template already exists, the clone happens right away and the write returns without re-snapshotting.
You can also create a template from an instance (even when it's running) by calling POST /instances/templates, or using the CLI:
You can list templates with GET /instances/templates or the CLI:
Now, you can create an instance from the template using the unikraft CLI:
unikraft
unikraft
Templates support delete locks, tags, and autokill. The platform measures autokill on a template from the time of last clone, not from instance stop time.
You can also have the platform create a template implicitly as part of an instance-create call, instead of converting and managing it yourself. See On-demand templates.
Nested templates
You can clone a template from another template, creating a hierarchy. Each clone inherits the parent's full state at clone time and can independently accumulate further state before you convert it into its own template. This enables layered configurations, for example a base template with a warm database connection pool, and child templates specialized for different query workloads.
No depth limit applies to nesting, and circular references aren't possible because the template state is immutable once set.
You can also build such a hierarchy in a single API call with on-demand templates, where the platform creates each level only if it doesn't already exist.
For more information, check out the API reference for instance templates here.
Instance metrics
Use the GET /instances/metrics endpoint to retrieve runtime statistics for one or more instances.
With no identifiers, the platform returns metrics for all instances in your account.
For more information, check out this dedicated section on instance metrics.
Instance logs
Use the GET /instances/logs endpoint to retrieve logs for one or more instances.
The logs capture the instance's stdout and stderr output, and they're preserved across restarts and stops.
With the CLI, you can also follow the logs in real time:
Learn more
- The CLI reference and the legacy CLI reference.
- Unikraft Cloud's REST API reference, in particular the section on instances.
Footnotes
-
A forced stop doesn't give the instance a chance to perform a clean shutdown. Often,
exit_codeandstop_codeare therefore not available. If the guest reports an exit while the forced shutdown is in progress, bits 0 [K] and 1 [A] can still be set. ↩ -
A stop command originating from the user travels through the platform controller. This is why bit 2 [P] will also always occur for user-initiated stops. ↩
-
Internally this bit is set when ukpd, the platform controller, initiates the stop. ↩
-
The system sets reserved bits to 0; ignore them. ↩