Skip to content

Instances

This document describes the Unikraft Cloud Instances API (v1) for managing Unikraft instances. An instance is a Unikraft virtual machine running a single instance of your application.

Instance States

An instance can be in one of the following states:

StateDescription
stoppedThe instance is not running and does not count against live resource quotas. Connections cannot be established.
startingThe instance is booting up. This usually takes just a few milliseconds.
runningYour application’s main entry point has been reached.
drainingThe instance is draining connections before shutting down. No new connections can be established.
stoppingThe instance is shutting down.
standbyThe 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, Unikraft Cloud 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:

Bit4 [F]3 [U]2 [P]1 [A]0 [K] (LSB)
Desc.This was a force stop1Stop initiated by user1Stop initiated by platformApp exited - exit_code availableKernel 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:

ValueBitmaskScenario
2811100/FUP--Forced user-initiated shutdown.
1501111/-UPAKRegular user-initiated shutdown. The application and kernel have exited. The exit_code and stop_code indicate if the application and kernel shut down cleanly.
1301101/-UP-KThe 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.
700111/--PAKUnikraft Cloud 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.
300011/---AKThe application exited. The exit_code and stop_code indicate if the application and kernel shut down cleanly.
100001/----KThe instance likely expierenced a fatal crash and the stop_code contains more information about the cause of the crash.
000000/-----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.

Bits31 - 24 (8 bits)23 - 16 (8 bits)15 [T]14 - 8 (7 bits)7 - 0 (8 bits)
Desc.reserved1errnoshutdown_bitinitlvlreason

1Reserved bits are set to 0. Ignore.

Reason reason can be any of the following values:

ValueSymbolScenario
0OKSuccessful shutdown
1EXPThe system detected an invalid state and actively stopped execution to prevent data corruption
2MATHAn arithmetic CPU error (e.g., division by zero)
3INVLOPInvalid CPU instruction or instruction error (e.g., wrong operand alignment)
4PGFAULTPage fault - see errno for further details
5SEGFAULTSegmentation fault
6HWERRHardware error
7SECERRSecurity 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, Unikraft Cloud 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:

PolicyDescription
neverNever restart the instance (default).
alwaysAlways restart the instance when the stop is initiated from within the instance (i.e., the application exits or the instance crashes).
on-failureOnly 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. Unikraft Cloud 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.

Scale-To-Zero

With conventional cloud platforms you need to keep at least one instance running at all times to be able to respond to incoming requests. Performing a just-in-time cold boot is simply too time-consuming and would create a response latency of multiple seconds. This is not the case with Unikraft Cloud. Instances on Unikraft Cloud are able to cold boot within milliseconds, which allows us to perform low-latency scale-to-zero.

To enable scale-to-zero for an instance it is sufficient to add a scale_to_zero configuration block. Unikraft Cloud will then put the instance into standby if there is no traffic to your service within the window of a cooldown period. When there is new traffic coming in, it is automatically started again.

If you have a heavyweight application that takes long to cold boot or has bad first request latency (e.g., with JIT compilation) consider to enable stateful scale-to-zero.

Policy

With the scale-to-zero policy you define under which circumstances Unikraft Cloud should put your instance into standby.

Unikraft Cloud currently supports the following scale-to-zero policies:

PolicyDescription
offScale-to-zero is not enabled. The instance keeps on running until manually stopped
onScale-to-zero is enabled. When there are no TCP connections or HTTP requests for the duration of the cooldown time, the instance is put into standby
idleSame as on, but also puts the instance into standby when there are TCP connections established that have been inactive for the duration of the cooldown time. The connections remain established and incoming packets wake up the instance. Scale-to-zero does not happen while there are active HTTP requests (i.e., traffic on ports, which have been marked with the http handler)

Application Support for Scale-To-Zero

Scale-to-zero can be used without any support from your application. However, there are cases where making your application aware of scale-to-zero makes sense.

Background Jobs For example, you want to run background jobs after your application has responded to a request (e.g., send trace information to a logging server). In this case, you may want to temporarily disable scale-to-zero to make sure your instance is not put to sleep while still performing work.

Long Request Processing The same is true if you application can have long request processing times. Consider a setup where you use the idle policy with plain TCP connections and configure a cooldown time of 10s. If it takes your application 15s to process a request until the first response data is sent, Unikraft Cloud will prematurely scale your instance to zero1.

While configuring a longer cooldown time can be a simple solution in some cases, this is not possible if the maximum duration of background jobs or request processing phases is unknown. It also means that you have to compromise between cost efficiency and reliability of your service.

Unikraft Cloud allows your application to temporarily disable scale-to-zero so you can have both a short cooldown phase and reliable operation no matter how long things may take. To control scale-to-zero from within your application, instances on Unikraft Cloud provide a special file-based interface:

FileDescription
/uk/libukp/scale_to_zero_disableAllows to temporarily disable scale-to-zero

The scale_to_zero_disable pseudo file keeps track of the count of concurrent disable requests. If the count is 0, scale-to-zero is not disabled1, any number larger than 0 means scale-to-zero is temporarily disabled. Using a count instead of a boolean value gives multiple independent workers of your application the ability to disable scale-to-zero individually by incrementing and decrementing the count without having to synchronize.

Reading the file returns the current count. The value is prefixed with an equals sign (i.e., =X with X being the current count). Writing to the file modifies the count. The following strings are accepted:

StringDescription
+Increment the current count by one
-Decrement the current count by one
=XSet the count to X
+XIncrement the current count by X
-XDecrement the current count by X

Any attempt to write an invalid string to the file returns an EINVAL error. Any attempt to set a count less than 0 or larger than 2^64 returns an ERANGE error.

1This is never the case for ports of your service that have the http handler set.
2If it is actually enabled depends on the instance configuration.

Stateful Scale-To-Zero

If your application has a long cold boot phase or suffers from large first response latency, for example, to run JIT compilation and fill caches, using stateful scale-to-zero can dramatically reduce the response time of your service. With stateful scale-to-zero Unikraft Cloud takes a snapshot of the instance state before putting it into standby. When incoming network traffic triggers a wakeup, the snapshot is loaded and the instance resumes execution where it left off - with caches already warm.

As the name suggests, stateful scale-to-zero can also be used to enable scale-to-zero for applications that need to keep state for functional correctness, even if cold boot times are no concern.

API Endpoints

The Unikraft Cloud Instances API provides the following endpoints:

MethodEndpointPurpose and Description
POST/v1/instancesCreates one or more new instances of the specified image.
GET/v1/instancesReturns the current status and the configuration of instances.
DELETE/v1/instancesDeletes the specified instances.
GET/v1/instances/listLists all existing instances.
PUT/v1/instances/startStarts the specified instances.
PUT/v1/instances/stopStops the specified instances, but does not destroy them.
GET/v1/instances/waitWaits until one or more instances have reached the desired state.
GET/v1/instances/logReturns the console log output of the specified instances.
GET/v1/instances/metricsReturns metrics of the specified instances.

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 introduction for more information on how to connect to the API.

Creating a New Instance

Creates a new instance of the specified Unikraft Cloud 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

Body ParameterTypeDefaultRequiredDescription
name1NameName of the instance. The instance will receive a DNS entry in your private network of the form <name>.internal
image2string✔️Name of the Unikraft image to instantiate. Private images will be available under your user’s namespace
argsstring | array of stringsApplication arguments
envobjectKey/value pairs to be set as environment variables at boot time. Values must be strings
memory_mbint128Amount of memory to assign to the instance in megabytes
service_groupobjectDescription of published services
    uuid | name3UUID | NameUUID or name of an existing service
    services3array of objectsDescription of exposed network services
        portint✔️Public-facing Port
        destination_portintSame as portPort that the image listens on
        handlersarray of stringsSee Connection Handlers
    domainsarray of objectsauto-generatedDescription of domains to associate with the service (see here)
        namestring✔️Publicly accessible domain name
        certificateobjectauto-generatedTLS certificate to use for the domain
            uuid | nameUUID | Name✔️UUID or name of the certificate
volumesarray of objectsDescription of volumes
    uuid | name4UUID | NameUUID or name of an existing volume. Must be in available state
    size_mb4int✔️Size of the new volume in megabytes
    atstring✔️Path of the mountpoint. Must be empty. Automatically created if it does not exist
    readonlyboolfalseWhether the volume should be mounted read-only
autostartboolfalseAutostart behavior. If true the instance will start immediately after creation
replicasint0Number of instance replicas to create with these properties
wait_timeout_ms5int0Timeout to wait for all new instances to reach running state in milliseconds. No wait performed for 0
featuresarray of stringsSet of features to enable for the instance (see below)
restart_policystringneverAuto-restart policy (see here)
scale_to_zeroobjectScale-to-zero configuration
    policystring✔️Scale-to-zero policy to use
    cooldown_time_msint1000Cooldown time in milliseconds
    statefulboolfalseWhether to use stateful scale-to-zero

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 Unikraft Cloud 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 via uuid or name, or provide a description of a new service. If a description for a new service is provided, the service is created and the instance attached. The service will receive an auto-generated name. Specifying an empty service_group object creates a new service 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:

FeatureDescription
scale-to-zeroEnables scale-to-zero using the default configuration with policy=on.

This feature string is deprecated and will be removed in future versions. Use the scale_to_zero configuration object instead.
delete-on-stopMakes the instance ephemeral so that it is automatically deleted when it stops.
Example of creating an instance
curl -X POST \
-H "Authorization: Bearer ${UKC_TOKEN}" \
-H "Content-Type: application/json" \
"https://api.fra0.kraft.cloud/v1/instances" \
-d "{
'name': 'myapp',
'image': '${UKC_USER}/myapp:latest',
'args': [
'--quiet',
'--listen 0.0.0.0:8080'
],
'env': {
'MY_VAR': 'MY_VALUE'
},
'memory_mb': 128,
'service_group': {
'services': [
{
'port': 443,
'destination_port': 8080,
'handlers': [
'tls', 'http'
]
}
]
},
'volumes': [
{
'size_mb': 100,
'at': '/mnt/'
}
],
'autostart': true
}"

Response

The response is embedded in a JSON object as described in API Responses.

FieldTypeDescription
statusstringsuccess on success, or error if the request failed
stateStateCurrent state of the instance
uuidUUIDUUID of the newly created instance
nameNameName of the newly created instance
private_fqdnstringLocal fully-qualified domain name of the instance
private_ipstringPrivate IPv4 of the instance for communication between instances of the same user
service_group1objectDescription of the service that the instance is part of
    uuidUUIDUUID of the service
    nameNameName of the service
    domainsarray of objectsDescription of domains associated with the service
        fqdnstringPublic fully-qualified domain name under which the service is accessible from the Internet
        certificate2objectTLS certificate used for the domain
            uuidUUIDUUID of the certificate
            nameNameName of the certificate
            stateStateState of the certificate
boot_time_us3intBoot time of the instance in microseconds

1 Only if attached to a service.
2 Not for subdomains of <metro>.kraft.host.
3 Only if autostart and wait_timeout_ms are set.

Status 200 OK
{
"status": "success",
"data": {
"instances": [
{
"status": "success",
"state": "starting",
"uuid": "77d0316a-fbbe-488d-8618-5bf7a612477a",
"name": "myapp",
"private_fqdn:": "myapp.internal",
"private_ip": "172.16.0.5",
"service_group": {
"uuid": "b8a1f5dc-601e-43e2-ab00-3832c832f3ff",
"name": "young-monkey-uq6dxq0u",
"domains": [
{
"fqdn": "young-monkey-uq6dxq0u.fra0.kraft.host"
}
]
}
}
]
}
}

Getting the Status of an Instance

Returns the current status and the configuration of a particular instance if a UUID or name is specified. Otherwise, returns the current status and configuration of all instances.

Request

Endpoints:
GET /v1/instances
GET /v1/instances/<UUID>

Query ParameterTypeDefaultRequiredDescription
detailsbooltrueWhether to provide detailed status and configuration information
metricsboolfalseWhether to include metrics in the detailed status
name1string | list of stringsNames of instances to return as comma-separated list
uuid1string | list of stringsUUIDs of instances to return as comma-separated list
Body ParameterTypeDefaultRequiredDescription
uuid | name1,2UUID | Name✔️UUID or name of the instance to get the status for

1 Not allowed in local scope.
2 You need to specify either uuid or name within the same body object.

Example of getting the status of instances
curl -X GET \
-H "Authorization: Bearer ${UKC_TOKEN}" \
"https://api.fra0.kraft.cloud/v1/instances/77d0316a-fbbe-488d-8618-5bf7a612477a"
Terminal window
curl -X GET \
-H "Authorization: Bearer ${UKC_TOKEN}" \
"https://api.fra0.kraft.cloud/v1/instances" \
-d '[
{
"uuid": "77d0316a-fbbe-488d-8618-5bf7a612477a"
},
{
"name": "my-instance"
}
]'
Terminal window
curl -X GET \
-H "Authorization: Bearer ${UKC_TOKEN}" \
"https://api.fra0.kraft.cloud/v1/instances?name=my-instance,my-other-instance"
Terminal window
curl -X GET \
-H "Authorization: Bearer ${UKC_TOKEN}" \
"https://api.fra0.kraft.cloud/v1/instances?details=false"

Response

The response is embedded in a JSON object as described in API Responses.

FieldTypeDescription
status1stringsuccess on success, or error if the request failed
uuidUUIDUUID of the instance
nameNameName of the instance
created_atstringDate and time of creation in ISO8601
stateStateCurrent state of the instance
image2stringDigest of the image that the instance uses
memory_mbintAmount of memory assigned to the instance in megabytes
argsarray of stringsApplication arguments
envobjectKey/value pairs to be set as environment variables at boot time
start_countintTotal number of times the instance has been started
started_atstringDate and time of last start in ISO8601
stopped_atstringIf stopped, date and time of stop in ISO8601
uptime_msintTotal uptime of instance in milliseconds
rss_bytes3intResident set size (RSS) of the VMM in bytes (see here for remarks on RSS)
cpu_time_ms3intTotal consumed CPU time in milliseconds
nconns3intNumber of currently established inbound connections (non-HTTP)
nreqs3intNumber of in-flight HTTP requests
nqueued3intNumber of queued inbound connections and HTTP requests
ntotal3intTotal number of inbound connections and HTTP requests handled
vmm_start_time_us4intTime from start of instance to VMM process start in microseconds
vmm_load_time_us4intTime from start of instance to finish loading of initrd and kernel into instance in microseconds
vmm_ready_time_us4intTime from start of instance to entering instance execution in microseconds
boot_time_usintTime from start of instance to finish booting of Unikraft in microseconds
net_time_us4intTime from start of instance to first listen socket in microseconds
stop_reasonintReason for ongoing or current stop (see here)
exit_codeintExit code of the application
stop_codeintStop code of the kernel (see here)
restart_policystringConfigured restart policy
restartobjectInformation about auto-restarts
    attemptintNumber of restarts performed in the current restart sequence
    next_atstringDate and time of next restart attempt in ISO8601
restart_countintTotal number of times the instance has been restarted by restart policy
scale_to_zeroobjectScale-to-zero configuration
    enabledboolWhether scale-to-zero is currently enabled
    policystringConfigured scale-to-zero policy
    cooldown_time_msintCooldown time in milliseconds
    statefulboolWhether stateful scale-to-zero is enabled
snapshotobject
    uuidUUIDUUID of the snapshot
private_fqdnstringFully-qualified domain name under which the instance is accessible in the private network
private_ipstringPrivate 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_group5objectDescription of the service that the instance is part of
    uuidUUIDUUID of the service
    nameNameName of the service
    domainsarray of objectsDescription of domains associated with the service
        fqdnstringPublic fully-qualified domain name under which the service is accessible from the Internet
        certificate6objectTLS certificate used for the domain
            uuidUUIDUUID of the certificate
            nameNameName of the certificate
            stateStateState of the certificate
volumesarray of objectsDescription of volumes
    uuidUUIDUUID of the volume
    nameNameName of the volume
    atstringPath of the mountpoint
    readonlyboolWhether the volume is mounted read-only
network_interfacesarray of objectsList of network interfaces attached to the instance
    uuidUUIDUUID of the network interface
    private_ipstringPrivate IPv4 of network interface
    macstringMAC address of the network interface
    rx_bytes3intAmount of bytes received from interface
    rx_packets3intCount of packets received from interface
    tx_bytes3intAmount of bytes transmitted over interface
    tx_packets3intCount of packets transmitted over interface

1 Not when listing all existing instances.
2 The image tag (e.g., latest) is translated by Unikraft Cloud to the image digest that was assigned the tag at the time of instance creation. The image is pinned to this particular version.
3 Only with metrics=true query parameter.
4 Only with Unikraft Cloud developer permissions.
5 Only if attached to a service.
6 Not for subdomains of <metro>.kraft.host.

Status 200 OK
{
"status": "success",
"data": {
"instances": [
{
"status": "success",
"uuid": "77d0316a-fbbe-488d-8618-5bf7a612477a",
"name": "myapp",
"created_at": "2023-08-21T16:38:15Z",
"state": "starting",
"image": "${UKC_USER}/myapp@sha256:c4c2919...f03db26",
"memory_mb": 128,
"args": [
"--quiet",
"--listen 0.0.0.0:8080"
],
"env": {
"MY_VAR": "MY_VALUE"
},
"start_count": 1,
"started_at": "2023-08-21T16:38:15Z",
"uptime_ms": 12,
"restart_policy": "never",
"private_fqdn": "myapp.internal",
"private_ip": "172.16.0.5",
"service_group": {
"uuid": "b8a1f5dc-601e-43e2-ab00-3832c832f3ff",
"name": "young-monkey-uq6dxq0u",
"domains": [
{
"fqdn": "young-monkey-uq6dxq0u.fra0.kraft.host"
}
]
},
"network_interfaces": [
{
"uuid": "5ccad8a3-751a-47c6-a31f-8cd0d4cdb979",
"private_ip": "172.16.0.5",
"mac": "12:b0:ac:10:00:05"
}
],
"volumes": [
{
"uuid": "0a8b68b2-7367-4a6c-9453-edbccf5fb218",
"at": "/mnt/",
"readonly": false
}
]
}
]
}
}

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 and deletes all instances created by autoscale.

Request

Endpoints:
DELETE /v1/instances
DELETE /v1/instances/<UUID>

Query ParameterTypeDefaultRequiredDescription
name1string | list of stringsNames of instances to delete as comma-separated list
uuid1string | list of stringsUUIDs of instances to delete as comma-separated list
Body ParameterTypeDefaultRequiredDescription
uuid | name1,2UUID | Name✔️UUID or name of the instance to delete

1 Not allowed in local scope.
2 You need to specify either uuid or name within the same body object.

Example of deleting a specific instance
curl -X DELETE \
-H "Authorization: Bearer ${UKC_TOKEN}" \
"https://api.fra0.kraft.cloud/v1/instances/77d0316a-fbbe-488d-8618-5bf7a612477a"

Response

The response is embedded in a JSON object as described in API Responses.

FieldTypeDescription
statusstringsuccess on success, or error if the request failed
uuidUUIDUUID of the instance
nameNameName of the instance
previous_stateStateState of the instance before the call
Status 200 OK
{
"status": "success",
"data": {
"instances": [
{
"status": "success",
"uuid": "77d0316a-fbbe-488d-8618-5bf7a612477a",
"name": "myapp",
"previous_state": "stopped"
}
]
}
}

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

Body ParameterTypeDefaultRequiredDescription
stateStateState for filtering
Example of listing all existing instances
curl -X GET \
-H "Authorization: Bearer ${UKC_TOKEN}" \
"https://api.fra0.kraft.cloud/v1/instances/list"
Example of listing all instances currently stopping or already stopped
curl -X GET \
-H "Authorization: Bearer ${UKC_TOKEN}" \
-H "Content-Type: application/json" \
"https://api.fra0.kraft.cloud/v1/instances/list" \
-d '[{
"state": "stopping"
},
{
"state": "stopped"
}]'

Response

The response is embedded in a JSON object as described in API Responses.

FieldTypeDescription
uuidUUIDUUID of the instance
nameNameName of the instance
Status 200 OK
{
"status": "success",
"data": {
"instances": [
{
"uuid": "77d0316a-fbbe-488d-8618-5bf7a612477a",
"name": "myapp"
},
{
"uuid": "d6bb5ad2-402e-4f8d-981d-caf52110426e",
"name": "myapp-2"
}
]
}
}

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

Query ParameterTypeDefaultRequiredDescription
name1string | list of stringsNames of instances to start as comma-separated list
uuid1string | list of stringsUUIDs of instances to start as comma-separated list
Body ParameterTypeDefaultRequiredDescription
uuid | name1,2UUID | Name✔️UUID or name of the instance to start
wait_timeout_ms3int0Timeout to wait for all specified instances to reach running state in milliseconds. No wait performed for 0

1 Not allowed in local scope.
2 You need to specify either uuid or name within the same body object.
3 The maximum timeout may vary. Use -1 for the largest possible value.

Example of starting a specific instance
curl -X PUT \
-H "Authorization: Bearer ${UKC_TOKEN}" \
"https://api.fra0.kraft.cloud/v1/instances/77d0316a-fbbe-488d-8618-5bf7a612477a/start"

Response

The response is embedded in a JSON object as described in API Responses.

FieldTypeDescription
statusstringsuccess on success, or error if the request failed
uuidUUIDUUID of the instance
nameNameName of the instance
stateStateCurrent state of the instance
previous_stateStateState of the instance before the call
Status 200 OK
{
"status": "success",
"data": {
"instances": [
{
"status": "success",
"uuid": "77d0316a-fbbe-488d-8618-5bf7a612477a",
"name": "myapp",
"state": "starting",
"previous_state": "stopped"
}
]
}
}

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

Query ParameterTypeDefaultRequiredDescription
name1string | list of stringsNames of instances to stop as comma-separated list
uuid1string | list of stringsUUIDs of instances to stop as comma-separated list
Body ParameterTypeDefaultRequiredDescription
uuid | name1,2UUID | Name✔️UUID or name of the instance to stop
forceboolfalseForces immediate shutdown
drain_timeout_ms3int0Timeout 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.
2 You need to specify either uuid or name within the same body object.
3 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

Example of stopping a specific instance
curl -X PUT \
-H "Authorization: Bearer ${UKC_TOKEN}" \
"https://api.fra0.kraft.cloud/v1/instances/77d0316a-fbbe-488d-8618-5bf7a612477a/stop"
Example of stopping a specific instance with draining connections for at most 1 minute
curl -X PUT \
-H "Authorization: Bearer ${UKC_TOKEN}" \
-H "Content-Type: application/json" \
"https://api.fra0.kraft.cloud/v1/instances/77d0316a-fbbe-488d-8618-5bf7a612477a/stop" \
-d '{
"drain_timeout_ms": 60000
}'

Response

The response is embedded in a JSON object as described in API Responses.

FieldTypeDescription
statusstringsuccess on success, or error if the request failed
uuidUUIDUUID of the instance
nameNameName of the instance
stateStateCurrent state of the instance
previous_stateStateState of the instance before the call
Status 200 OK
{
"status": "success",
"data": {
"instances": [
{
"status": "success",
"uuid": "77d0316a-fbbe-488d-8618-5bf7a612477a",
"name": "myapp",
"state": "draining",
"previous_state": "running"
}
]
}
}

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

Body ParameterTypeDefaultRequiredDescription
uuid | name1,2UUID | NameUUID or name of an existing instance
ids1array of objectsIDs of the instances to wait for
    uuid | name2UUID | NameUUID or name of an existing instance
stateStaterunningState to wait for
timeout_ms4int-1Timeout for the wait in milliseconds

1 Not allowed in local scope.
2 You need to specify either uuid or name within the same body object.
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.

Example of waiting for a specific instance to be started
curl -X GET \
-H "Authorization: Bearer ${UKC_TOKEN}" \
"https://api.fra0.kraft.cloud/v1/instances/77d0316a-fbbe-488d-8618-5bf7a612477a/wait"

Response

The response is embedded in a JSON object as described in API Responses.

FieldTypeDescription
statusstringsuccess on success, or error if the request failed
uuidUUIDUUID of the instance
nameNameName of the instance
stateStateCurrent state of the instance
Status 200 OK
{
"status": "success",
"data": {
"instances": [
{
"status": "success",
"uuid": "77d0316a-fbbe-488d-8618-5bf7a612477a",
"name": "myapp",
"state": "running"
}
]
}
}

Retrieving 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

Query ParameterTypeDefaultRequiredDescription
name1string | list of stringsNames of instances to return logs for as comma-separated list
uuid1string | list of stringsUUIDs of instances to return logs for as comma-separated list
Body ParameterTypeDefaultRequiredDescription
uuid | name1,2UUID | Name✔️UUID or name of the instance to return log output for
offsetint-4096The byte offset of the log output to receive. A negative sign makes the offset relative to the end of the log.
limitint4096The amount of bytes to return at most.

1Not allowed in local scope.
2You need to specify either uuid or name within the same body object.

Example of getting the log output of an instance
curl -X GET \
-H "Authorization: Bearer ${UKC_TOKEN}" \
"https://api.fra0.kraft.cloud/v1/instances/77d0316a-fbbe-488d-8618-5bf7a612477a/log"

Response

The response is embedded in a JSON object as described in API Responses.

FieldTypeDescription
statusstringsuccess on success, or error if the request failed
uuidUUIDUUID of the instance
nameNameName of the instance
outputstringBASE64 encoded log output
availableobjectDescription of the log availability
    startintThe first byte offset that can be retrieved
    endintThe last byte offset that can be retrieved
rangeobjectDescription of the range that was returned. Useful for requests with offset relative to end.
    startintThe first retrieved byte
    endintThe last retrieved byte
Status 200 OK
{
"status": "success",
"data": {
"instances": [
{
"status": "success",
"uuid": "77d0316a-fbbe-488d-8618-5bf7a612477a",
"name": "myapp",
"available": {
"start": 0,
"end": 42
},
"output": "..."
}
]
}
}

To decode the base64 formatted log output on the command line you can use tools like jq and base64:

Example of decoding the log output
curl -X GET \
-H "Authorization: Bearer ${UKC_TOKEN}" \
"https://api.fra0.kraft.cloud/v1/instances/77d0316a-fbbe-488d-8618-5bf7a612477a/log"
| jq -r '.data.instances[].output' | base64 -d

Retrieving Instance Metrics

Returns the various instances metrics like CPU time and network traffic statistics. Cumulative metrics (e.g., used CPU time) are accumulated over instance starts. This endpoint can return either a JSON-encoded response or a response in the Prometheus format.

Request

Endpoints:
GET /v1/instances/metrics
GET /v1/instances/<UUID>/metrics

Query ParameterTypeDefaultRequiredDescription
name1string | list of stringsNames of instances to return metrics for as comma-separated list
uuid1string | list of stringsUUIDs of instances to return metrics for as comma-separated list
Body ParameterTypeDefaultRequiredDescription
uuid | name1,2UUID | Name✔️UUID or name of the instance to return metrics for

1Not allowed in local scope.
2You need to specify either uuid or name within the same body object.

Example of getting metrics of an instance
curl -X GET \
-H "Authorization: Bearer ${UKC_TOKEN}" \
-H "Accept: application/json" \
"https://api.fra0.kraft.cloud/v1/instances/77d0316a-fbbe-488d-8618-5bf7a612477a/metrics"

Response

The endpoint returns a JSON object as described in API Responses when the HTTP Accept header specifies application/json. Otherwise, the endpoint returns a response in the Prometheus format.

FieldTypeDescription
uuidUUIDUUID of the instance
nameNameName of the instance
rss_bytes1intResident set size of the VMM in bytes
cpu_time_msintConsumed CPU time in milliseconds
rx_bytesintTotal amount of bytes received from network
rx_packetsintTotal count of packets received from network
tx_bytesintTotal amount of bytes transmitted over network
tx_packetsintTotal count of packets transmitted over network
nconnsintNumber of currently established inbound connections (non-HTTP)
nreqsintNumber of in-flight HTTP requests
nqueuedintNumber of queued inbound connections and HTTP requests
ntotalintTotal number of inbound connections and HTTP requests handled

1 The resident set size (RSS) specifies the amount of physical memory that has been touched by the instance and is currently reserved for the instance on the Unikraft Cloud server. The RSS grows until the instance has touched all memory assigned to it via the memory_mb setting and may also exceed this value as supporting services running outside the instance acquire memory. The RSS is different from the current amount of memory allocated by the application, which is likely to fluctuate over the lifetime of the application. The RSS is not a cumulative metric. When the instance is stopped rss goes down to 0.


Status 200 OK
{
"status": "success",
"data": {
"instances": [
{
"uuid": "77d0316a-fbbe-488d-8618-5bf7a612477a",
"name": "myapp",
"rss_bytes": 86347300,
"cpu_time_ms": 130,
"rx_bytes": 3100,
"rx_packets": 42,
"tx_bytes": 1000,
"tx_packets": 12,
"nconns": 0,
"nreqs": 2,
"ntotal": 2324,
"nqueued": 0
}
]
}
}