Domains

When attaching a service to an instance, Unikraft Cloud exposes the instance on a subdomain of unikraft.app by default. You can also use your own custom domain instead.

Configuring your external DNS provider

Before Unikraft Cloud can launch an app, you need to ensure that you have configured things correctly with your DNS provider:

• For a subdomain you own such as docs.mydomain.com, a CNAME is enough. In this case, you can just add a CNAME record with your sub-domain (docs) as the host and point the record to Unikraft Cloud's metro (for example, fra.unikraft.app).

• For an apex domain (for example, mydomain.com), add one of: ALIAS¹, ANAME¹, or a flattened CNAME record. Depending on your provider, leave the host field empty or enter @. Point the record to the metro (for example, fra.unikraft.app). If the provider doesn't support these record types, add an A record pointing to the metro IP address.

Code
unikraft metros list

Launching your app

Assume the goal is to use NGINX as an app:

git clone https://github.com/unikraft-cloud/examples
cd examples/nginx

Log into Unikraft Cloud and select a metro close to you. This guide uses fra (Frankfurt, DE):

Code
unikraft login

With this in place, use the CLI to create an instance of the web server and link it to a custom name. Unikraft Cloud does this through the domain flag:

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

The resulting output of the deploy command should be like:

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
  domains:
  - fqdn:        mydomain.com
    certificate:
      name:      mydomain.com-savtl
      uuid:      51efebaf-4858-450c-8ba5-8bd1df96c20b
networks:
- uuid:          62d9bbf0-aec8-61f6-7bdb-86edf63dd068
  private-ip:    10.0.3.3
  mac:           12:b0:c6:23:ed:15
timestamps:
  created:       just now

When you issue the domain flag, Unikraft Cloud requests a new certificate from the public certificate authority. To check the validation status of the certificate, use the CLI:

Code
unikraft certificates list

You should see it first in pending:

Code
METRO  NAME                COMMON-NAME   STATE    CREATED   NOT-AFTER
fra    mydomain.com-savtl  mydomain.com  pending  just now  never

After their state changes to valid, check the deployment with curl:

Code
curl https://mydomain.com

<!DOCTYPE html>
<html>
<head>
<title>Welcome to nginx!</title>
[...]

Learn more

• The CLI reference.
• Unikraft Cloud's REST API reference, in particular the sections on instances, service groups and certificates.
• The certificates documentation for more information on how to use custom certificates with your services.