CUSTOM DOMAIN
Migrating customer domains off a hand-rolled DNS setup does not require downtime. It requires a parallel-run window, a domain-by-domain cutover, and verification before every switch. The shape of it: stand up the new connection layer next to the old one, move domains over in small batches behind a verification gate, watch each batch for a few days, then decommission what's left.
That's the whole idea. The rest of this guide is the mechanics — what the parallel run actually looks like, how to sequence a 30-day cutover, and what to check before you delete anything.
What Does a Hand-Rolled DNS Setup Actually Cost a Platform Team?
If your team built domain connection in-house two or three years ago, the symptoms are probably familiar enough that you stopped logging them as incidents:
- Support tickets with registrar screenshots. A customer pastes a picture of GoDaddy, or Namecheap, or Cloudflare, or a registrar nobody on the team has heard of, and asks where to paste the CNAME. Someone has to know that UI well enough to walk them through it.
- Cert-renewal pager duty. Somewhere there's a cron job or a Lambda that renews TLS certificates for customer domains, and somewhere there's a person who gets paged when it silently stops working for one customer's edge case.
- The DNS edge-case file nobody owns. Every hand-rolled system accumulates a document — a wiki page, a pinned Slack thread — of exceptions: the registrar that doesn't support CNAME flattening, the customer whose DNS host requires a trailing dot, the one where the MX priority logic breaks mail silently. Nobody wrote it as a spec. Everyone treats it as one.
- Onboarding drop-off at the DNS step. Your activation funnel has a step where a non-technical customer is asked to log into a registrar and add a record. That's the step where a percentage of signups quietly stop.
None of this is a documentation problem. Better instructions don't fix an architecture where two systems — your platform and the customer's DNS provider — can only talk to each other through the customer copying values by hand. That's the bug. A migration replaces the architecture. It doesn't add a better help article to the existing one.
What Does a Zero-Downtime Migration Architecture Look Like?
The migration itself follows four rules, all mechanical, none of them clever:
Run old and new in parallel. Nothing gets cut over on day one. The new connection layer goes live alongside the existing hand-rolled system, taking new domains and connecting them, while every existing customer domain keeps resolving exactly as it does today. Parallel running is what makes the whole migration reversible at every step — there's no big-bang moment where the old system goes off and the new one has to be right the first time.
Cut over domain by domain, not platform-wide. Each customer domain moves independently: verify it resolves and serves correctly on the new layer, then and only then repoint it. A platform-wide cutover turns one bad edge case into an incident. A domain-by-domain one turns it into a single support ticket.
Verify before you switch. Before a domain is considered migrated, the new layer confirms ownership and correct resolution — the same verification gate a fresh connection gets. This is where most migrations that fail actually fail: not at cutover, but because nobody checked the new record actually resolved before the old one got deleted.
Keep rollback live until you're sure. The old configuration stays in place, untouched, until the new one has proven itself in production — typically a few days of clean serving and passing drift checks. If something's wrong, you point back at the old system. You don't debug in production with no fallback.
Underneath those four rules sit the same architectural commitments the platform runs on for any domain, migrated or new: the edge fails closed, so no unapproved hostname is ever served, even mid-migration. Verification tokens are used once and never stored — a migrated domain gets a fresh verification, not a copy of old credentials. The control plane stays out of the request path, so a control-plane migration never touches request-serving latency. And once a domain is live, hourly drift checks catch anything that moves outside expected state — including a customer who edits their DNS mid-migration — and alert before it becomes an incident.
In one sentence: a custom-domain migration runs the old and new connection layers in parallel, cuts over one domain at a time behind a verification gate, and keeps rollback available until the new configuration has proven itself in production.
Under the hood, connecting a domain on the new layer is one call — POST /v1/connections — with the DNS provider auto-detected and records written automatically. Custom Domain extends the Domain Connect protocol, which covers roughly 20 DNS providers natively. Custom Domain auto-configures 25+, including providers outside standard Domain Connect coverage. A typical connection goes live in about 30 seconds once the record is in place. The layer you're migrating onto runs under SOC 2, ISO 27001, and GDPR compliance — worth confirming against whatever compliance posture your hand-rolled system was never formally audited against.
What Does a 30-Day Migration Plan Look Like?
Four phases, each with a clear exit condition before the next one starts.
| Phase | Days | What happens | Exit condition |
|---|---|---|---|
| Audit | 1–5 | Inventory every customer domain, its DNS provider, cert status, and any known edge cases from the exceptions file. Stand up the new connection layer in parallel — no customer domains touched yet. | Full domain inventory reconciled against production traffic; new layer passing internal verification tests. |
| Pilot batch | 6–12 | Migrate a small batch (internal domains, then a handful of low-risk customer domains) through the full flow: connect, verify, cut over, watch. | Pilot batch serving cleanly for 72 hours with no verification failures or cert gaps. |
| Bulk cutover | 13–24 | Migrate remaining domains in scheduled batches, ordered by risk (simplest DNS setups first, known edge cases last). Each batch gets its own verify-then-switch gate and a hold period before the next batch starts. | All customer domains migrated and passing hourly drift checks; rollback still available for each batch's hold window. |
| Decommission | 25–30 | Retire the old DNS automation, cert-renewal jobs, and support runbooks once every batch has cleared its hold period with no rollbacks. Archive the edge-case file — it's now the new system's test suite. | Old system fully decommissioned; on-call rotation updated to drop the legacy pager duty. |
Thirty days is a template, not a mandate — a domain book with more edge cases stretches the bulk-cutover phase. A smaller one compresses it. The sequencing (audit → pilot → bulk → decommission) doesn't change with scale.
When Should You Talk to a Migration Team Instead of Running This Solo?
Everything above works for a self-serve migration of a handful of domains. It gets more involved once you're managing client or customer domains at real scale — multi-tenant SSL across dozens of certificate authorities' worth of edge cases, a domain automation API your other systems depend on, or a client-domain book an agency owns on behalf of its own customers. That's a different conversation than "connect one domain": it's about the API contract, the webhook events your systems will consume, and the migration sequencing for a large book without a maintenance window.
Connecting more than a handful of domains? Talk to us.
Frequently Asked Questions
Does migrating custom domains cause downtime?
No, if the migration runs old and new in parallel and cuts over domain by domain. Each domain keeps resolving on the existing configuration until its replacement is verified and proven, so there's no window where a domain is unreachable.
What happens to SSL/TLS certificates during cutover?
The new layer issues its own certificate for a domain as part of verification, before cutover — not after. Because the edge fails closed, no hostname is ever served without an approved, valid certificate, so there's no gap between the old cert expiring and the new one being ready.
What happens to in-flight domain verifications from the old system?
They're superseded, not reused. A migrated domain gets a fresh verification on the new layer — verification tokens are used once and never stored, so an in-flight or stale verification from the old system simply doesn't carry over. It has no bearing on the new one.
How long does a full migration take for a large domain book?
The four-phase sequence (audit, pilot, bulk cutover, decommission) typically runs 30 days for a mid-sized book. Larger or more edge-case-heavy books extend the bulk-cutover phase, since batches are gated on a hold period rather than run all at once.
Can we roll back a domain after cutover?
Yes, during the hold window. The old configuration stays intact and untouched until a batch has proven itself — typically a few days of clean serving and passing drift checks — so rollback is a repoint, not a rebuild.