Domains
A service is private by default. It answers inside its environment and nowhere else. A domain is what changes that: it gives the service a public hostname, terminates HTTPS in front of it, and routes traffic to the port it listens on.
There are two kinds of domains. A platform domain is one click and works immediately, and a service has one of them. A custom domain is a hostname you own, which takes two DNS records and a few minutes, and a service can have as many as it needs.
Both need the service to have a port. A service that does not listen on one has nothing to route to.
Platform domains
Open the service, go to Settings → Networking → Platform Domain, and click Generate Domain. You get something like:
vouch-development-ee6tz.lucity.app
The name is built from the service, the environment, and a short random suffix that keeps it unique across the platform. DNS resolution and HTTPS both work pretty much instantly: there are no records to add and no certificate to wait for.
This is the right choice for development environments, for previews, and for anything internal where the URL does not need to be memorable. When you want a hostname of your own, add a custom domain alongside it: the platform domain keeps working, so nothing breaks while you set the other one up.
Custom domains
Under Settings → Networking → Custom Domains, enter the hostname you want and Lucity shows you the DNS records to add at your provider, with the exact values ready to copy.
Every custom domain needs two records: one that proves you control the domain, and one that points traffic at the platform. Which routing record you add depends on whether you are pointing a subdomain or the domain itself.
Subdomain
For api.example.com, www.example.com, or anything else below the domain:
| Type | Host | Value |
|---|---|---|
TXT | _lucity-verify.example.com | A challenge string unique to your workspace and domain |
CNAME | api.example.com | lb.lucity.app |
Apex domain
For example.com itself, with nothing in front of it:
| Type | Host | Value |
|---|---|---|
TXT | _lucity-verify.example.com | A challenge string unique to your workspace and domain |
ALIAS | example.com | lb.lucity.app |
DNS does not allow a CNAME at the root of a zone, so an apex needs your provider's stand-in for one. The name varies: some providers call it ALIAS or ANAME, and others let you enter a CNAME at the root and flatten it for you. They all do the same thing, which is to answer with the addresses of lb.lucity.app.
Not every DNS provider offers this. If yours does not, redirect the apex to a subdomain instead.
Notice that the TXT record is identical in both cases: it goes on the domain, not on the hostname you are adding. One of them covers every hostname under that domain, so the second and third you add need only their own routing record.
Redirects
A custom domain can send visitors to another domain of the same service instead of serving it. Tick Redirect to when you add the domain and pick the target, which has to be attached to the service already. Requests get a permanent redirect to the same path on the target.
The usual case is an apex that redirects to www. A redirecting apex takes a plain A record, which every DNS provider supports:
| Type | Host | Value |
|---|---|---|
TXT | _lucity-verify.example.com | A challenge string unique to your workspace and domain |
A | example.com | The platform's IP address, shown with the record |
A redirecting subdomain takes the same CNAME as one that serves. A redirecting domain still gets its own certificate, so https://example.com redirects without a warning.
A domain that others redirect to cannot be removed until those redirects are gone, and a redirect cannot point at a domain that redirects itself.
Verification and certificates
Lucity picks up a record as soon as your DNS provider is serving it, without waiting for caches elsewhere to expire. The check runs every couple of minutes on its own, and the Check button next to the domain runs it immediately.
Once the TXT record verifies, two things happen. The route goes live, so the hostname reaches your service once its routing record is in place. And a certificate is requested from Let's Encrypt, which usually takes a few seconds and occasionally a minute. HTTPS starts working on that hostname when the certificate is issued, and renews itself from then on.
Troubleshooting
Each domain shows a DNS state and a TLS state, and between them they say what is holding things up.
| State | What it means |
|---|---|
| DNS pending | Neither record has been seen yet. Normal for the first few minutes after you add them. |
| DNS misconfigured | The routing record points at the platform, but the TXT record is missing or does not match. Almost always the TXT record on the wrong name. |
| DNS error | The lookup itself failed, usually a nameserver problem on the domain rather than a wrong record. |
| TLS provisioning | The certificate has been requested and is not issued yet. It is issued once the routing record points at the platform. |
| TLS error | Issuance failed. Check that the domain still resolves to the platform, and that a CAA record is not blocking Let's Encrypt. |
A proxying DNS provider works too. If yours puts its own network in front of your domain, such as Cloudflare with the orange cloud switched on, set its SSL mode to Full or Full (strict).
Removing a domain
The X next to a domain removes it. The route disappears straight away and the hostname stops reaching your service, though whatever you put in DNS stays there until you delete it too.
Removing a custom domain also removes its certificate. Add the same hostname again later and a fresh one is issued, so there is no benefit to leaving a domain attached to a service you are no longer serving from it.
Under the hood
Domains are Gateway API(opens in a new tab) objects. Each custom domain gets its own listener and its own cert-manager(opens in a new tab) certificate in your environment's namespace, with an HTTPRoute pointing at your service. Platform domains attach to a shared listener with a wildcard certificate already in place, which is why they need no issuance step.
That is all standard Kubernetes, so an ejected project keeps its routing and its certificates without Lucity in the picture.
Next steps
- Services for the port a domain routes to
- Environments for keeping production hostnames separate from development ones
- Deployments for what happens to traffic during a release