Instances
This document describes the KraftCloud Instances REST API (v1) for managing Unikraft instances. An instance is a Unikraft unikernel running a single instance of your application.
Instance States
An instance can be in one of the following states:
State | Description |
---|---|
stopped | The instance is not running and does not count against live resource quotas. Connections cannot be established. |
starting | The instance is booting up. This usually takes just a few milliseconds. |
running | Your application’s main entry point has been reached. |
draining | The instance is draining connections before shutting down. No new connections can be established. |
stopping | The instance is shutting down. |
standby | The instance has scale-to-zero enabled. The instance is not running, but will be automatically started when there are incoming requests. |
These are reported as instance state
by the endpoints.
Stop Reason
To understand why an instance has been stopped or is in the process of shutting down, KraftCloud provides information about the stop reason.
You can retrieve this information via the GET /v1/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 | 4 [F] | 3 [U] | 2 [P] | 1 [A] | 0 [K] (LSB) |
---|---|---|---|---|---|
Desc. | This was a force stop1 | Stop initiated by user1 | Stop initiated by platform | App exited - exit_code available | Kernel exited - stop_code available |
1A forced stop does not give the instance a chance to perform a clean shutdown. Bits 0 [K] and 1 [A] can thus never be set for forced shutdowns. Consequently, there won’t be an exit_code
or stop_code
.
2A stop command originating from the user is travelling through the platform controller. This is why bit 2 [P] will also always be set for user-initiated stops.
For example, the stop_reason
will contain the following values in the given scenarios:
Value | Bitmask | Scenario |
---|---|---|
28 | 11100 /FUP-- | Forced user-initiated shutdown. |
15 | 01111 /-UPAK | Regular user-initiated shutdown. The application and kernel have exited. The exit_code and stop_code indicate if the application and kernel shut down cleanly. |
13 | 01101 /-UP-K | The user initiated a shutdown but the application was forcefully killed by the kernel during shutdown. This can be the case if the image does not support a clean application exit or the application crashed after receiving a termination signal. The exit_code won’t be present in this scenario. |
7 | 00111 /--PAK | KraftCloud initiated the shutdown, for example, due to scale-to-zero. The application and kernel have exited. The exit_code and stop_code indicate if the application and kernel shut down cleanly. |
3 | 00011 /---AK | The application exited. The exit_code and stop_code indicate if the application and kernel shut down cleanly. |
1 | 00001 /----K | The instance likely expierenced a fatal crash and the stop_code contains more information about the cause of the crash. |
0 | 00000 /----- | The stop reason is unknown. |
Exit Code
The application exit code is what the application returns upon leaving its main entry point.
The encoding of the exit_code
is application specific.
See the documentation of the application for more details.
Usually, an exit_code
of 0
indicates success / no failure.
Stop Code
The stop_code
is defined by the kernel and has the following encoding irrespective of the application.
Bits | 31 - 24 (8 bits) | 23 - 16 (8 bits) | 15 [T] | 14 - 8 (7 bits) | 7 - 0 (8 bits) |
---|---|---|---|---|---|
Desc. | reserved1 | errno | shutdown_bit | initlvl | reason |
1Reserved bits are set to 0. Ignore.
Reason
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 (e.g., division by zero) |
3 | INVLOP | Invalid CPU instruction or instruction error (e.g., wrong operand alignment) |
4 | PGFAULT | Page fault - see errno for further details |
5 | SEGFAULT | Segmentation fault |
6 | HWERR | Hardware error |
7 | SECERR | Security violation (e.g., violation of memory access protections) |
A reason
of 0
indicates that the instance was shut down cleanly.
To detect if the system experienced a crash, all other bits of stop_code
can be ignored.
Init Level
initlvl
indicates during which initialization or shutdown phase the instance stopped. A level of 127
indicates that the instance was executing the application when it stopped.
Shutdown Bit
shutdown_bit
is set when the stop occurred while the system was shutting down.
Error Number
errno
is a Linux error code number that provides more detailed information about the root cause.
Restart Policy
When an instance stops either because the application exits or the instance crashes, KraftCloud can auto-restart your instance. Auto-restarts are performed according to the restart policy configured for a particular instance. The policy can have the following values:
Policy | Description |
---|---|
never | Never restart the instance (default). |
always | Always restart the instance when the stop is initiated from within the instance (i.e., the application exits or the instance crashes). |
on-failure | Only restart the instance if it crashes. |
When an instance stops, the stop reason and the configured restart policy are evaluated to decide if a restart should be performed. KraftCloud 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 the back-off delay is reset and the restart sequence ends.
The restart.attempt
reported in GET /v1/instances
counts the number of restarts performed in the current sequence.
The restart.next_at
field indicates when the next restart will take place 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.
API Endpoints
The KraftCloud Instances REST API provides the following endpoints:
Method | Endpoint | Purpose and Description |
---|---|---|
POST | /v1/instances | Creates one or more new instances of the specified image. |
GET | /v1/instances | Returns the current status and the configuration of instances. |
DELETE | /v1/instances | Deletes the specified instances. |
GET | /v1/instances/list | Lists all existing instances. |
PUT | /v1/instances/start | Starts the specified instances. |
PUT | /v1/instances/stop | Stops the specified instances, but does not destroy them. |
GET | /v1/instances/wait | Waits until one or more instances have reached the desired state. |
GET | /v1/instances/log | Returns the console log output of the specified instances. |
In the following, the API endpoints are specified relative to this base URL:
With X
being the IATA metro code.
We use fra0
as an example in the documentation.
See the introduction for more information on how to connect to the API.
Creating a New Instance
Creates a new instance of the specified Unikraft image. You can describe the properties of the new instance such as its startup arguments and amount of memory. Note that the instance properties can only be defined during creation. They cannot be changed later.
Request
Endpoints:
POST /v1/instances
Parameter | Type | Default | Required | Description |
---|---|---|---|---|
name 1 | Name | Name of the instance. The instance will receive a DNS entry in your private network of the form <name>.internal | ||
image 2 | string | ✔️ | Name of the Unikraft image to instantiate. Private images will be available under your user’s namespace | |
args | string | array of strings | Application arguments | ||
env | object | Key/value pairs to be set as environment variables at boot time. Values must be strings | ||
memory_mb | int | 128 | Amount of memory to assign to the instance in megabytes | |
service_group | object | Description of published services | ||
uuid | name 3 | UUID | Name | UUID or name of an existing service group | ||
services 3 | array of objects | Description of exposed network services | ||
port | int | ✔️ | Public-facing Port | |
destination_port | int | Same as port | Port that the image listens on | |
handlers | array of strings | See Connection Handlers | ||
domains | array of objects | auto-generated | Description of domains to associate with the service group (see here) | |
name | string | ✔️ | Publicly accessible domain name | |
certificate | object | auto-generated | TLS certificate to use for the domain | |
uuid | name | UUID | Name | ✔️ | UUID or name of the certificate | |
volumes | array of objects | Description of volumes | ||
uuid | name 4 | UUID | Name | UUID or name of an existing volume. Must be in available state | ||
size_mb 4 | int | ✔️ | Size of the new volume in megabytes | |
at | string | ✔️ | Path of the mountpoint. Must be empty. Automatically created if it does not exist | |
readonly | bool | false | Whether the volume should be mounted read-only | |
autostart | bool | false | Autostart behavior. If true the instance will start immediately after creation | |
replicas | int | 0 | Number of instance replicas to create with these properties | |
wait_timeout_ms 5 | int | 0 | Timeout to wait for all new instances to reach running state in milliseconds. No wait performed for 0 | |
features | array of strings | Set of features to enable for the instance (see below) | ||
restart_policy | string | never | Auto-restart policy (see here) |
1 If no name is specified a random name of the form <app>-X
is auto-generated, where <app>
is the application name taken from image
(e.g., myapp
for ../myapp:latest
) and X
is a 5 character long random alphanumeric suffix.
2 The image tag (e.g., latest
) is translated by KraftCloud to the image digest that the tag was pointing to at the time of instance creation.
The image is pinned to this particular version.
3 You need to specify either an existing service group via uuid
or name
, or provide a description of a new service group.
If a description for a new service group is provided, the service group is created and the instance attached.
The service group will receive an auto-generated name.
Specifying an empty service_group
object creates a new service group with no services published.
4 You need to specify either uuid
, name
, or size_mb
.
Specifying size_mb
will create a new volume and attach it to the instance.
The volume will receive an auto-generated name.
5 Only valid if autostart
is true
.
The maximum timeout may vary. Use -1
for the largest possible value.
The features field accepts the following values:
Feature | Description |
---|---|
scale-to-zero | Enables scale-to-zero using the default autoscale configuration with min_size and max_size set to 0 and 1 , respectively. |
Response
The response is embedded in a JSON object as described in API Responses.
Field | Type | Description |
---|---|---|
status | string | success on success, or error if the request failed |
state | State | Current state of the instance |
uuid | UUID | UUID of the newly created instance |
name | Name | Name of the newly created instance |
private_fqdn | string | Local fully-qualified domain name of the instance |
private_ip | string | Private IPv4 of the instance for communication between instances of the same user |
service_group 1 | object | Description of the service group that the instance is part of |
uuid | UUID | UUID of the service |
name | Name | Name of the service |
domains | array of objects | Description of domains associated with the service group |
fqdn | string | Public fully-qualified domain name under which the group is accessible from the Internet |
certificate 2 | object | TLS certificate used for the domain |
uuid | UUID | UUID of the certificate |
name | Name | Name of the certificate |
state | State | State of the certificate |
boot_time_us 3 | int | Boot time of the instance in microseconds |
1 Only if attached to a service group.
2 Not for subdomains of <metro>.kraft.host
.
3 Only if autostart
and wait_timeout_ms
are set.
Getting the Status of an Instance
Returns the current status and the configuration of an instance.
Request
Endpoints:
GET /v1/instances
GET /v1/instances/<UUID>
Parameter | Type | Default | Required | Description |
---|---|---|---|---|
uuid | name 1 | UUID | Name | ✔️ | UUID or name of the instance to get the status for |
1 Not allowed in local scope.
You need to specify either uuid
or name
.
Response
The response is embedded in a JSON object as described in API Responses.
Field | Type | Description |
---|---|---|
status | string | success on success, or error if the request failed |
uuid | UUID | UUID of the instance |
name | Name | Name of the instance |
created_at | string | Date and time of creation in ISO8601 |
state | State | Current state of the instance |
image 1 | string | Digest of the image that the instance uses |
memory_mb | int | Amount of memory assigned to the instance in megabytes |
args | array of strings | Application arguments |
env | object | Key/value pairs to be set as environment variables at boot time |
start_count | int | Total number of times the instance has been started |
started_at | string | Date and time of last start in ISO8601 |
stopped_at | string | If stopped, date and time of stop in ISO8601 |
uptime_ms | int | Total uptime of instance in milliseconds |
vmm_start_time_us 2 | int | Time from start of instance to VMM process start in microseconds |
vmm_load_time_us 2 | int | Time from start of instance to finish loading of initrd and kernel into instance in microseconds |
vmm_ready_time_us 2 | int | Time from start of instance to entering instance execution in microseconds |
boot_time_us | int | Time from start of instance to finish booting of Unikraft in microseconds |
net_time_us 2 | int | Time from start of instance to first listen socket in microseconds |
stop_reason | int | Reason for ongoing or current stop (see here) |
exit_code | int | Exit code of the application |
stop_code | int | Stop code of the kernel (see here) |
restart_policy | string | Configured restart policy |
restart | object | Information about auto-restarts |
attempt | int | Number of restarts performed in the current restart sequence |
next_at | string | Date and time of next restart attempt in ISO8601 |
restart_count | int | Total number of times the instance has been restarted by restart policy |
private_fqdn | string | Fully-qualified domain name under which the instance is accessible in the private network |
private_ip | string | Private IPv4 of the instance for communication between instances of the same user. This is equivalent to the IPv4 address of the first network interface |
service_group 3 | object | Description of the service group that the instance is part of |
uuid | UUID | UUID of the service |
name | Name | Name of the service |
domains | array of objects | Description of domains associated with the service group |
fqdn | string | Public fully-qualified domain name under which the group is accessible from the Internet |
certificate 4 | object | TLS certificate used for the domain |
uuid | UUID | UUID of the certificate |
name | Name | Name of the certificate |
state | State | State of the certificate |
volumes | array of objects | Description of volumes |
uuid | UUID | UUID of the volume |
name | Name | Name of the volume |
at | string | Path of the mountpoint |
readonly | bool | Whether the volume is mounted read-only |
network_interfaces | array of objects | List of network interfaces attached to the instance |
uuid | UUID | UUID of the network interface |
private_ip | string | Private IPv4 of network interface |
mac | string | MAC address of the network interface |
1 The image tag (e.g., latest
) is translated by KraftCloud to the image digest that was assigned the tag at the time of instance creation.
The image is pinned to this particular version.
2 Only with KraftCloud developer permissions.
3 Only if attached to a service group.
4 Not for subdomains of <metro>.kraft.host
.
Deleting an Instance
Deletes the specified instance. After this call the IDs associated with the instance are no longer valid. A running instance is force stopped. If the instance is an autoscale master, deleting the instance resets autoscale for the service group and deletes all instances created by autoscale.
Request
Endpoints:
DELETE /v1/instances
DELETE /v1/instances/<UUID>
Parameter | Type | Default | Required | Description |
---|---|---|---|---|
uuid | name 1 | UUID | Name | ✔️ | UUID or name of the instance to delete |
1 Not allowed in local scope.
You need to specify either uuid
or name
.
Response
The response is embedded in a JSON object as described in API Responses.
Field | Type | Description |
---|---|---|
status | string | success on success, or error if the request failed |
uuid | UUID | UUID of the instance |
name | Name | Name of the instance |
previous_state | State | State of the instance before the call |
List Existing Instances
Lists all existing instances. You can filter by instance state. No particular value is assumed if no status is provided in the request.
Request
Endpoints:
GET /v1/instances/list
Parameter | Type | Default | Required | Description |
---|---|---|---|---|
state | State | State for filtering |
Response
The response is embedded in a JSON object as described in API Responses.
Field | Type | Description |
---|---|---|
uuid | UUID | UUID of the instance |
name | Name | Name of the instance |
Starting an Instance
Starts a stopped instance. Does nothing for an instance that is already running.
Request
Endpoints:
PUT /v1/instances/start
PUT /v1/instances/<UUID>/start
Parameter | Type | Default | Required | Description |
---|---|---|---|---|
uuid | name 1 | UUID | Name | ✔️ | UUID or name of the instance to start | |
wait_timeout_ms 2 | int | 0 | Timeout to wait for all specified instances to reach running state in milliseconds. No wait performed for 0 |
1 Not allowed in local scope.
You need to specify either uuid
or name
.
2 The maximum timeout may vary.
Use -1
for the largest possible value.
Response
The response is embedded in a JSON object as described in API Responses.
Field | Type | Description |
---|---|---|
status | string | success on success, or error if the request failed |
uuid | UUID | UUID of the instance |
name | Name | Name of the instance |
state | State | Current state of the instance |
previous_state | State | State of the instance before the call |
Stopping an Instance
Stops the specified instance, but does not destroy it.
All volatile state (e.g., RAM contents) is lost.
Does nothing for an instance that is already stopped.
The instance can be started again with the start
endpoint.
Request
Endpoints:
PUT /v1/instances/stop
PUT /v1/instances/<UUID>/stop
Parameter | Type | Default | Required | Description |
---|---|---|---|---|
uuid | name 1 | UUID | Name | ✔️ | UUID or name of the instance to stop | |
force | bool | false | Forces immediate shutdown | |
drain_timeout_ms 2 | int | 0 | Timeout for draining connections in milliseconds. The instance does not receive new connections in the draining phase. The instance is stopped when the last connection has been closed or the timeout expired |
1 Not allowed in local scope.
You need to specify either uuid
or name
.
2 The maximum timeout may vary.
Use -1
for the largest possible value. The call does not block.
Use wait
to wait for the instance to reach the stopped
state
Response
The response is embedded in a JSON object as described in API Responses.
Field | Type | Description |
---|---|---|
status | string | success on success, or error if the request failed |
uuid | UUID | UUID of the instance |
name | Name | Name of the instance |
state | State | Current state of the instance |
previous_state | State | State of the instance before the call |
Waiting for an Instance to Reach a Desired State
Waits until the specified instance has reached the desired state. The request blocks until all waits in the call are satisfied or the request timed out.
Request
Endpoints:
GET /v1/instances/wait
GET /v1/instances/<UUID>/wait
Parameter | Type | Default | Required | Description |
---|---|---|---|---|
uuid | name 1,2 | UUID | Name | UUID or name of an existing instance | ||
ids 1 | array of objects | IDs of the instances to wait for | ||
uuid | name 2 | UUID | Name | UUID or name of an existing instance | ||
state | State | running | State to wait for | |
timeout_ms 4 | int | -1 | Timeout for the wait in milliseconds |
1 Not allowed in local scope.
2 You need to specify either uuid
or name
.
3 You cannot combine uuid
/name
with IDs provided in ids
. If you want to specify multiple IDs, specify all of them via ids
.
4 The maximum timeout may vary. Use -1
for the largest possible value.
Response
The response is embedded in a JSON object as described in API Responses.
Field | Type | Description |
---|---|---|
status | string | success on success, or error if the request failed |
uuid | UUID | UUID of the instance |
name | Name | Name of the instance |
state | State | Current state of the instance |
Retrieve the Log Output
Returns the log output of the specified instance in base64 encoding. Note that the maximum response size is capped. The log output might thus be cut off and require multiple requests to fetch further output.
Request
Endpoints:
GET /v1/instances/log
GET /v1/instances/<UUID>/log
Parameter | Type | Default | Required | Description |
---|---|---|---|---|
uuid | name 1 | UUID | Name | ✔️ | UUID or name of the instance to return log output for | |
offset | int | -4096 | The byte offset of the log output to receive. A negative sign makes the offset relative to the end of the log. | |
limit | int | 4096 | The amount of bytes to return at most. |
1 Not allowed in local scope.
You need to specify either uuid
or name
.
Response
The response is embedded in a JSON object as described in API Responses.
Field | Type | Description |
---|---|---|
status | string | success on success, or error if the request failed |
uuid | UUID | UUID of the instance |
name | Name | Name of the instance |
output | string | BASE64 encoded log output |
available | object | Description of the log availability |
start | int | The first byte offset that can be retrieved |
end | int | The last byte offset that can be retrieved |
range | object | Description of the range that was returned. Useful for requests with offset relative to end. |
start | int | The first retrieved byte |
end | int | The last retrieved byte |
To decode the base64 formatted log output on the command line you can use tools like jq
and base64
: