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.

Code
await ukc.metro("fra").services.create({
  services: [{ port: 443, handlers: ["tls", "http"], destination_port: 8080 }],
});

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:

Code
unikraft run --metro fra \
  -m 256M \
  -p 443:8080/http+tls \
  --image <my-org>/nginx:latest

Code
metro:        fra
name:         nginx-67zbu
uuid:         8a8bc1b9-0af6-420e-a426-190dc2da9eaa
state:        starting
image:        <my-org>/nginx
resources:
  memory:     256MiB
  vcpus:      1
service:
  uuid:       a942b9b5-ad17-3ffe-dcd2-ef4331f9087a
  name:       nameless-fog-0tvh1uov                     # <---- service name
  domains:
  - fqdn:     nameless-fog-0tvh1uov.fra.unikraft.app    # <---- service domain
networks:
- uuid:       62d9bbf0-aec8-61f6-7bdb-86edf63dd068
  private-ip: 10.0.3.3
  mac:        12:b0:c6:23:ed:15
timestamps:
  created:    just now

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:

Code
unikraft services create --metro fra \
  --name my-service \
  --service 443:8080/http+tls

Code
metro:         fra
name:          my-service
uuid:          9bfe76ea-2679-482a-954e-577de7d122b3
persistent:    true
limits:
  soft:        1
  hard:        65535
timestamps:
  created:     just now
domains:
- fqdn:        my-service-pc4xjplc.fra.unikraft.app
services:
- source:      443
  destination: 8080
  handlers:    ["tls", "http"]

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:

Code
git clone https://github.com/unikraft-cloud/examples
cd examples/httpserver-go1.21/
unikraft build . --output <my-org>/httpserver-go121:latest
unikraft run --metro fra \
  -m 256M \
  --service my-service \
  --image <my-org>/httpserver-go121:latest

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:

Code
metro:        fra
name:         httpserver-go121-9a2wv
uuid:         8bb34040-9434-4a28-bd1e-c24ee532e2da
state:        starting
image:        <my-org>/httpserver-go121
resources:
  memory:     256MiB
  vcpus:      1
service:
  uuid:       9bfe76ea-2679-482a-954e-577de7d122b3
  name:       my-service
  domains:
  - fqdn:     my-service-pc4xjplc.fra.unikraft.app
networks:
- uuid:       51f79dc1-e989-908d-894b-bdf0a87e7901
  private-ip: 10.0.3.3
  mac:        12:b0:57:91:bb:a5
timestamps:
  created:    just now

In this case, the instance name is httpserver-go121-9a2wv. Notice that the service ID is the same from the service created earlier, and so is the FQDN, which is https://my-service-pc4xjplc.fra.unikraft.app.

Use curl to query the Go HTTP server:

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

Hello, world!

That's it.

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

Code
unikraft services delete my-service

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, redirecting to port 443 (HTTP mode).
• Port 10000 with only the tls handler (TCP mode).

Code
unikraft services create --metro fra \
  --name my-service \
  --service 443:8080/tls+http \
  --service 80:443/http+redirect \
  --service 10000:10000/tls

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.

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:

Code
unikraft services create --metro fra \
  --name my-service \
  --service 443:8080/http+tls \
  --soft-limit 5 \
  --hard-limit 10

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