Skip to content
Ownkube

Custom domains

Every public web app gets a hostname under ownkube.app with a certificate Ownkube manages. On an own-cloud Starter cluster you can also serve the same app from a hostname you own, such as app.acme.io or the bare acme.io, with HTTPS handled for you. You register the parent domain once per cluster, then link as many hosts under it as you need.

How it works

Section titled “How it works”

A custom domain has two parts, and the dashboard walks you through both.

  1. Certificate verification, once per parent domain. You add a single CNAME at your DNS provider that delegates the _acme-challenge name to Ownkube. That proves you own the domain, and Ownkube issues one certificate covering acme.io and *.acme.io. It renews on its own.
  2. Traffic routing, once per host. You link a host to an app on the deployment’s Settings tab, add the routing record the dashboard shows you, and the host comes online as soon as DNS resolves.

Certificates come from Let’s Encrypt through the DNS-01 challenge, which is why the apex domain works too: no ALIAS record tricks and no proxy in front.

Before you start

Section titled “Before you start”
  • A Starter cluster on cluster platform 0.22.0 or newer.
  • A public web app on that cluster. See Public hostnames.
  • Access to the DNS zone for the domain you want to use (Cloudflare, Route 53, Namecheap, or any provider that can create CNAME and A records).

Register the parent domain

Section titled “Register the parent domain”

  1. Open the cluster’s settings

    Go to your dashboard, open the cluster, and find the Certificate verification card under Settings.

  2. Enter the domain

    Type the parent domain, for example acme.io. Every host under it, and the bare domain itself, will be covered by one certificate. Click Add.

  3. Add the verification record

    The card shows one CNAME to create at your DNS provider:

    TypeNameTarget
    CNAME_acme-challenge.acme.iothe Ownkube-owned name shown in the card

    This record is the only thing Ownkube ever needs in your zone. It does not change where acme.io itself points.

  4. Wait for the certificate

    Once the record resolves, the card reads DNS verified, issuing your certificate, then Active. Issuance usually finishes within a couple of minutes of the DNS change going live. Click Verify to recheck early.

Section titled “Link a host to an app”

  1. Open the app’s Settings tab

    Open the deployment and go to Settings. The Traffic routing card lists linked hosts and the parent domains you have registered.

  2. Enter the hostname

    Type the full host, such as app.acme.io, api.acme.io, or the bare acme.io, and click Link. A host can be linked to one app at a time.

  3. Add the routing record

    The dashboard shows the record for that host:

    HostTypeTarget
    A subdomain such as app.acme.ioCNAMEan Ownkube name for your cluster
    The apex acme.ioAyour cluster’s public IP

    Add it at your DNS provider. The host moves from pending to verifying to active on its own. If the certificate for the parent domain is still being issued, the card says so and the host goes live once it is ready.

  4. Check it

    Open https://app.acme.io. Your app answers over HTTPS with a certificate issued for your domain, and plain http:// redirects to https://.

Your app sees the custom hostname in the Host header, so framework redirects and absolute URLs work without any forwarded-header configuration.

To stop serving a host, click Unlink next to it. The parent domain and its certificate stay registered so you can link the host again later or point it at a different app.

From the CLI or an agent

Section titled “From the CLI or an agent”

The same flow is available in okctl and through the MCP server.

Terminal
# Linked hosts on an app, plus the parent domains available on its cluster
okctl domains list <deployment-id>


# Link a host; prints the routing record and the certificate challenge record
okctl domains add <deployment-id> app.acme.io


# Recheck DNS now instead of waiting for the next pass
okctl domains verify <domain-id>


# Unlink a host
okctl domains delete <domain-id>

Limits

Section titled “Limits”
  • One parent domain registration per domain per cluster. Two apps on the same cluster can share a parent domain with different hosts.
  • A host links to one app at a time. Unlink it first to move it.
  • Public web apps only. Workers, jobs, databases and caches have no public hostname to attach a domain to.
  • Starter clusters only. On Production (EKS) clusters and Ownkube Compute, apps keep their ownkube.app hostname.

Troubleshooting

Section titled “Troubleshooting”
”Couldn’t find the DNS record yet”

The record has not propagated or was created on a different name. Check it from outside your network:

Terminal
dig +short _acme-challenge.acme.io CNAME
dig +short app.acme.io CNAME

Both should return the targets the dashboard shows. On Cloudflare, make sure the _acme-challenge record is DNS only (grey cloud), not proxied.

The host is active but the browser warns about the certificate

The parent domain’s certificate is still being issued. Open the cluster’s Certificate verification card and wait for Active, or click Verify. If it has been more than ten minutes, check that the _acme-challenge CNAME still exists.

I use Cloudflare’s proxy in front of my site

You can keep the orange cloud on the routing record for the host. Set Cloudflare’s SSL mode to Full (strict) so it validates the certificate Ownkube issued. Leave the _acme-challenge record unproxied.

Public hostnames The ownkube.app address every public web app gets, and how to rename it.
Access protection Put a password in front of an app on your own domain.
Clusters Everything on the cluster page, including the certificate verification card.