Skip to content

Instances

This document describes the KraftCloud Instances REST API (v1) for managing Unikraft instances. An instance is a Unikraft unikernel running a single instance of your application.

Instance States

An instance can be in one of the following states:

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.

API Endpoints

The KraftCloud Instances REST 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/consoleReturns the console output 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 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

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 group
    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
    dns_namestringPublicly accessible DNS name of the service group (see here)
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)

1 If no name is specified a random name of the form <app>-X is auto-generated, where <app> is the application name taken from image (e.g., myapp for ../myapp:latest) and X is a 5 character long random alphanumeric suffix.
2 The image tag (e.g., latest) is translated by KraftCloud to the image digest that the tag was pointing to at the time of instance creation. The image is pinned to this particular version.
3 You need to specify either an existing service group via uuid or name, or provide a description of a new service group. If a description for a new service group is provided, the service group is created and the instance attached. The service group will receive an auto-generated name. Specifying an empty service_group object creates a new service group with no services published.
4 You need to specify either uuid, name, or size_mb. Specifying size_mb will create a new volume and attach it to the instance. The volume will receive an auto-generated name.
5 Only valid if autostart is true. The maximum timeout may vary. Use -1 for the largest possible value.

The features field accepts the following values:

FeatureDescription
scale-to-zeroEnables scale-to-zero using the default autoscale configuration with min_size and max_size set to 0 and 1, respectively.
Example of creating an instance
curl -X POST \
-H "Authorization: Bearer ${KRAFTCLOUD_TOKEN}" \
-H "Content-Type: application/json" \
"https://api.fra0.kraft.cloud/v1/instances" \
-d "{
'name': 'myapp',
'image': '${KRAFTCLOUD_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
fqdn1stringPublicly accessible fully-qualified domain name of the instance
private_fqdnstringLocal fully-qualified domain name of the instance
private_ipstringPrivate IPv4 of the instance for communication between instances of the same user
boot_time_us2intBoot time of the instance in microseconds

1 Only if attached to a service group.
2 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",
"fqdn": "young-monkey-uq6dxq0u.fra0.kraft.host",
"private_fqdn:": "myapp.internal",
"private_ip": "172.16.0.5"
}
]
}
}

Getting the Status of an Instance

Returns the current status and the configuration of an instance.

Request

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

ParameterTypeDefaultRequiredDescription
uuid | name1UUID | Name✔️UUID or name of the instance to get the status for

1 Not allowed in local scope. You need to specify either uuid or name.

Example of getting the status of a specific instance
curl -X GET \
-H "Authorization: Bearer ${KRAFTCLOUD_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
created_atstringDate and time of creation in ISO8601
stateStateCurrent state of the instance
image1stringDigest 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
fqdnstringPublicly accessible fully-qualified domain name of the instance
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_groupobjectDescription of the service group that the instance is part of
    uuidUUIDUUID of the service
    nameNameName of the service
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
boot_time_usintTime it took to start the instance including booting Unikraft in microseconds

1 The image tag (e.g., latest) is translated by KraftCloud to the image digest that was assigned the tag at the time of instance creation. The image is pinned to this particular version.

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",
"private_fqdn": "myapp.internal",
"image": "${KRAFTCLOUD_USER}/myapp@sha256:c4c2919...f03db26",
"memory_mb": 128,
"args": [
"--quiet",
"--listen 0.0.0.0:8080"
],
"env": {
"MY_VAR": "MY_VALUE"
},
"service_group": {
"uuid": "b8a1f5dc-601e-43e2-ab00-3832c832f3ff",
"name": "young-monkey-uq6dxq0u"
},
"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"
}
],
"private_ip": "172.16.0.5",
"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 group and deletes all instances created by autoscale.

Request

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

ParameterTypeDefaultRequiredDescription
uuid | name1UUID | Name✔️UUID or name of the instance to delete

1 Not allowed in local scope. You need to specify either uuid or name.

Example of deleting a specific instance
curl -X DELETE \
-H "Authorization: Bearer ${KRAFTCLOUD_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

ParameterTypeDefaultRequiredDescription
stateStateState for filtering
Example of listing all existing instances
curl -X GET \
-H "Authorization: Bearer ${KRAFTCLOUD_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 ${KRAFTCLOUD_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

ParameterTypeDefaultRequiredDescription
uuid | name1UUID | Name✔️UUID or name of the instance to start
wait_timeout_ms2int0Timeout to wait for all specified instances to reach running state in milliseconds. No wait performed for 0

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

Example of starting a specific instance
curl -X PUT \
-H "Authorization: Bearer ${KRAFTCLOUD_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

ParameterTypeDefaultRequiredDescription
uuid | name1UUID | Name✔️UUID or name of the instance to stop
forceboolfalseForces immediate shutdown
drain_timeout_ms2int0Timeout for draining connections in milliseconds. The instance does not receive new connections in the draining phase. The instance is stopped when the last connection has been closed or the timeout expired

1 Not allowed in local scope. You need to specify either uuid or name.
2 The maximum timeout may vary. Use -1 for the largest possible value. The call does not block. Use wait to wait for the instance to reach the stopped state

Example of stopping a specific instance
curl -X PUT \
-H "Authorization: Bearer ${KRAFTCLOUD_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 ${KRAFTCLOUD_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

ParameterTypeDefaultRequiredDescription
id1object | array of objects✔️IDs of the instances to wait for
    uuid | name2UUID | NameUUID or name of an existing instance
stateStaterunningState to wait for
timeout_ms3int-1Timeout for the wait in milliseconds

1 Not allowed in local scope.
2 You need to specify either uuid or name.
3 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 ${KRAFTCLOUD_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"
}
]
}
}

Retrieve the Console Output

Returns the console output of the specified instance in base64 encoding. Note that the maximum response size is capped. The console output might thus be cut off.

Request

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

ParameterTypeDefaultRequiredDescription
uuid | name1UUID | Name✔️UUID or name of the instance to return console output for
max_linesint-1Number of lines to return. -1 for the maximum number of lines
latestbooltrueReturn the latest max_lines lines

1 Not allowed in local scope. You need to specify either uuid or name.

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

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 console output
Status 200 OK
{
"status": "success",
"data": {
"instances": [
{
"status": "success",
"uuid": "77d0316a-fbbe-488d-8618-5bf7a612477a",
"name": "myapp",
"output": "..."
}
]
}
}

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

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