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:
Handler | Description |
---|---|
tls | Terminate 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 |
http | Enable 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 |
redirect | Redirect 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 havetls
set - Port 443: Must have
http
andtls
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 havehttp
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:
Method | Endpoint | Purpose and Description |
---|---|---|
POST | /v1/services | Creates one or more service groups |
GET | /v1/services | Returns the current state and configuration of service groups |
DELETE | /v1/services | Deletes the specified service groups |
GET | /v1/services/list | Lists all existing service groups |
In the following, the API endpoints are specified relative to this base URL:
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
Parameter | Type | Default | Required | Description |
---|---|---|---|---|
name 1 | Name | auto-generated | Name of the service group | |
services | array of objects | ✔️ | Description of exposed network services | |
port | int | ✔️ | Public-facing port | |
destination_port | int | Same as port | Port that the application listens on | |
handlers | array of strings | See Connection Handlers | ||
domains 2 | array of objects | auto-generated | Description of domains to associate with the service group | |
name 3 | string | ✔️ | Publicly accessible domain name | |
certificate 4 | object | auto-generated | TLS certificate to use for the domain | |
uuid | name 5 | UUID | Name | ✔️ | UUID or name of the certificate |
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.
2If name
is specified without also providing a domain, a domain 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 a domain results in an auto-generated domain of my-project-<random>.fra0.kraft.host
.
3The services published by the service group will be accessible under the given domain names.
If 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.fra0.kraft.host
).
4Only allowed for FQDNs, not for subdomains.
Subdomains like my-project
inherit the wildcard *.<metro>.kraft.host
certificate.
If you specify an FQDN like www.example.com.
, KraftCloud will automatically pick the certificate with the matching CN or trigger a certificate request (see here).
5You need to specify either uuid
or name
.
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 newly created group |
name | Name | Name of the newly created group |
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 |
certificate 1 | 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 |
1 Not for subdomains of <metro>.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>
Parameter | Type | Default | Required | Description |
---|---|---|---|---|
uuid | name 1 | UUID | 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
.
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 group |
name | Name | Name of the group |
created_at | string | Date and time of creation in ISO8601 |
persistent | bool | Indicates if the group will stay alive even after the last instance detached |
autoscale | bool | Indicates if the group has autoscale enabled |
services | array of objects | Description of published network services |
port | int | Public-facing port |
destination_port | int | Application port to which inbound traffic is redirected |
handlers | array of strings | See Connection Handlers |
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 |
certificate | object | TLS certificate used for the domain (not for subdomains of <metro>.kraft.host ) |
uuid | UUID | UUID of the certificate |
name | Name | Name of the certificate |
state | State | State of the certificate |
instances | array of objects | Instances attached to this group |
uuid | UUID | UUID of the instance |
name | Name | Name of the instance |
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>
Parameter | Type | Default | Required | Description |
---|---|---|---|---|
uuid | name 1 | UUID | Name | ✔️ | UUID or name of the group to delete |
1 Not allowed in local scope.
You need to specify either uuid
or name
.
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 group |
name | Name | Name of the group |
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
Parameter | Type | Default | Required | Description |
---|---|---|---|---|
persistent | bool | Desired persistence value for filtering | ||
fqdn | string | Fully-qualified domain name of the group to look up |
Response
The response is embedded in a JSON object as described in API Responses.
Field | Type | Description |
---|---|---|
uuid | UUID | UUID of the group |
name | Name | Name of the group |