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.

Note

Except for unencrypted HTTP traffic on port 80, KraftCloud accepts only TLS connections from the Internet. It uses Server Name Indication (SNI) to forward inbound traffic to your application.

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 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:

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:

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.

Local Scope

Local API endpoints directed at a specific service group additionally include the UUID of the service group (i.e., GET /v1/services/<UUID>)

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.

Batching

You can specify an array of service group descriptions to create multiple groups with different properties with the same call.

Request

Endpoints:
POST /v1/services

Parameter	Type	Default	Required	Description
name1	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
domains2	array of objects	auto-generated		Description of domains to associate with the service group
name3	string		✔️	Publicly accessible domain name
certificate4	object	auto-generated		TLS certificate to use for the domain
uuid | name5	UUID | Name		✔️	UUID or name of the certificate

¹If 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.
²If 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.
³The 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).
⁴Only 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).
⁵You need to specify either uuid or name.

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"
            ]
          }
        ],
        "domains": [
          {
            "name": "my-project"
          },
          {
            "name": "example.com."
          }
        ]
      }'

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
certificate1	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

¹ Not for subdomains of <metro>.kraft.host.

Status 200 OK

{
  "status": "success",
  "data": {
    "service_groups": [
      {
        "status": "success",
        "uuid": "3b5b4c36-2c9b-46e4-80c6-7e5b561938c2",
        "name": "young-monkey-uq6dxq0u",
        "domains": [
          {
            "fqdn": "my-project.fra0.kraft.host"
          },
          {
            "fqdn": "example.com",
            "certificate": {
              "uuid": "0b8fda39-d326-426e-827e-093e4c173dc8",
              "name": "example.com-x9d9k",
              "state": "valid"
            }
          }
        ]
      }
    ]
  }
}

Quota Exceeded Error

If you experience a Quota exceeded error (EDQUOT), check your user account’s quota usage and limits.

Getting the Status of a Service Group

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

Batching

In global scope, you can specify an array of status requests to retrieve the status of multiple groups with the same call.

Request

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

Parameter	Type	Default	Required	Description
uuid | name1	UUID | Name		✔️	UUID or name of the service group to get the status for

¹ 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.

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

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",
        "persistent": false,
        "autoscale": false,
        "services": [
          {
            "port": 443,
            "destination_port": 8080,
            "handlers": [
              "tls",
              "http"
            ]
          }
        ],
        "domains": [
          {
            "fqdn": "my-project.fra0.kraft.host"
          },
          {
            "fqdn": "example.com",
            "certificate": {
              "uuid": "0b8fda39-d326-426e-827e-093e4c173dc8",
              "name": "example.com-x9d9k",
              "state": "valid"
            }
          }
        ],
        "instances": [
          {
            "uuid": "77d0316a-fbbe-488d-8618-5bf7a612477a",
            "name": "myapp"
          }
        ]
      }
    ]
  }
}

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.

Caution

This operation cannot be undone.

Batching

In global scope, you can specify an array of delete requests to delete multiple groups with the same call.

Request

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

Parameter	Type	Default	Required	Description
uuid | name1	UUID | Name		✔️	UUID or name of the group to delete

¹ 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.

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

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

Parameter	Type	Default	Required	Description
persistent	bool			Desired persistence value for filtering
fqdn	string			Fully-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.

Field	Type	Description
uuid	UUID	UUID of the group
name	Name	Name 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"
      }
    ]
  }
}