Instances

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

Instance States

An instance can be in one of the following states:

State	Description
stopped	The instance is not running and does not count against live resource quotas. Connections cannot be established.
starting	The instance is booting up. This usually takes just a few milliseconds.
running	Your application’s main entry point has been reached.
draining	The instance is draining connections before shutting down. No new connections can be established.
stopping	The instance is shutting down.
standby	The instance has scale-to-zero enabled. The instance is not running, but will be automatically started when there are incoming requests.

These are reported as instance state by the endpoints.

Stop Reason

To understand why an instance has been stopped or is in the process of shutting down, KraftCloud provides information about the stop reason. You can retrieve this information via the GET /v1/instances endpoint when an instance is in the draining, stopping, stopped or standby state.

The stop_reason contains a bitmask that tells you the origin of the shutdown:

Bit	4 [F]	3 [U]	2 [P]	1 [A]	0 [K] (LSB)
Desc.	This was a force stop1	Stop initiated by user1	Stop initiated by platform	App exited - exit_code available	Kernel exited - stop_code available

¹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	KraftCloud initiated the shutdown, for example, due to scale-to-zero. The application and kernel have exited. The exit_code and stop_code indicate if the application and kernel shut down cleanly.
3	00011/---AK	The application exited. The exit_code and stop_code indicate if the application and kernel shut down cleanly.
1	00001/----K	The instance likely expierenced a fatal crash and the stop_code contains more information about the cause of the crash.
0	00000/-----	The stop reason is unknown.

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, KraftCloud can auto-restart your instance. Auto-restarts are performed according to the restart policy configured for a particular instance. The policy can have the following values:

Policy	Description
never	Never restart the instance (default).
always	Always restart the instance when the stop is initiated from within the instance (i.e., the application exits or the instance crashes).
on-failure	Only restart the instance if it crashes.

When an instance stops, the stop reason and the configured restart policy are evaluated to decide if a restart should be performed. KraftCloud uses an exponential back-off delay (immediate, 5s, 10s, 20s, 40s, …, 5m) to slow down restarts in tight crash loops. If an instance runs without problems for 10s the back-off delay is reset and the restart sequence ends.

The restart.attempt reported in GET /v1/instances counts the number of restarts performed in the current sequence. The restart.next_at field indicates when the next restart will take place if a back-off delay is in effect.

A manual start or stop of the instance aborts the restart sequence and resets the back-off delay.

API Endpoints

The KraftCloud Instances REST API provides the following endpoints:

Method	Endpoint	Purpose and Description
POST	/v1/instances	Creates one or more new instances of the specified image.
GET	/v1/instances	Returns the current status and the configuration of instances.
DELETE	/v1/instances	Deletes the specified instances.
GET	/v1/instances/list	Lists all existing instances.
PUT	/v1/instances/start	Starts the specified instances.
PUT	/v1/instances/stop	Stops the specified instances, but does not destroy them.
GET	/v1/instances/wait	Waits until one or more instances have reached the desired state.
GET	/v1/instances/log	Returns the console log output of the specified instances.

In the following, the API endpoints are specified relative to this base URL:

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

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 group
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 group (see here)
name	string		✔️	Publicly accessible domain name
certificate	object	auto-generated		TLS certificate to use for the domain
uuid | name	UUID | Name		✔️	UUID or name of the certificate
volumes	array of objects			Description of volumes
uuid | 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)

¹ 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 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.
³ 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.
⁴ 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 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.

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 group that the instance is part of
uuid	UUID	UUID of the service
name	Name	Name of the service
domains	array of objects	Description of domains associated with the service group
fqdn	string	Public fully-qualified domain name under which the group is accessible from the Internet
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 group.
² 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 guest has not enough physical memory assigned (memory_mb) it is possible that the Unikernel 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 guest memory is below the size of the image (i.e., initrd + kernel), the create call will fail. Note that the reported minimal guest 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 an instance.

Batching

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

Request

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

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

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.

Field	Type	Description
status	string	success on success, or error if the request failed
uuid	UUID	UUID of the instance
name	Name	Name of the instance
created_at	string	Date and time of creation in ISO8601
state	State	Current state of the instance
image1	string	Digest of the image that the instance uses
memory_mb	int	Amount of memory assigned to the instance in megabytes
args	array of strings	Application arguments
env	object	Key/value pairs to be set as environment variables at boot time
start_count	int	Total number of times the instance has been started
started_at	string	Date and time of last start in ISO8601
stopped_at	string	If stopped, date and time of stop in ISO8601
uptime_ms	int	Total uptime of instance in milliseconds
vmm_start_time_us2	int	Time from start of instance to VMM process start in microseconds
vmm_load_time_us2	int	Time from start of instance to finish loading of initrd and kernel into instance in microseconds
vmm_ready_time_us2	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_us2	int	Time from start of instance to first listen socket in microseconds
stop_reason	int	Reason for ongoing or current stop (see here)
exit_code	int	Exit code of the application
stop_code	int	Stop code of the kernel (see here)
restart_policy	string	Configured restart policy
restart	object	Information about auto-restarts
attempt	int	Number of restarts performed in the current restart sequence
next_at	string	Date and time of next restart attempt in ISO8601
restart_count	int	Total number of times the instance has been restarted by restart policy
private_fqdn	string	Fully-qualified domain name under which the instance is accessible in the private network
private_ip	string	Private IPv4 of the instance for communication between instances of the same user. This is equivalent to the IPv4 address of the first network interface
service_group3	object	Description of the service group that the instance is part of
uuid	UUID	UUID of the service
name	Name	Name of the service
domains	array of objects	Description of domains associated with the service group
fqdn	string	Public fully-qualified domain name under which the group is accessible from the Internet
certificate4	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

¹ 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.
² Only with KraftCloud developer permissions.
³ Only if attached to a service group.
⁴ 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": "${KRAFTCLOUD_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 group 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>

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

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

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.

Request

Endpoints:
GET /v1/instances/list

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

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

Parameter	Type	Default	Required	Description
uuid | name1	UUID | Name		✔️	UUID or name of the instance to start
wait_timeout_ms2	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.
² 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.

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

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

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

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.
³ 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 ${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.

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

Retrieve the Log Output

Returns the log output of the specified instance in base64 encoding. Note that the maximum response size is capped. The log output might thus be cut off and require multiple requests to fetch further output.

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

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

Example of getting the log output of an instance

curl -X GET \
     -H "Authorization: Bearer ${KRAFTCLOUD_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 ${KRAFTCLOUD_TOKEN}" \
     "https://api.fra0.kraft.cloud/v1/instances/77d0316a-fbbe-488d-8618-5bf7a612477a/log"
     | jq -r '.data.instances[].output' | base64 -d