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:

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, 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:

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

¹A 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.
²A 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	Unikraft 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.
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.

Note

There can be a short delay of a few milliseconds between the instance reaching the stopped state and the stop_reason being updated (or vice versa).

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

¹Reserved 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.

Note

For example, an out-of-memory (OOM) situation usually results in a page fault PGFAULT(4) with errno being ENOMEM(12). Hence, the stop_code would be 0x000C7F04=818948 and the stop_reason would be ----K(1) if the stopped occurred during application execution.

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:

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. 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:

Policy	Description
off	Scale-to-zero is not enabled. The instance keeps on running until manually stopped
on	Scale-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
idle	Same 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)

Note

Unikraft Cloud only considers network traffic that is going through its proxy to control scale-to-zero. Connections that your application actively establishes to servers on the Internet and within Unikraft Cloud bypass the proxy for maximum performance. The instance will thus be put into standby irrespective of the presence of and data sent over such connections.

See how you can make Unikraft Cloud cooperate with your application in these scenarios in the next section.

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 zero¹.

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:

File	Description
/uk/libukp/scale_to_zero_disable	Allows 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 disabled¹, 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:

String	Description
+	Increment the current count by one
-	Decrement the current count by one
=X	Set the count to X
+X	Increment the current count by X
-X	Decrement 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.

Caution

Writing to the file to disable scale-to-zero does not atomically disable scale-to-zero. There can be a short delay (usually a few milliseconds) until changing the value is communicated to the Unikraft Cloud controller which is responsible for making scale-to-zero decisions. Make sure to configure a cooldown time large enough to accomodate for potential signal delay.

¹This is never the case for ports of your service that have the http handler set.
²If 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.

Note

The time to load an instance snapshot is roughly constant and usually in the order of a few milliseconds. This is what is reported in the various boot time metrics. However, the actual memory contents is loaded from the snapshot only at first access. This is to reduce response latency by loading only what is really necessary to process the request at hand. This means that the first few requests might take longer until all required memory has been brought back.

The time to take an instance snapshot during scale-to-zero depends on the amount of memory touched by the application since it was last started.

API Endpoints

The Unikraft Cloud Instances 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.
GET	/v1/instances/metrics	Returns 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.

Local Scope

Local API endpoints directed at a specific instance additionally include the UUID of the instance (i.e., GET /v1/instances/<UUID>)

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.

Batching

You can specify an array of instance descriptions to create multiple instances with different properties with the same call.

Waiting for Instances to Run

If you autostart your new instance, you can wait for it to finish starting with a blocking API call if you specify a wait_timeout_ms greater than zero.

Request

Endpoints:
POST /v1/instances

Body Parameter	Type	Default	Required	Description
name1	Name			Name of the instance. The instance will receive a DNS entry in your private network of the form <name>.internal
image2	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 | name3	UUID | Name			UUID or name of an existing service
services3	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 (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 | name4	UUID | Name			UUID or name of an existing volume. Must be in available state
size_mb4	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_ms5	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)
scale_to_zero	object			Scale-to-zero configuration
policy	string		✔️	Scale-to-zero policy to use
cooldown_time_ms	int	1000		Cooldown time in milliseconds
stateful	bool	false		Whether to use stateful scale-to-zero

¹ 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.
² 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.
³ 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.
⁴ 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.
⁵ 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 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-stop	Makes 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.

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_group1	object	Description of the service 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
fqdn	string	Public fully-qualified domain name under which the service is accessible from the Internet
certificate2	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_us3	int	Boot time of the instance in microseconds

¹ Only if attached to a service.
² Not for subdomains of <metro>.kraft.host.
³ 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"
            }
          ]
        }
      }
    ]
  }
}

Quota Exceeded Error

If you experience a Quota exceeded error (EDQUOT), check your user account’s quota usage and limits.

Instance Stops Immediately

If the instance has not enough physical memory assigned (memory_mb) it is possible that it cannot complete the boot. In this case, a blocking call with wait_timeout_ms will time out and the instance will be reported as stopped when you query its status afterwards. You can retrieve the log output from the kernel via the log endpoint to check for “Out of memory” messages.

In addition, if the instance memory is below the size of the image (i.e., initrd + kernel), the create call will fail. Note that the reported minimal instance memory size in the error message just ensures that the image can be loaded. More memory might still be needed to complete the boot. This is especially the case for large ramdisks.

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.

Batching

In global scope, you can specify an array of status requests to retrieve the status of multiple specific instances with the same call.

Listing All Existing Instances

In global scope, do not provide any IDs via body or query parameters if you want to list all existing instances.

Request

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

Query Parameter	Type	Default	Required	Description
details	bool	true		Whether to provide detailed status and configuration information
metrics	bool	false		Whether to include metrics in the detailed status
name1	string | list of strings			Names of instances to return as comma-separated list
uuid1	string | list of strings			UUIDs of instances to return as comma-separated list

Body Parameter	Type	Default	Required	Description
uuid | name1,2	UUID | Name		✔️	UUID or name of the instance to get the status for

¹ Not allowed in local scope.
² 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"

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"
      }
     ]'

curl -X GET \
     -H "Authorization: Bearer ${UKC_TOKEN}" \
     "https://api.fra0.kraft.cloud/v1/instances?name=my-instance,my-other-instance"

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.

Field	Type	Description
status1	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
image2	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
rss_bytes3	int	Resident set size (RSS) of the VMM in bytes (see here for remarks on RSS)
cpu_time_ms3	int	Total consumed CPU time in milliseconds
nconns3	int	Number of currently established inbound connections (non-HTTP)
nreqs3	int	Number of in-flight HTTP requests
nqueued3	int	Number of queued inbound connections and HTTP requests
ntotal3	int	Total number of inbound connections and HTTP requests handled
vmm_start_time_us4	int	Time from start of instance to VMM process start in microseconds
vmm_load_time_us4	int	Time from start of instance to finish loading of initrd and kernel into instance in microseconds
vmm_ready_time_us4	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_us4	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
scale_to_zero	object	Scale-to-zero configuration
enabled	bool	Whether scale-to-zero is currently enabled
policy	string	Configured scale-to-zero policy
cooldown_time_ms	int	Cooldown time in milliseconds
stateful	bool	Whether stateful scale-to-zero is enabled
snapshot	object
uuid	UUID	UUID of the snapshot
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_group5	object	Description of the service 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
fqdn	string	Public fully-qualified domain name under which the service is accessible from the Internet
certificate6	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
rx_bytes3	int	Amount of bytes received from interface
rx_packets3	int	Count of packets received from interface
tx_bytes3	int	Amount of bytes transmitted over interface
tx_packets3	int	Count of packets transmitted over interface

¹ Not when listing all existing instances.
² 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.
³ Only with metrics=true query parameter.
⁴ Only with Unikraft Cloud developer permissions.
⁵ Only if attached to a service.
⁶ 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.

Caution

This operation cannot be undone. All data associated with the instance is permanently deleted!

Batching

In global scope, you can specify an array of delete requests to delete multiple instances with the same call.

Request

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

Query Parameter	Type	Default	Required	Description
name1	string | list of strings			Names of instances to delete as comma-separated list
uuid1	string | list of strings			UUIDs of instances to delete as comma-separated list

Body Parameter	Type	Default	Required	Description
uuid | name1,2	UUID | Name		✔️	UUID or name of the instance to delete

¹ Not allowed in local scope.
² 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.

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

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.

Caution

This endpoint has been deprecated and will be removed in future versions. Use GET /v1/instances instead.

Request

Endpoints:
GET /v1/instances/list

Body Parameter	Type	Default	Required	Description
state	State			State 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.

Field	Type	Description
uuid	UUID	UUID of the instance
name	Name	Name 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.

Batching

In global scope, you can specify an array of start requests to start multiple instances with the same call.

Request

Endpoints:
PUT /v1/instances/start
PUT /v1/instances/<UUID>/start

Query Parameter	Type	Default	Required	Description
name1	string | list of strings			Names of instances to start as comma-separated list
uuid1	string | list of strings			UUIDs of instances to start as comma-separated list

Body Parameter	Type	Default	Required	Description
uuid | name1,2	UUID | Name		✔️	UUID or name of the instance to start
wait_timeout_ms3	int	0		Timeout to wait for all specified instances to reach running state in milliseconds. No wait performed for 0

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

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

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.

Batching

In global scope, you can specify an array of stop requests to shutdown multiple instances with the same call.

Request

Endpoints:
PUT /v1/instances/stop
PUT /v1/instances/<UUID>/stop

Query Parameter	Type	Default	Required	Description
name1	string | list of strings			Names of instances to stop as comma-separated list
uuid1	string | list of strings			UUIDs of instances to stop as comma-separated list

Body Parameter	Type	Default	Required	Description
uuid | name1,2	UUID | Name		✔️	UUID or name of the instance to stop
force	bool	false		Forces immediate shutdown
drain_timeout_ms3	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

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

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

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.

Batching

In global scope, you can specify an array of wait requests to wait for different states for different instances with the same call. The effective timeout is the minimum timeout over all specified waits.

Request

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

Body Parameter	Type	Default	Required	Description
uuid | name1,2	UUID | Name			UUID or name of an existing instance
ids1	array of objects			IDs of the instances to wait for
uuid | name2	UUID | Name			UUID or name of an existing instance
state	State	running		State to wait for
timeout_ms4	int	-1		Timeout for the wait in milliseconds

¹ Not allowed in local scope.
² You need to specify either uuid or name within the same body object.
³ You cannot combine uuid/name with IDs provided in ids. If you want to specify multiple IDs, specify all of them via ids.
⁴ 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.

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

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.

Batching

In global scope, you can specify an array of log requests to get the log output of multiple instances with the same call.

Request

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

Query Parameter	Type	Default	Required	Description
name1	string | list of strings			Names of instances to return logs for as comma-separated list
uuid1	string | list of strings			UUIDs of instances to return logs for as comma-separated list

Body Parameter	Type	Default	Required	Description
uuid | name1,2	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.

¹Not allowed in local scope.
²You 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.

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

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.

Batching

In global scope, you can specify an array of metric requests to get the metrics of multiple instances with the same call.

Request

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

Query Parameter	Type	Default	Required	Description
name1	string | list of strings			Names of instances to return metrics for as comma-separated list
uuid1	string | list of strings			UUIDs of instances to return metrics for as comma-separated list

Body Parameter	Type	Default	Required	Description
uuid | name1,2	UUID | Name		✔️	UUID or name of the instance to return metrics for

¹Not allowed in local scope.
²You 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.

Field	Type	Description
uuid	UUID	UUID of the instance
name	Name	Name of the instance
rss_bytes1	int	Resident set size of the VMM in bytes
cpu_time_ms	int	Consumed CPU time in milliseconds
rx_bytes	int	Total amount of bytes received from network
rx_packets	int	Total count of packets received from network
tx_bytes	int	Total amount of bytes transmitted over network
tx_packets	int	Total count of packets transmitted over network
nconns	int	Number of currently established inbound connections (non-HTTP)
nreqs	int	Number of in-flight HTTP requests
nqueued	int	Number of queued inbound connections and HTTP requests
ntotal	int	Total number of inbound connections and HTTP requests handled

¹ 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
      }
    ]
  }
}