Domains & SSL

Every Kipper cluster gets automatic HTTPS, both on free kipper.run subdomains and custom domains.

Free kipper.run subdomains

When you run kip install, Kipper registers a free subdomain based on your server's IP address:

203-0-113-10.kipper.run

Apps deployed to the cluster get subdomains automatically:

hello-203-0-113-10.kipper.run
api-203-0-113-10.kipper.run
console-203-0-113-10.kipper.run

All subdomains are single-level (using dashes, not dots) to work with the wildcard TLS certificate.

How it works

A wildcard DNS record (*.kipper.run) points all subdomains to the Kipper Gateway. The gateway looks up the cluster IP from its registry and reverse-proxies the request. TLS is terminated at the gateway using a Let's Encrypt wildcard certificate.

Subdomain expiry

Free subdomains expire after 30 days of inactivity. Running any kip command against the cluster automatically renews the registration. If a subdomain expires, re-running kip install will re-register it.

Custom console domain

Replace the auto-generated console URL with your own domain:

kip cluster domain kipper.example.com

This command handles everything in one step:

• Console Ingress: adds the custom hostname with TLS
• Console API Ingress: adds both api.{domain} and console-api-{domain-dashed}.kipper.run
• Dex: updates the issuer URL, Ingress, and redirect URIs
• Gateway: registers a clean kipper.run subdomain (e.g. kipper-example-com.kipper.run)
• console-api: updates CLUSTER_DOMAIN, CONSOLE_DOMAIN, and DEX_ISSUER

After running this command, all Kipper URLs use the clean subdomain derived from your custom domain instead of the raw server hostname.

See Configuration: Custom console domain for more details.

Custom app domains

Apps can use custom domains instead of kipper.run subdomains. Set a route with a custom host in the web console's Route panel, or via the API.

With a custom domain, traffic goes directly to your server (bypassing the gateway) and cert-manager issues a Let's Encrypt certificate automatically.

TIP

Point your domain's A record to the server's IP before configuring it. cert-manager needs DNS to resolve to issue the TLS certificate.

DNS verification

After saving a route, the console reports one of these states next to the URL:

• Green tick, "resolves to this cluster". The hostname's A record points at one of the cluster's node IPs. Nothing more to do, the certificate will follow.
• Amber warning, "does not resolve". There's no DNS record for the hostname yet. The panel shows the IP your A record needs to point at, with a copy button.
• Red warning, "resolves to X". There is a DNS record but it points elsewhere. The panel shows the current IP and the IP it should point to.
• Green tick, "Free kipper.run subdomain". The route is on *.kipper.run, served by the shared kipper.run gateway. No DNS to set up.
• Green tick, "Covered by your wildcard A record". The route is a subdomain of your cluster's domain (the value you passed to kip install --domain). The wildcard A record you set at install time covers every new app subdomain automatically. A "Verify wildcard anyway" link runs the lookup if you want to sanity-check.

After you change your DNS at the registrar, click the refresh icon to re-check. There's no background polling, so the indicator only updates when you ask it to.

SSL certificates

All SSL certificates are managed automatically:

• kipper.run subdomains: wildcard certificate on the gateway, renewed by Caddy
• Custom domains: per-domain certificate on the cluster, issued and renewed by cert-manager
• No manual certificate management required

Troubleshooting certificates

Browser shows "insecure" or "TRAEFIK DEFAULT CERT"

If you see a certificate warning with TRAEFIK DEFAULT CERT as the common name, it means cert-manager hasn't issued a proper Let's Encrypt certificate yet. The most common cause is an invalid ACME registration email.

Check if this is the problem:

kip cert email

If the email shows something like admin@kipper.local, that's the issue. Let's Encrypt rejects emails on non-public domains.

Fix it:

kip cert email you@yourdomain.com

This updates the email, re-registers with Let's Encrypt, and triggers renewal for any stuck certificates. Give it a minute or two, then reload the page.

TIP

When you install with kip install --domain yourdomain.com, the email defaults to admin@yourdomain.com. If you install without --domain, it falls back to admin@kipper.local which Let's Encrypt will reject. Always set a real email.

Certificates stuck in "Issuing" state

If the email is valid but certificates are still not ready, check the certificate status:

KUBECONFIG=~/.kip/clusters/your-cluster.yaml kubectl get certificates -A

Common causes:

• DNS not pointing to the server yet. cert-manager uses HTTP-01 challenges, so the domain must resolve to your server's IP. Check with dig yourdomain.com.
• Ports 80/443 blocked. Let's Encrypt needs to reach your server on port 80 to verify ownership.
• Rate limiting. Let's Encrypt has rate limits. If you've issued too many certificates for the same domain recently, you'll need to wait. Check the cert-manager logs: kubectl logs -n cert-manager -l app=cert-manager.