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 |
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 | 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. |
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, 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) |
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:
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 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:
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.
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:
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:
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 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 | ||
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 (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) | |
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 |
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:
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. |
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 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 |
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.
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 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 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 | |
name 1 | string | list of strings | Names of instances to return as comma-separated list | ||
uuid 1 | string | list of strings | UUIDs of instances to return as comma-separated list |
Body Parameter | Type | Default | Required | Description |
---|---|---|---|---|
uuid | name 1,2 | UUID | 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.
Response
The response is embedded in a JSON object as described in API Responses.
Field | Type | Description |
---|---|---|
status 1 | 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 2 | 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_bytes 3 | int | Resident set size (RSS) of the VMM in bytes (see here for remarks on RSS) |
cpu_time_ms 3 | int | Total consumed CPU time in milliseconds |
nconns 3 | int | Number of currently established inbound connections (non-HTTP) |
nreqs 3 | int | Number of in-flight HTTP requests |
nqueued 3 | int | Number of queued inbound connections and HTTP requests |
ntotal 3 | int | Total number of inbound connections and HTTP requests handled |
vmm_start_time_us 4 | int | Time from start of instance to VMM process start in microseconds |
vmm_load_time_us 4 | int | Time from start of instance to finish loading of initrd and kernel into instance in microseconds |
vmm_ready_time_us 4 | 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 4 | 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_group 5 | 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 |
certificate 6 | 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_bytes 3 | int | Amount of bytes received from interface |
rx_packets 3 | int | Count of packets received from interface |
tx_bytes 3 | int | Amount of bytes transmitted over interface |
tx_packets 3 | int | Count 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
.
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 Parameter | Type | Default | Required | Description |
---|---|---|---|---|
name 1 | string | list of strings | Names of instances to delete as comma-separated list | ||
uuid 1 | string | list of strings | UUIDs of instances to delete as comma-separated list |
Body Parameter | Type | Default | Required | Description |
---|---|---|---|---|
uuid | name 1,2 | UUID | 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.
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
Body 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
Query Parameter | Type | Default | Required | Description |
---|---|---|---|---|
name 1 | string | list of strings | Names of instances to start as comma-separated list | ||
uuid 1 | string | list of strings | UUIDs of instances to start as comma-separated list |
Body Parameter | Type | Default | Required | Description |
---|---|---|---|---|
uuid | name 1,2 | UUID | Name | ✔️ | UUID or name of the instance to start | |
wait_timeout_ms 3 | 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.
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.
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
Query Parameter | Type | Default | Required | Description |
---|---|---|---|---|
name 1 | string | list of strings | Names of instances to stop as comma-separated list | ||
uuid 1 | string | list of strings | UUIDs of instances to stop as comma-separated list |
Body Parameter | Type | Default | Required | Description |
---|---|---|---|---|
uuid | name 1,2 | UUID | Name | ✔️ | UUID or name of the instance to stop | |
force | bool | false | Forces immediate shutdown | |
drain_timeout_ms 3 | 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.
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
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
Body 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
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.
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 |
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 Parameter | Type | Default | Required | Description |
---|---|---|---|---|
name 1 | string | list of strings | Names of instances to return logs for as comma-separated list | ||
uuid 1 | string | list of strings | UUIDs of instances to return logs for as comma-separated list |
Body Parameter | Type | Default | Required | Description |
---|---|---|---|---|
uuid | name 1,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. |
1Not allowed in local scope.
2You need to specify either uuid
or name
within the same body object.
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
:
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 Parameter | Type | Default | Required | Description |
---|---|---|---|---|
name 1 | string | list of strings | Names of instances to return metrics for as comma-separated list | ||
uuid 1 | string | list of strings | UUIDs of instances to return metrics for as comma-separated list |
Body Parameter | Type | Default | Required | Description |
---|---|---|---|---|
uuid | name 1,2 | UUID | 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.
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_bytes 1 | 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 |
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.