Unikraft Cloud Platform API

ServiceGroups

Endpoint

A service group on Unikraft Cloud is used to describe how your application exposes its functionality to the outside world. Once defined, assigning an instance to the service will make it accessible from the Internet.

An application, running as an instance, may expose one or more ports, e.g. it listens on port 80 because your application exposes a HTTP web service. This, along with a set of additional metadata defines how the "service" is configured and accessed. For example, a service may be configured to use TLS, or be bound to a specific domain name.

When an instance is assigned to a service group, it immediately becomes accessible over the Internet on the exposed public port, using the set DNS name, and is routed to the set destination port.

Note: If you do not specify a DNS name when you create a service and you indicate that the application exposes some ports, Unikraft Cloud will generates a random DNS name for you. Unikraft Cloud also supports custom domains like www.example.com and wildcard domains like *.example.com.

List Service Groups

GET

https://api.fra.unikraft.cloud

/v1/services

Get one or many service groups with their current status and configuration. It's possible to filter this list by name or UUID.

List Service Groups › query Parameters

detailsboolean
Whether to include details about the service group in the response. By default this is set to true, meaning that all information about the service group will be included in the response. If set to false, only the basic information about the service group will be included, such as its name and UUID.

List Service Groups › Request Body

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · requires: uuid
	type = object · requires: name

Properties for uuid:

uuidstring · uuid · required
Mutually exclusive with name.
Example: 123e4567-e89b-12d3-a456-426614174000

List Service Groups › Responses

default

statusstring · enum · enum
The status of the response.
Enum values:
success
error
messagestring
An optional message providing additional information about the status. This field is useful when the status is not success.
Example: Failed to perform all operations
dataobject
The response data for this request.
errorsobject[]
A list of errors which may have occurred during the request.
op_time_usinteger · uint64
The operation time in microseconds. This is the time it took to process the request and generate the response.
Example: 46

Create Service Group

POST

https://api.fra.unikraft.cloud

/v1/services

Create a new service with the given configuration.

Note that the service properties like published ports can only be defined during creation. They cannot be changed later. Each port in a service can specify a list of handlers that determine how traffic arriving at the port is handled. See Connection Handlers for a complete overview.

Create Service Group › Request Body

namestring
Name of the service group. This is a human-readable name that can be used to identify the service group. The name must be unique within the context of your account. If no name is specified, a random name is generated for you. The name can also be used to identify the service group in API calls.
Example: funky-service-g7gum5cj
servicesobject[]
Description of exposed services.
domainsobject[]
Description of domains associated with the service group.
soft_limitinteger · uint64
The soft limit is used by the Unikraft Cloud load balancer to decide when to wake up another standby instance.

For example, if the soft limit is set to 5 and the service consists of 2 standby instances, one of the instances receives up to 5 concurrent requests. The 6th parallel requests wakes up the second instance. If there are no more standby instances to wake up, the number of requests assigned to each instance will exceed the soft limit. The load balancer makes sure that when the number of in-flight requests goes down again, instances are put into standby as fast as possible.
Example: 1
hard_limitinteger · uint64
The hard limit defines the maximum number of concurrent requests that an instance assigned to the this service can handle.

The load balancer will never assign more requests to a single instance. In case there are no other instances available, excess requests fail (i.e., they are blocked and not queued).
Example: 100

Create Service Group › Responses

default

statusstring · enum · enum
The status of the response.
Enum values:
success
error
messagestring
An optional message providing additional information about the status. This field is useful when the status is not success.
Example: Failed to perform all operations
dataobject
The response data for this request.
errorsobject[]
A list of errors which may have occurred during the request.
op_time_usinteger · uint64
The operation time in microseconds. This is the time it took to process the request and generate the response.
Example: 46

Delete Service Groups

DELETE

https://api.fra.unikraft.cloud

/v1/services

Delete the specified service group(s). After this call the name of the service group(s) are no longer valid.

Delete Service Groups › Request Body

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · requires: uuid
	type = object · requires: name

Properties for uuid:

uuidstring · uuid · required
Mutually exclusive with name.
Example: 123e4567-e89b-12d3-a456-426614174000

Delete Service Groups › Responses

default

statusstring · enum · enum
The status of the response.
Enum values:
success
error
messagestring
An optional message providing additional information about the status. This field is useful when the status is not success.
Example: Failed to perform all operations
dataobject
The response data for this request.
errorsobject[]
A list of errors which may have occurred during the request.
op_time_usinteger · uint64
The operation time in microseconds. This is the time it took to process the request and generate the response.
Example: 46

Update Service Groups

PATCH

https://api.fra.unikraft.cloud

/v1/services

Update one or more service groups.

Update Service Groups › Request Body

propstring · enum · enum · required
The property to modify.
Enum values:
services
domains
soft_limit
hard_limit
Example: services
opstring · enum · enum · required
The operation to perform.
Enum values:
set
add
del
Example: set

idstring
(Optional). A client-provided identifier for tracking this operation in the response.
Example: op-1
uuidstring · uuid
The UUID of the service group to update. Mutually exclusive with name.
Example: 123e4567-e89b-12d3-a456-426614174000
namestring
The name of the service group to update. Mutually exclusive with UUID.
Example: funky-town-g756b5d
value
The value for the update operation:
- For "services": array of Service objects
- For "domains": array of Domain objects
- For "soft_limit": integer (1–65535), must be <= "hard_limit"
- For "hard_limit": integer (1–65535), must be >= "soft_limit"

Update Service Groups › Responses

default

statusstring · enum · enum
The status of the response.
Enum values:
success
error
messagestring
An optional message providing additional information about the status. This field is useful when the status is not success.
Example: Failed to perform all operations
dataobject
The response data for this request.
errorsobject[]
A list of errors which may have occurred during the request.
op_time_usinteger · uint64
The operation time in microseconds. This is the time it took to process the request and generate the response.
Example: 76

Get Service Group by UUID

GET

https://api.fra.unikraft.cloud

/v1/services/{uuid}

Get a specified service group by its UUID.

Get Service Group by UUID › path Parameters

uuidstring · uuid · required
The UUID of the service group to retrieve.
Example: 12345678-90ab-cdef-1234-567890abcdef

Get Service Group by UUID › query Parameters

detailsboolean
Whether to include details about the service group in the response. By default this is set to true, meaning that all information about the service group will be included in the response. If set to false, only the basic information about the service group will be included, such as its name and UUID.

Get Service Group by UUID › Responses

default

statusstring · enum · enum
The status of the response.
Enum values:
success
error
messagestring
An optional message providing additional information about the status. This field is useful when the status is not success.
Example: Failed to perform all operations
dataobject
The response data for this request.
errorsobject[]
A list of errors which may have occurred during the request.
op_time_usinteger · uint64
The operation time in microseconds. This is the time it took to process the request and generate the response.
Example: 46

Delete Service Group by UUID

DELETE

https://api.fra.unikraft.cloud

/v1/services/{uuid}

Delete a specified service group by its UUID. After this call the UUID of the service group is no longer valid.

Delete Service Group by UUID › path Parameters

uuidstring · uuid · required
The UUID of the service group to delete.
Example: 12345678-90ab-cdef-1234-567890abcdef

Delete Service Group by UUID › Responses

default

statusstring · enum · enum
The status of the response.
Enum values:
success
error
messagestring
An optional message providing additional information about the status. This field is useful when the status is not success.
Example: Failed to perform all operations
dataobject
The response data for this request.
errorsobject[]
A list of errors which may have occurred during the request.
op_time_usinteger · uint64
The operation time in microseconds. This is the time it took to process the request and generate the response.
Example: 46

Update Service Group by UUID

PATCH

https://api.fra.unikraft.cloud

/v1/services/{uuid}

Update a service group by its UUID.

Update Service Group by UUID › path Parameters

uuidstring · uuid · required
The UUID of the service group to update.
Example: 123e4567-e89b-12d3-a456-426614174000

Update Service Group by UUID › Request Body

propstring · enum · enum · required
The property to modify.
Enum values:
services
domains
soft_limit
hard_limit
Example: services
opstring · enum · enum · required
The operation to perform.
Enum values:
set
add
del
Example: set

idstring
(Optional). A client-provided identifier for tracking this operation in the response.
Example: op-1
value
The value for the update operation:
- For "services": array of Service objects
- For "domains": array of Domain objects
- For "soft_limit": integer (1–65535), must be <= "hard_limit"
- For "hard_limit": integer (1–65535), must be >= "soft_limit"

Update Service Group by UUID › Responses

default

statusstring · enum · enum
The status of the response.
Enum values:
success
error
messagestring
An optional message providing additional information about the status. This field is useful when the status is not success.
Example: Failed to perform all operations
dataobject
The response data for this request.
errorsobject[]
A list of errors which may have occurred during the request.
op_time_usinteger · uint64
The operation time in microseconds. This is the time it took to process the request and generate the response.
Example: 76

Instances System