Service Groups

Server

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.sfo.unikraft.cloud

/v1/services

List service groups.

List Service Groups › query Parameters

uuid

string[]

The UUID of the resource.

name

string[]

The name of the resource.

details

boolean

count

integer · uint32

from

string

order

Common.PaginationOrder · enum

The sort order used by list endpoints.

Enum values:

asc

desc

sortby

Common.PaginationSortBy · enum

The sort field used by list endpoints.

Enum values:

create_time

List Service Groups › Request Body optional

Common.NameOrUUID[]

An identifier for a resource — either a name or a UUID, but not both.

Common.NameOrUUID

uuid

string · uuid

The UUID of the resource.

name

string

The name of the resource.

oneOf

Exactly one variant must match.

Decision Table

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

Properties for Variant 1:

uuid

string · uuid · required

The UUID of the resource.

name

string

The name of the resource.

List Service Groups › Responses

200

The request has succeeded.

The response message for getting one or more service group(s) given their UUID(s) or name(s).

Services.GetServiceGroupsResponse

status

string · enum · required

The status of the response.

Enum values:

success

error

partial_success

op_time_us

integer · uint64 · required

The operation time in microseconds.

message

string

An optional message providing additional information about the status.

object

The response data for this request.

Common.ResponseError[]

A list of errors which may have occurred during the request.

GET/v1/services

curl https://api.sfo.unikraft.cloud/v1/services \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '[
  {
    "uuid": "00000000-0000-0000-0000-000000000000",
    "name": "name"
  }
]'

Example Request Body

[
  {
    "uuid": "00000000-0000-0000-0000-000000000000",
    "name": "name"
  }
]

json

Example Responses

{
  "status": "success",
  "message": "message",
  "data": {
    "service_groups": [
      {
        "status": "success",
        "message": "message",
        "error": 0,
        "uuid": "00000000-0000-0000-0000-000000000000",
        "name": "name",
        "created_at": "2024-08-25T15:00:00Z",
        "persistent": true,
        "autoscale": true,
        "soft_limit": 1,
        "hard_limit": 100,
        "services": [
          {
            "port": 443,
            "destination_port": 8080,
            "protocol": "tcp",
            "ip": "ip",
            "handlers": [
              "tls"
            ]
          }
        ],
        "domains": [
          {
            "fqdn": "example.com.",
            "certificate": {
              "status": "success",
              "message": "message",
              "error": 0,
              "uuid": "00000000-0000-0000-0000-000000000000",
              "name": "name",
              "created_at": "2024-08-25T15:00:00Z",
              "common_name": "my-common-name",
              "subject": "example.com",
              "issuer": "CN=R10,O=Let's Encrypt,C=US",
              "serial_number": "123456789ABCDEF123456789ABCDEF123456",
              "not_before": "2024-08-25T15:00:00Z",
              "not_after": "2024-08-25T15:00:00Z",
              "state": "pending",
              "validation": {
                "attempt": 0,
                "next": "2024-08-25T15:00:00Z"
              },
              "service_groups": [
                {
                  "uuid": "00000000-0000-0000-0000-000000000000",
                  "name": "name"
                }
              ]
            }
          }
        ],
        "instances": [
          {
            "uuid": "00000000-0000-0000-0000-000000000000",
            "name": "name"
          }
        ],
        "autokill": {
          "time_ms": 0
        }
      }
    ]
  },
  "errors": [
    {
      "status": 0
    }
  ],
  "op_time_us": 0
}

json

application/json

Create Service Group

POST

https://api.sfo.unikraft.cloud

/v1/services

Create a new service group.

Create Service Group › Request Body

The request message for creating a new service group.

Services.CreateServiceGroupRequest

Services.Service[] · required

Services to expose. At least one service is required.

name

string

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

Services.CreateServiceGroupRequestDomain[]

Description of domains associated with the service group.

soft_limit

integer · 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_limit

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

object

Automatic delete-on-idle configuration.

Create Service Group › Responses

200

The request has succeeded.

The response message for creating a new service group.

Services.CreateServiceGroupResponse

status

string · enum · required

The status of the response.

Enum values:

success

error

partial_success

op_time_us

integer · uint64 · required

The operation time in microseconds.

message

string

An optional message providing additional information about the status.

object

The response data for this request.

Common.ResponseError[]

A list of errors which may have occurred during the request.

POST/v1/services

curl https://api.sfo.unikraft.cloud/v1/services \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "name": "funky-service-g7gum5cj",
  "services": [
    {
      "port": 443,
      "destination_port": 8080,
      "protocol": "tcp",
      "ip": "ip",
      "handlers": [
        "tls"
      ]
    }
  ],
  "domains": [
    {
      "name": "example.com.",
      "certificate": {
        "uuid": "00000000-0000-0000-0000-000000000000",
        "name": "name"
      }
    }
  ],
  "soft_limit": 1,
  "hard_limit": 100,
  "autokill": {
    "time_ms": 0
  }
}'

Example Request Body

{
  "name": "funky-service-g7gum5cj",
  "services": [
    {
      "port": 443,
      "destination_port": 8080,
      "protocol": "tcp",
      "ip": "ip",
      "handlers": [
        "tls"
      ]
    }
  ],
  "domains": [
    {
      "name": "example.com.",
      "certificate": {
        "uuid": "00000000-0000-0000-0000-000000000000",
        "name": "name"
      }
    }
  ],
  "soft_limit": 1,
  "hard_limit": 100,
  "autokill": {
    "time_ms": 0
  }
}

json

Example Responses

{
  "status": "success",
  "message": "message",
  "data": {
    "service_groups": [
      {
        "status": "success",
        "message": "message",
        "error": 0,
        "uuid": "00000000-0000-0000-0000-000000000000",
        "name": "name",
        "created_at": "2024-08-25T15:00:00Z",
        "persistent": true,
        "autoscale": true,
        "soft_limit": 1,
        "hard_limit": 100,
        "services": [
          {
            "port": 443,
            "destination_port": 8080,
            "protocol": "tcp",
            "ip": "ip",
            "handlers": [
              "tls"
            ]
          }
        ],
        "domains": [
          {
            "fqdn": "example.com.",
            "certificate": {
              "status": "success",
              "message": "message",
              "error": 0,
              "uuid": "00000000-0000-0000-0000-000000000000",
              "name": "name",
              "created_at": "2024-08-25T15:00:00Z",
              "common_name": "my-common-name",
              "subject": "example.com",
              "issuer": "CN=R10,O=Let's Encrypt,C=US",
              "serial_number": "123456789ABCDEF123456789ABCDEF123456",
              "not_before": "2024-08-25T15:00:00Z",
              "not_after": "2024-08-25T15:00:00Z",
              "state": "pending",
              "validation": {
                "attempt": 0,
                "next": "2024-08-25T15:00:00Z"
              },
              "service_groups": [
                {
                  "uuid": "00000000-0000-0000-0000-000000000000",
                  "name": "name"
                }
              ]
            }
          }
        ],
        "instances": [
          {
            "uuid": "00000000-0000-0000-0000-000000000000",
            "name": "name"
          }
        ],
        "autokill": {
          "time_ms": 0
        }
      }
    ]
  },
  "errors": [
    {
      "status": 0
    }
  ],
  "op_time_us": 0
}

json

application/json

Delete Service Groups

DELETE

https://api.sfo.unikraft.cloud

/v1/services

Delete service groups by ID(s).

Delete Service Groups › Request Body

Common.NameOrUUID[]

An identifier for a resource — either a name or a UUID, but not both.

Common.NameOrUUID

uuid

string · uuid

The UUID of the resource.

name

string

The name of the resource.

oneOf

Exactly one variant must match.

Decision Table

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

Properties for Variant 1:

uuid

string · uuid · required

The UUID of the resource.

name

string

The name of the resource.

Delete Service Groups › Responses

200

The request has succeeded.

The response message for deleting of one or more service group(s) given their UUID(s) or name(s).

Services.DeleteServiceGroupsResponse

status

string · enum · required

The status of the response.

Enum values:

success

error

partial_success

op_time_us

integer · uint64 · required

The operation time in microseconds.

message

string

An optional message providing additional information about the status.

object

The response data for this request.

Common.ResponseError[]

A list of errors which may have occurred during the request.

DELETE/v1/services

curl https://api.sfo.unikraft.cloud/v1/services \
  --request DELETE \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '[
  {
    "uuid": "00000000-0000-0000-0000-000000000000",
    "name": "name"
  }
]'

Example Request Body

[
  {
    "uuid": "00000000-0000-0000-0000-000000000000",
    "name": "name"
  }
]

json

Example Responses

{
  "status": "success",
  "message": "message",
  "data": {
    "service_groups": [
      {
        "uuid": "00000000-0000-0000-0000-000000000000",
        "name": "name",
        "status": "success",
        "message": "message",
        "error": 0
      }
    ]
  },
  "errors": [
    {
      "status": 0
    }
  ],
  "op_time_us": 0
}

json

application/json

Update Service Groups

PATCH

https://api.sfo.unikraft.cloud

/v1/services

Update service groups.

Update Service Groups › Request Body

Services.UpdateServiceGroupsRequestItem[]

A single update operation to be applied to a service group.

Services.UpdateServiceGroupsRequestItem

prop

string · enum · required

The property to modify.

Enum values:

services

domains

soft_limit

hard_limit

autokill

op

string · enum · required

The operation to perform.

Enum values:

set

add

del

uuid

string · uuid

The UUID of the resource.

name

string

The name of the resource.

id

string

A client-provided identifier for tracking this operation in the response.

Example: op-1

value

The value for the update operation. The type depends on the property and operation:

For "image": string
For "args": string or array of strings
For "env": object (for SET/ADD) or string/array of strings (for DEL)
For "memory_mb": integer
For "vcpus": integer
For "scale_to_zero": object with cooldown_time_ms, policy, and stateful fields
For "tags": array of strings
For "delete_lock": boolean
For "schedules": array of schedule objects (with name, when, action, and optional args fields). Use action "exec" together with args to execute a command at the scheduled time.
For "autokill": object with time_ms and num_requests fields
For "hostname": string (valid DNS label)
For "roms": array of ROM objects (with name and image fields) for SET/ADD, or array of ROM names for DEL
For "dependencies": array of instance identifiers (name or UUID)
For "sched_priority": SchedPriority enum value ("normal", "medium", "high", "admin")

Update Service Groups › Responses

200

The request has succeeded.

The response message for updating one or more service group(s) given their UUID(s) or name(s).

Services.UpdateServiceGroupsResponse

status

string · enum · required

The status of the response.

Enum values:

success

error

partial_success

op_time_us

integer · uint64 · required

The operation time in microseconds.

message

string

An optional message providing additional information about the status.

object

The response data for this request.

Common.ResponseError[]

A list of errors which may have occurred during the request.

PATCH/v1/services

curl https://api.sfo.unikraft.cloud/v1/services \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '[
  {
    "uuid": "00000000-0000-0000-0000-000000000000",
    "name": "name",
    "id": "op-1",
    "prop": "services",
    "op": "set",
    "value": {}
  }
]'

Example Request Body

[
  {
    "uuid": "00000000-0000-0000-0000-000000000000",
    "name": "name",
    "id": "op-1",
    "prop": "services",
    "op": "set",
    "value": {}
  }
]

json

Example Responses

{
  "status": "success",
  "message": "message",
  "data": {
    "service_groups": [
      {
        "uuid": "00000000-0000-0000-0000-000000000000",
        "name": "name",
        "id": "id",
        "status": "success",
        "message": "message",
        "error": 0
      }
    ]
  },
  "errors": [
    {
      "status": 0
    }
  ],
  "op_time_us": 0
}

json

application/json

Get Service Group by UUID

GET

https://api.sfo.unikraft.cloud

/v1/services/{uuid}

Get a service group by UUID.

Get Service Group by UUID › path Parameters

uuid

string · uuid · required

Get Service Group by UUID › query Parameters

details

boolean

Get Service Group by UUID › Responses

200

The request has succeeded.

The response message for getting one or more service group(s) given their UUID(s) or name(s).

Services.GetServiceGroupsResponse

status

string · enum · required

The status of the response.

Enum values:

success

error

partial_success

op_time_us

integer · uint64 · required

The operation time in microseconds.

message

string

An optional message providing additional information about the status.

object

The response data for this request.

Common.ResponseError[]

A list of errors which may have occurred during the request.

GET/v1/services/{uuid}

curl https://api.sfo.unikraft.cloud/v1/services/:uuid \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "status": "success",
  "message": "message",
  "data": {
    "service_groups": [
      {
        "status": "success",
        "message": "message",
        "error": 0,
        "uuid": "00000000-0000-0000-0000-000000000000",
        "name": "name",
        "created_at": "2024-08-25T15:00:00Z",
        "persistent": true,
        "autoscale": true,
        "soft_limit": 1,
        "hard_limit": 100,
        "services": [
          {
            "port": 443,
            "destination_port": 8080,
            "protocol": "tcp",
            "ip": "ip",
            "handlers": [
              "tls"
            ]
          }
        ],
        "domains": [
          {
            "fqdn": "example.com.",
            "certificate": {
              "status": "success",
              "message": "message",
              "error": 0,
              "uuid": "00000000-0000-0000-0000-000000000000",
              "name": "name",
              "created_at": "2024-08-25T15:00:00Z",
              "common_name": "my-common-name",
              "subject": "example.com",
              "issuer": "CN=R10,O=Let's Encrypt,C=US",
              "serial_number": "123456789ABCDEF123456789ABCDEF123456",
              "not_before": "2024-08-25T15:00:00Z",
              "not_after": "2024-08-25T15:00:00Z",
              "state": "pending",
              "validation": {
                "attempt": 0,
                "next": "2024-08-25T15:00:00Z"
              },
              "service_groups": [
                {
                  "uuid": "00000000-0000-0000-0000-000000000000",
                  "name": "name"
                }
              ]
            }
          }
        ],
        "instances": [
          {
            "uuid": "00000000-0000-0000-0000-000000000000",
            "name": "name"
          }
        ],
        "autokill": {
          "time_ms": 0
        }
      }
    ]
  },
  "errors": [
    {
      "status": 0
    }
  ],
  "op_time_us": 0
}

json

application/json

Delete Service Group by UUID

DELETE

https://api.sfo.unikraft.cloud

/v1/services/{uuid}

Delete a service group by UUID.

Delete Service Group by UUID › path Parameters

uuid

string · uuid · required

Delete Service Group by UUID › Responses

200

The request has succeeded.

The response message for deleting of one or more service group(s) given their UUID(s) or name(s).

Services.DeleteServiceGroupsResponse

status

string · enum · required

The status of the response.

Enum values:

success

error

partial_success

op_time_us

integer · uint64 · required

The operation time in microseconds.

message

string

An optional message providing additional information about the status.

object

The response data for this request.

Common.ResponseError[]

A list of errors which may have occurred during the request.

Update Service Group by UUID

PATCH

https://api.sfo.unikraft.cloud

/v1/services/{uuid}

Update a service group by UUID.

Update Service Group by UUID › path Parameters

uuid

string · uuid · required

Update Service Group by UUID › Request Body

Services.UpdateServiceGroupByUUIDRequestBody

prop

string · enum · required

The property to modify.

Enum values:

services

domains

soft_limit

hard_limit

autokill

op

string · enum · required

The operation to perform.

Enum values:

set

add

del

id

string

A client-provided identifier for tracking this operation in the response.

Example: op-1

value

The value for the update operation. The type depends on the property and operation:

For "image": string
For "args": string or array of strings
For "env": object (for SET/ADD) or string/array of strings (for DEL)
For "memory_mb": integer
For "vcpus": integer
For "scale_to_zero": object with cooldown_time_ms, policy, and stateful fields
For "tags": array of strings
For "delete_lock": boolean
For "schedules": array of schedule objects (with name, when, action, and optional args fields). Use action "exec" together with args to execute a command at the scheduled time.
For "autokill": object with time_ms and num_requests fields
For "hostname": string (valid DNS label)
For "roms": array of ROM objects (with name and image fields) for SET/ADD, or array of ROM names for DEL
For "dependencies": array of instance identifiers (name or UUID)
For "sched_priority": SchedPriority enum value ("normal", "medium", "high", "admin")

Update Service Group by UUID › Responses

200

The request has succeeded.

The response message for updating one or more service group(s) given their UUID(s) or name(s).

Services.UpdateServiceGroupsResponse

status

string · enum · required

The status of the response.

Enum values:

success

error

partial_success

op_time_us

integer · uint64 · required

The operation time in microseconds.

message

string

An optional message providing additional information about the status.

object

The response data for this request.

Common.ResponseError[]

A list of errors which may have occurred during the request.

PATCH/v1/services/{uuid}

curl https://api.sfo.unikraft.cloud/v1/services/:uuid \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "id": "op-1",
  "prop": "services",
  "op": "set",
  "value": {}
}'

Example Request Body

{
  "id": "op-1",
  "prop": "services",
  "op": "set",
  "value": {}
}

json

Example Responses

{
  "status": "success",
  "message": "message",
  "data": {
    "service_groups": [
      {
        "uuid": "00000000-0000-0000-0000-000000000000",
        "name": "name",
        "id": "id",
        "status": "success",
        "message": "message",
        "error": 0
      }
    ]
  },
  "errors": [
    {
      "status": 0
    }
  ],
  "op_time_us": 0
}

json

application/json

Volumes Instances