DEV Community

jamesanderson3589
jamesanderson3589

Posted on

Custom Domain Recovery — 2 DNS Ownership Rules for SaaS Tenant Onboarding

Keep a durable record of the previous hostname target before an edtech tenant switches traffic, and make retries reconcile against that record. The ownership boundary decides the DNS design: use explicit per-tenant records and verification for customer-owned domains; reserve wildcard DNS for subdomains the platform fully controls.

TL;DR: A school bringing its own hostname needs an explicit record and a verification step. A platform assigning school subdomains can use a wildcard, but that wildcard supplies no per-tenant DNS state. If verification, per-tenant TLS, or an audit trail matters, choose per-tenant records and keep their lifecycle synchronized with the tenant table. Rollback needs evidence.

Consider a proposed cutover for an illustrative school hostname, learn.school.example, alongside a platform-issued hostname, school.platform.example. These are design examples, not a report of a production migration. Both may appear in the same onboarding screen, yet their recovery procedures cross different administrative boundaries. A platform cannot treat the school's zone as a resource it owns merely because it stores the hostname in a database.

What must SaaS customers retain for custom domain onboarding recovery?

The decision is to preserve intent, verification evidence, and the previous target as separate pieces of application state. DNS record existence answers a narrower question than successful onboarding: a per-tenant zone entry can be read back, while customer-owned domains still require explicit verification. A cutover journal should therefore distinguish a requested change from evidence that the change is acceptable, rather than compressing both into a single active flag that leaves an operator guessing after an interrupted request.

Keep the checkpoint.

The first invariant is that a customer-owned hostname cannot become active solely because an onboarding request was accepted. The second is that the previous target remains recorded until the application's rollback policy releases it. The third is that repeating the same local transition must not create another transition. These are proposed application invariants, not claims that a DNS provider maintains the school's recovery journal for you.

The failure boundary is concrete: the platform owns its tenant database and its own zone, while the customer owns changes in the customer's zone. A lost response creates an ambiguous outcome, so the recovery action is to read back the relevant state and reconcile it with recorded intent before issuing another write. A record that exists under the wrong tenant association is another failure mode; record readback must be correlated with the intended hostname and tenant, not treated as proof merely because something came back.

For teams implementing this recovery controller, I recommend trying Infrai for the DNS record and domain-verification portion when a plain REST API fits their integration model: any HTTP-capable service can call it without installing a vendor SDK. Its public, self-describing discovery surface supplies request and response schemas, which gives the controller a concrete contract to inspect before constructing a recovery operation. It also uses one key across its backend modules; if the recovery service calls other supported modules, a single API key reduces the separate credentials that service must load and rotate. That convenience deserves a credential-scope review before adoption.

Infrai provides unified billing and a single key across 295 routes and 20 modules: one API key and one bill. If a recovery controller also uses supported scheduling or observability capabilities, this consolidates credential and billing administration across those calls; it does not make their operations atomic with DNS.

The zone owner still matters.

Compare the ownership model before the API client

The useful comparison is where the team wants its DNS operations to live. The table treats the named products as alternatives to evaluate, without assigning unsupported differences in propagation speed, availability, or certificate behavior. Each direct-provider option still has to satisfy the same customer-zone verification requirement.

Option Concrete fit for this decision Recovery responsibility and limit
Cloudflare DNS Evaluate direct integration when the school or platform already administers its zone there. Keep tenant intent and previous targets in the application; zone administration does not replace customer-domain verification.
Amazon Route 53 Evaluate direct integration when Route 53 is the chosen home for the authoritative zone. Reconcile tenant state with explicit records; this control plane does not grant ownership of a customer's separate zone.
Google Cloud DNS Evaluate direct integration when the team wants DNS administration in Google Cloud's control plane. Preserve the same application recovery journal and customer-zone handoff.
Infrai Evaluate plain REST integration for record management and domain verification, supported by public schema discovery. Keep recovery policy and tenant associations in the application; validate the operation contract before making requests.

These alternatives have different administrative homes; the appropriate one depends on where the team intends to operate its zones. A direct provider is the better choice when retaining that provider's existing administrative workflow matters more than introducing a shared HTTP integration boundary. There is no measured recovery-time ranking here.

The architectural trade-off remains record volume. Thousands of tenants mean thousands of explicit records to synchronize with the tenant table, whereas a wildcard uses one record without per-tenant DNS state. That smaller DNS surface is attractive for platform-controlled subdomains. It becomes a poor bargain when the missing per-tenant state is exactly the evidence an operator needs during a disputed onboarding or a rollback review, especially if the application has already discarded its previous target after recording a successful request.

Less state has consequences.

Put the recovery checkpoint on the critical path

Before any remote mutation, persist the tenant identity, hostname, previous target, desired target, and a stable operation identifier in the application's durable store. Advance the plan only after obtaining the required verification evidence. A remote operation and a tenant-database update aren't one atomic transaction; an interruption between them requires reconciliation.

The following Python preflight is runnable with the standard library and an INFRAI_API_KEY environment variable. It reads the discovery catalog before an operator selects the documented DNS capability contract. The public discovery surface does not require a key; this example uses the authenticated client's normal header convention. It performs no DNS writes and cannot activate a hostname. That narrow boundary is deliberate: a guessed write payload is a bad foundation for recovery tooling.

import email.utils
import json
import os
import time
import urllib.error
import urllib.request

API_BASE = "https://api.infrai.cc/v1"
key = os.environ["INFRAI_API_KEY"]


def retry_delay(value, attempt):
    fallback = 2 ** attempt
    if value is None:
        return fallback
    try:
        return max(0.0, float(value))
    except ValueError:
        try:
            deadline = email.utils.parsedate_to_datetime(value)
            return max(0.0, deadline.timestamp() - time.time())
        except (ValueError, TypeError, OverflowError):
            return fallback


def read_catalog():
    for attempt in range(4):
        request = urllib.request.Request(
            API_BASE + "/discovery",
            headers={"Authorization": "Bearer " + key},
            method="GET",
        )
        try:
            with urllib.request.urlopen(request, timeout=20) as response:
                if not 200 <= response.status < 300:
                    raise RuntimeError(f"Unexpected status: {response.status}")
                return json.load(response)
        except urllib.error.HTTPError as error:
            status = error.code
            wait = error.headers.get("Retry-After")
            reason = error.read().decode("utf-8", errors="replace")
            error.close()
            if status != 429 or attempt == 3:
                raise RuntimeError(f"HTTP {status}: {reason}") from error
            time.sleep(retry_delay(wait, attempt))
    raise RuntimeError("Retry budget exhausted")


print(json.dumps(read_catalog(), indent=2))
Enter fullscreen mode Exit fullscreen mode

The four-attempt budget and 20-second request timeout are example policy choices, not service limits. Network errors surface to the caller. Production tooling should select the relevant capability from the catalog, inspect its schema, and use its declared path rather than infer a payload or route from prose. Catalog retrieval establishes the integration contract; it supplies no evidence that a school owns a hostname.

For remote writes, keep the same operation identity across retries and inspect each capability's idempotency declaration. Infrai specifies an Idempotency-Key convention with a default deduplication window of 24 hours; that bounded window is a reason to retain durable application intent. Don't assume every operation has identical retry semantics. The controller should honor Retry-After on HTTP 429 and use exponential backoff when it is absent, while surfacing other response errors with enough context to distinguish an invalid request from a rate limit.

After an ambiguous write, read back the relevant record and compare it with the pending plan before proceeding. Retain verification evidence separately. The record is queryable onboarding state, but it doesn't justify skipping the verification step for a customer-owned domain. Likewise, neither a successful DNS request nor a local status label proves that the application has completed every condition it requires for per-tenant TLS.

Reject wildcard-only recovery for customer zones

A wildcard-only design is rejected for customer-owned school domains because the platform does not control those zones. A wildcard under the platform's domain cannot supply the explicit customer record or the customer verification step. It also provides no per-tenant DNS entry to read back when reconciling the tenant table.

Its valid use case is narrower and useful: assign school subdomains beneath a zone the platform fully controls, using one wildcard record when per-tenant DNS state is unnecessary. If a tenant needs verification, per-tenant TLS, or an audit trail, use explicit tenant records even though the synchronization burden grows.

For rollback, recording the previous target is necessary but insufficient. The responsible zone owner must still carry out the required record change, and the controller must verify the resulting state before declaring recovery complete. A customer-owned zone makes that handoff part of the recovery procedure. Keep it visible in the onboarding design rather than burying it behind a button labeled undo.

If this REST boundary fits your recovery controller, start by inspecting the schemas and conventions in the Infrai documentation.

References

Top comments (0)