Custom Domains

Kupe Cloud supports custom domains on the same HTTPRoute model used for platform domains.

You add your hostname to the route, then create two DNS CNAME records from the values shown in the console. Kupe handles certificate issuance and HTTPS listener management for that hostname.

Step 1: Create or update the HTTPRoute

Create the route with your custom hostname and attach it to external-gateway:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: my-app
  namespace: my-app
spec:
  parentRefs:
    - name: external-gateway
      namespace: kube-system
  hostnames:
    - app.acme.com
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: my-app
          port: 80

You can mix platform and custom hostnames on the same route if you want:

hostnames:
  - app.acme.com
  - app.<tenant>.kupe.cloud

Step 2: Open the Custom Domains page in the console

After the route exists, open Custom Domains in the console and select Manage for the route. The console reads the controller status directly from the route and shows the exact records you need to create.

Do not construct the ACME challenge target manually. Copy it from the console.

Step 3: Create the two CNAME records

For each custom hostname, create:

Traffic CNAME

This routes public traffic to the platform’s stable external gateway hostname:

app.acme.com CNAME ext.kupe.cloud

ACME challenge CNAME

This delegates certificate validation to a Kupe-managed zone:

_acme-challenge.app.acme.com CNAME _acme-challenge.app--acme--com.custom.kupe.cloud

The second target is derived from your hostname, so always copy the exact value from the console.

Step 4: Wait for verification and certificate issuance

Once the records resolve correctly, Kupe automatically:

1. verifies the traffic CNAME
2. verifies the ACME challenge CNAME
3. issues a certificate for the hostname
4. adds the HTTPS listener on the shared gateway

This usually completes within a few minutes after DNS propagation.

What you will see in the console

The Custom Domains page shows a simple status for each route:

Status	Meaning
Action Required	The route exists, but the required DNS records are not in place yet
Pending	DNS records are being verified or the certificate is still being issued
Active	The certificate is ready and traffic is live on HTTPS

The Manage dialog also shows progress through:

• Configure DNS
• Verify ACME
• Issue Certificate

Notes

• Each custom hostname needs its own ACME challenge CNAME
• Platform hostnames under *.kupe.cloud do not need this flow
• Apex domains such as acme.com need DNS provider support for ALIAS, ANAME, or CNAME flattening
• One route can carry multiple custom hostnames if needed

Removing a custom domain

To remove a custom domain:

1. remove the hostname from the HTTPRoute, or delete the route
2. let Kupe clean up the certificate and gateway listener
3. optionally remove the DNS records from your DNS provider

You do not need to revoke certificates or patch the gateway manually.

Related pages

• HTTP Routes
• TLS and Certificates