The moment your product lets customers use their own domain, you have taken on an operational problem most delivery documentation glosses over: certificates you do not control, DNS you cannot see, and a routing layer that must resolve a hostname you have never heard of to the right tenant, in single-digit milliseconds, every time. Here is how to build it so it still works at the five-hundredth customer.
Three ways a customer can point a domain at you
Every custom-hostname design is a choice about how much of the customer’s DNS you get to control, and the choice determines everything downstream. The lightest option is a CNAME on a subdomain: the customer aliases app.theircompany.com to a hostname you own, and you serve it. It is trivial to onboard, it works on every DNS provider, and it fails on apex domains, because a name holding a CNAME cannot hold anything else and an apex must hold at least nameserver and mail-related data.
The second option solves the apex by asking for address records instead, which means publishing stable anycast addresses your customers point at directly. That works, but it welds you to those addresses: every future renumbering becomes a coordinated migration across every customer’s DNS, and some of those customers will not answer your emails. Prefer alias-style flattened records where the customer’s DNS provider supports them, and treat hard-coded addresses as a liability you are accepting deliberately.
The third option is full or partial delegation: the customer delegates a subdomain to your nameservers, or delegates validation records once so you can act on their behalf afterwards. Delegation is more to ask for and much better to operate, because every subsequent change — new validation, new address, new steering behaviour — happens on your side without another customer ticket. If you expect to run this for years, ask for delegation of a validation subdomain at minimum. It converts a recurring interruption into a one-time setup step.
Certificates: issuance, validation, renewal
Certificates are where custom-hostname projects actually fail, and they fail on renewal rather than issuance. Automated issuance needs proof of control, which arrives one of two ways: an HTTP challenge served on a path under the hostname, or a DNS challenge answered with a record in the customer’s zone. The HTTP route is easier to bootstrap and breaks the moment a customer puts something else in front of you. The DNS route is more robust and requires either the customer to add a record or, far better, a one-time delegation of the validation subdomain so future renewals need nothing from them at all.
Renewal is the part that scales badly, and the shortening certificate lifetime schedule makes it worse every year — each step down multiplies the number of renewals per hostname per year, and multiplies any manual step by your customer count along with it. Assume you will be renewing continuously and design so that a renewal requires zero human action on either side. Alert on failures well before expiry, not on expiry: a certificate that fails validation four days out is a ticket, one that fails four hours out is an outage. The wider consequences of that schedule are laid out in the 2027 certificate step.
Two operational details save real incidents. First, watch for certificate authority rate limits — bulk onboarding can exhaust an issuance allowance and stall every pending hostname behind it, so stagger imports. Second, decide early whether customers may bring their own certificate. Some regulated ones will insist; supporting it means accepting a manual expiry you do not control, so make the customer’s renewal obligation explicit in writing and monitor those certificates yourself anyway.
Routing a hostname to the right tenant
Once the connection terminates, you have a hostname and a job: map it to a tenant, cheaply, and refuse if it maps to nothing. Do the lookup at the edge rather than the origin. A tenant map held in edge storage and read by an edge function resolves in a fraction of a millisecond and never leaves the region; the same lookup at the origin adds a full round trip to every request and turns your tenant directory into a single point of failure for every customer domain simultaneously.
Design the cache key with the hostname in it, always, and audit that assumption periodically. The characteristic multi-tenant incident is one customer’s content served under another customer’s domain, and it is nearly always caused by a cache key that omitted the host on some path, or by a normalisation rule that collapsed two hostnames into one. Treat host-in-key as an invariant and write a test that proves it for every route, not just the ones you remember.
Keep the mapping authoritative in one place and push it outward. Your control plane owns the tenant record; the edge holds a replica optimised for reads; the origin trusts a signed header rather than re-deriving the tenant itself. That way an unmapped hostname is refused at the edge before it costs you anything, and a compromised or spoofed host header does not become a tenant-boundary problem — which is exactly why the origin should also verify that requests arrived through your edge, using mutual TLS rather than trusting addresses.
Failure modes that only appear at scale
At ten hostnames, everything works. The interesting failures start around a few hundred, and they are mostly about the long tail of other people’s infrastructure. Customers put their own proxy in front of yours, producing a loop or a double-cached response nobody expected. Customers point a hostname at you and then delete it from their zone without telling you, leaving a certificate renewing forever for a domain that no longer resolves. Customers add a CAA record that forbids the authority you issue from, and your renewal quietly stops working for that hostname alone.
Stale delegation is the slowest-burning of these. A hostname that once pointed at you and now points somewhere else, or nowhere, keeps consuming issuance attempts and monitoring noise indefinitely. Reconcile continuously: resolve every configured hostname on a schedule, compare what it points at against what you expect, and flag drift. The same job catches the customer who migrated DNS providers and lost half their records in the process.
Then there is the noisy-neighbour dimension. Custom domains mean one customer’s traffic spike, one customer’s bot problem and one customer’s attack all arrive on infrastructure shared with everyone else. Per-hostname rate limiting is not optional at this stage, and neither is per-hostname observability — if your dashboards aggregate all custom domains into one line, you will spend the first hour of every incident working out whose domain it is.
Onboarding, offboarding and the limits nobody reads
Make onboarding self-service and verifiable. Show the customer exactly which record to create, check it yourself with a live resolution rather than trusting a checkbox, and report a specific failure — wrong target, record not yet propagated, conflicting record present — instead of a generic error. Most support load in this feature comes from customers who did the right thing at the wrong DNS provider, and a precise diagnostic removes most of that.
Offboarding matters more than teams expect. When a customer leaves, their hostname must stop resolving to your tenant, their certificate must stop renewing, and their configuration must actually be deleted rather than disabled — an abandoned hostname pointing at infrastructure you still serve is a subdomain-takeover risk with the customer’s brand on it. Build the teardown at the same time as the setup, not later.
Finally, read the limits before you sell the feature. Every platform has a ceiling somewhere: hostnames per zone or per account, certificates per issuance window, entries in an edge map, characters in a routing expression. Those ceilings are rarely on the pricing page and are frequently the reason a custom-domain feature stalls at a specific customer count. Ask your provider for the numbers in writing during evaluation — it belongs in the same list as everything else in writing CDN requirements — and confirm what happens at the ceiling: a hard stop, a soft throttle, or a quiet queue.