Custom Domains - Uncloud

Attach custom domains to your apps with automatic HTTPS certificates.

How It Works

You add a domain to your app via the API or dashboard
Uncloud creates an Ingress rule in Kubernetes
cert-manager provisions a TLS certificate from Let’s Encrypt
Traffic is routed to your app over HTTPS

Prerequisites

cert-manager installed on the cluster
cert_manager_cluster_issuer configured in config.yaml
Port 80 and 443 accessible from the internet

Step 1: Add the Domain

curl -X POST http://localhost:8080/api/v1/apps/app_your_id/domains \
  -H "Content-Type: application/json" \
  -d '{"domain": "api.example.com"}'

Step 2: Configure DNS

Add a DNS record pointing your domain to the cluster: Option A: CNAME Record (recommended)

Type	Name	Value
`CNAME`	`api.example.com`	`your-base-domain.com`

Option B: A Record

Type	Name	Value
`A`	`api.example.com`	`<cluster-load-balancer-ip>`

Step 3: Verify

Once DNS propagates (usually 1-5 minutes), cert-manager automatically provisions a TLS certificate. Your app is now accessible at https://api.example.com.

Default Subdomains

Every app automatically gets a subdomain under the configured base_domain:

<app-slug>.<base_domain>

For example:

App name: my-api → my-api.go4.site
App name: frontend → frontend.go4.site

These subdomains use the wildcard TLS certificate configured in default_tls_secret_name.

Multiple Domains

You can attach multiple domains to a single app:

# Add primary domain
curl -X POST http://localhost:8080/api/v1/apps/app_your_id/domains \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com"}'

# Add www subdomain
curl -X POST http://localhost:8080/api/v1/apps/app_your_id/domains \
  -H "Content-Type: application/json" \
  -d '{"domain": "www.example.com"}'

Remove a Domain

curl -X DELETE http://localhost:8080/api/v1/apps/app_your_id/domains/api.example.com

Configuration

The TLS configuration is defined in config.yaml:

apps:
  base_domain: go4.site
  default_tls_secret_name: wildcard-cert
  cert_manager_cluster_issuer: letsencrypt-prod

Field	Description
`base_domain`	Default domain for app subdomains
`default_tls_secret_name`	Kubernetes Secret with wildcard TLS cert
`cert_manager_cluster_issuer`	cert-manager issuer for custom domains

​How It Works

​Prerequisites

​Step 1: Add the Domain

​Step 2: Configure DNS

​Step 3: Verify

​Default Subdomains

​Multiple Domains

​Remove a Domain

​Configuration