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 one or many service groups with their current status and configuration. It's possible to filter this list by name or UUID.
query Parameters
detailsWhether 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.
countThe maximum number of service groups to return. If set to 0 or not set, all service groups matching filters will be returned. When filtering by IDs, this should not be set.
fromIf set, the listing starts from the service group with the given UUID or at the given ISO8601 creation timestamp (inclusive). When count is 0 or not set, a UUID value may be used to match a specific service group by UUID.
orderThe sort order for the returned service groups.
Valid values are PAGINATION_ORDER_ASC (ascending, oldest first) and
PAGINATION_ORDER_DESC (descending, newest first). Defaults to
PAGINATION_ORDER_ASC.
sortbyThe field to sort the service groups by.
Currently only PAGINATION_SORT_BY_CREATE_TIME is supported. Defaults to
PAGINATION_SORT_BY_CREATE_TIME.
List Service Groups › Request Body
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object · requires: uuid | |
| type = object · requires: name |
uuidMutually exclusive with name.
List Service Groups › Responses
default
statusThe status of the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
Create Service Group
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
nameName 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.
metro(Only applies when using global control plane). The metro to route the request to.
Description of exposed services.
Description of domains associated with the service group.
soft_limitThe 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.
hard_limitThe 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).
Automatic delete-on-idle configuration.
Create Service Group › Responses
default
statusThe status of the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
Delete Service Groups
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
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object · requires: uuid | |
| type = object · requires: name |
uuidMutually exclusive with name.
Delete Service Groups › Responses
default
statusThe status of the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
Update Service Groups
Update one or more service groups.
Update Service Groups › Request Body
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object | |
| type = object |
uuidThe UUID of the service group to update. Mutually exclusive with name.
Update Service Groups › Responses
default
statusThe status of the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
Get Service Group by UUID
Get a specified service group by its UUID.
path Parameters
uuidThe UUID of the service group to retrieve.
query Parameters
detailsWhether 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
statusThe status of the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
Delete Service Group by UUID
Delete a specified service group by its UUID. After this call the UUID of the service group is no longer valid.
path Parameters
uuidThe UUID of the service group to delete.
Delete Service Group by UUID › Responses
default
statusThe status of the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.
Update Service Group by UUID
Update a service group by its UUID.
path Parameters
uuidThe UUID of the service group to update.
Update Service Group by UUID › Request Body
propThe property to modify.
opThe operation to perform.
id(Optional). A client-provided identifier for tracking this operation in the response.
valueThe value for the update operation:
- For "services": array of Service objects (same as for creation)
- For "domains": array of Domain objects (same as for creation)
- For "soft_limit": integer (1–65535), must be <= "hard_limit"
- For "hard_limit": integer (1–65535), must be >= "soft_limit"
- For "autokill": object with time_ms field
Update Service Group by UUID › Responses
default
statusThe status of the response.
messageAn optional message providing additional information about the status.
This field is useful when the status is not success.
The response data for this request.
A list of errors which may have occurred during the request.
op_time_usThe operation time in microseconds. This is the time it took to process the request and generate the response.