Copy page

Cloud Platform

Services

On creation, Unikraft Cloud assigns each instance a private IP address and private FQDN for internal connectivity, of the form <instance-name>.internal. To connect to an instance from the Internet, you need to create a service and attach the instance to it.

A service defines how to reach a group of instances from the outside world. It maps an external FQDN port to an internal port common to all instances within the service. The platform load balances incoming connections across instances.

Instance service groups

If you specify a port mapping in the CLI deployment commands, the platform creates a service for you and attaches the instance to it:

This ties the service to the lifetime of the instance, so the platform deletes it when you delete the instance.

Persistent service groups

The rest of this guide shows how to create a service first, then use the CLI to create and attach instances to it.

First, create a new service with the CLI:

This creates a new service named my-service listening on port 443. Unikraft Cloud terminates TLS and sends HTTP traffic to the app's port 8080. This example assumes that the app opens port 8080.

Now use the CLI with the service flag to attach the instance to the my-service service. For example, from the Go HTTP server guide:

This creates a new Go web server instance and immediately attaches it to the my-service service. The output shows the instance address and other details:

In this case, the instance name is httpserver-go121-9a2wv. The address is https://my-service-f4744h0c.fra.unikraft.app.

Use curl to query the Go HTTP server:

Code
curl https://my-service-f4744h0c.fra.unikraft.app

Hello, world!

That's it.

In the end, if you want to remove a service, use:

Handlers

Handlers define how the service will handle incoming connections and forward traffic from the Internet to your app. For example, you can configure a service to end TLS connections, redirect HTTP traffic, or enable HTTP mode for load balancing. You configure the handlers for every published service port individually.

Currently, there are 3 supported handlers:

For example, the following creates the service my-service with three published ports:

• Port 443 with both http and tls handlers (HTTP mode).
• Port 80 with the http and redirect handlers (HTTP mode).
• Port 10000 with only the tls handler (TCP mode).

UDP services

You can use UDP for both internal VM-to-VM traffic and external traffic. To create a UDP service, use POST /services and set both protocol and ip:

POST /services
{
  "services": [
    {
      "port": 7777,
      "destination_port": 8080,
      "protocol": "udp",
      "ip": "a.b.c.d"
    }
  ]
}

The IP address must be one of the IP addresses allocated to your user.

Connection limits

Every service group has a soft and a hard connection limit that the load balancer enforces.

Field	Default	Range	Description
soft_limit	1	1-65535	The load balancer starts queuing new connections once the number of active connections reaches this value.
hard_limit	65535	1-65535	The load balancer rejects new connections once the number of active connections reaches this value.

soft_limit must be less than or equal to hard_limit. Setting soft_limit > hard_limit returns a 400 error.

You can use the CLI to set the connection limits for a service:

• The CLI reference and the legacy CLI reference.
• Unikraft Cloud's REST API reference, in particular the section on service groups.