Skip to content

Services

This document describes the KraftCloud Services REST API (v1) for publishing network services and creating load balancing groups. KraftCloud uses service groups to implement this functionality.

Service Groups

A service group has a public DNS name such as my-project.fra0.kraft.host. If you do not specify a DNS name when you create a service group, KraftCloud generates a random DNS name of the form young-monkey-uq6dxq0u.fra0.kraft.host. When you assign an instance to a service group, the instance becomes accessible from the Internet using this DNS name.

By default, a service group does not publish any services. To allow traffic to pass to the instances in a service group, you specify the network ports to publish. For example, if you run a web server you would publish port 443 (HTTPS) and/or port 80 (HTTP). You can also redirect port 80 (HTTP) to port 443 (HTTPS).

Connection Handlers

KraftCloud uses connection handlers to decide how to forward connections from the Internet to your application. You configure the handlers for every published service port individually. The following handlers are available:

HandlerDescription
tlsTerminate the TLS connection at the KraftCloud gateway using our wildcard certificate issued for the kraft.cloud domain. The gateway forwards the unencrypted traffic to your application
httpEnable HTTP mode on the load balancer to load balance on the level of individual HTTP requests. In this mode, only HTTP connections are accepted. If this option is not set the load balancer works in TCP mode and balances TCP connections
redirectRedirect traffic from the source port to the destination port

Currently, there is a set of constraints when publishing ports:

  • Port 80: Must have http and must not have tls set
  • Port 443: Must have http and tls set
  • The redirect handler can only be set on port 80 (HTTP) to redirect to port 443 (HTTPS)
  • All other ports must have tls and must not have http set

Load Balancing

Load balancing in KraftCloud is very easy. As soon as you attach more than one instance to a service group, KraftCloud will start balancing traffic between them. Therefore, only instances providing the same services must be part of the same group.

You can remove instances from a service group at any time. KraftCloud will immediately take the instance out of the load balancing group.

If you want to make sure that no existing connections are dropped when stopping an instance, use the draining feature of the PUT /v1/instances/stop endpoint.

Persistence

When a service group is implicitly created as part of a new instance (see POST /v1/instances) it exists only as long as its owning instance exists.

In contrast, service groups that you explicitly create using the POST /v1/services endpoint are persistent and are not automatically deleted when the last instance leaves the group. You need to delete them with the DELETE /v1/services endpoint.

When you attach a second instance to an implicitly created service group, KraftCloud re-configures the service group to be persistent from that point on.

API Endpoints

The KraftCloud Services REST API provides the following endpoints:

MethodEndpointPurpose and Description
POST/v1/servicesCreates one or more service groups
GET/v1/servicesReturns the current state and configuration of service groups
DELETE/v1/servicesDeletes the specified service groups
GET/v1/services/listLists all existing service groups

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 introduciton for more information on how to connect to the API.

Creating a New Service Group

Creates a new service group with the given configuration. Note that the service group properties like published ports can only be defined during creation. They cannot be changed later.

Each port in a service group can specify a list of handlers that determine how traffic arriving at the port is handled. See Connection Handlers for a complete overview.

Request

Endpoints:
POST /v1/services

ParameterTypeDefaultRequiredDescription
name1Nameauto-generatedName of the service group
dns_name2stringsame as namePublicly accessible DNS name of the service group
servicesarray of objects✔️Description of exposed network services
    portint✔️Public-facing port
    destination_portintSame as portPort that the application listens on
    handlersarray of stringsSee Connection Handlers

1If no name is specified a random name of the form <word>-<word>-<random> is auto-generated, where <random> is an 8 characters long random alphanumeric suffix.
2The services published by the service group will be accessible under the given domain name. If dns_name is a fully-qualified domain name, that is it ends with a dot (.), the domain name is taken as-is. Otherwise, the metro’s domain name is appended (e.g., my-project expands to my-project.fra0.kraft.host). If the given domain name is already in use by the current or a different user the operation fails. In addition, certain domain names cannot be used (e.g., www). Note that, specifying FQDNs like www.example.com. is experimental and currently supported for unencrypted HTTP traffic only. All other services will experience SSL certificate issues. If name is specified without also providing dns_name, the DNS name is derived from name by appending an 8 characters long random alphanumeric suffix and the metro’s domain name. For example, setting the name to my-project without also providing dns_name results in a DNS name of my-project-<random>.fra0.kraft.host.

Example of creating a service group that publishes HTTP port 8080 at HTTPS port 443
curl -X POST \
-H "Authorization: Bearer ${KRAFTCLOUD_TOKEN}" \
-H "Content-Type: application/json" \
"https://api.fra0.kraft.cloud/v1/services" \
-d '{
"services": [
{
"port": 443,
"destination_port": 8080,
"handlers": [
"tls",
"http"
]
}
]
}'

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 newly created group
nameNameName of the newly created group
fqdnstringPublicly accessible fully-qualified domain name of the service group
Status 200 OK
{
"status": "success",
"data": {
"service_groups": [
{
"status": "success",
"uuid": "3b5b4c36-2c9b-46e4-80c6-7e5b561938c2",
"name": "young-monkey-uq6dxq0u",
"fqdn": "young-monkey-uq6dxq0u.fra0.kraft.host"
}
]
}
}

Getting the Status of a Service Group

Returns the current status and the configuration of a service group.

Request

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

ParameterTypeDefaultRequiredDescription
uuid | name1UUID | Name✔️UUID or name of the service group 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 group
curl -X GET \
-H "Authorization: Bearer ${KRAFTCLOUD_TOKEN}" \
"https://api.fra0.kraft.cloud/v1/services/3b5b4c36-2c9b-46e4-80c6-7e5b561938c2"

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 group
nameNameName of the group
created_atstringDate and time of creation in ISO8601
fqdnstringPublic fully-qualified domain name under which the group is accessible from the Internet
instancesarray of UUIDsUUIDs of the instances attached to this group
servicesarray of objectsDescription of published network services
    portintPublic-facing port
    destination_portintApplication port to which inbound traffic is redirected
    handlersarray of stringsSee Connection Handlers
persistentboolIndicates if the group will stay alive even after the last instance detached
autoscaleboolIndicates if the group has autoscale enabled
Status 200 OK
{
"status": "success",
"data": {
"service_groups": [
{
"status": "success",
"uuid": "3b5b4c36-2c9b-46e4-80c6-7e5b561938c2",
"name": "young-monkey-uq6dxq0u",
"created_at": "2023-08-21T16:38:15Z",
"fqdn": "young-monkey-uq6dxq0u.fra0.kraft.host",
"instances": [
"77d0316a-fbbe-488d-8618-5bf7a612477a"
],
"services": [
{
"port": 443,
"destination_port": 8080,
"handlers": [
"tls",
"http"
]
}
],
"persistent": false,
"autoscale": false
}
]
}
}

Deleting a Service Group

Deletes the specified service group. Fails if there are still instances attached to the group. After this call the IDs associated with the service group are no longer valid and the domain name is released.

Request

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

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

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

Example of deleting a specific service group
curl -X DELETE \
-H "Authorization: Bearer ${KRAFTCLOUD_TOKEN}" \
"https://api.fra0.kraft.cloud/v1/services/3b5b4c36-2c9b-46e4-80c6-7e5b561938c2"

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 group
nameNameName of the group
Status 200 OK
{
"status": "success",
"data": {
"service_groups": [
{
"status": "success",
"uuid": "3b5b4c36-2c9b-46e4-80c6-7e5b561938c2",
"name": "young-monkey-uq6dxq0u"
}
]
}
}

List Existing Service Groups

Lists all existing service groups. You can filter by persistence and domain name. The latter can be used to lookup the UUID of the service group that owns a certain domain name. The returned groups fulfill all provided filter criteria. No particular value is assumed if a filter is not part of the request.

Request

Endpoints:
GET /v1/services/list

ParameterTypeDefaultRequiredDescription
persistentboolDesired persistence value for filtering
fqdnstringFully-qualified domain name of the group to look up
Example of listing all existing service groups
curl -X GET \
-H "Authorization: Bearer ${KRAFTCLOUD_TOKEN}" \
"https://api.fra0.kraft.cloud/v1/services/list"
Example of looking up the service group for a DNS name
curl -X GET \
-H "Authorization: Bearer ${KRAFTCLOUD_TOKEN}" \
-H "Content-Type: application/json" \
"https://api.fra0.kraft.cloud/v1/services/list" \
-d '{
"fqdn": "young-monkey-uq6dxq0u.fra0.kraft.host"
}'

Response

The response is embedded in a JSON object as described in API Responses.

FieldTypeDescription
uuidUUIDUUID of the group
nameNameName of the group
Status 200 OK
{
"status": "success",
"data": {
"service_groups": [
{
"uuid": "3b5b4c36-2c9b-46e4-80c6-7e5b561938c2",
"name": "young-monkey-uq6dxq0u"
},
{
"uuid": "d3a7fe17-0a44-4862-836f-d5f9a6a0b2f8",
"name": "patient-butterfly-9br0p9e5"
}
]
}
}