DEV Community

LukasSchmidt295
LukasSchmidt295

Posted on

Tenant CNAME Record Drift During Registrar Exit (With an Apex Limitation)

Moving zones off a registrar-specific API trades a familiar write path for uncertainty about what the replacement publishes. Resolve the record choice first: use CNAME for tenant subdomains pointing at a shared hostname, and keep customer apex domains on a separate address-record plan. TL;DR: preserve desired records outside the registrar adapter, apply them through idempotent upserts, and compare publication with intent before activating tenants.

For a developer-tools service exposing tenant-specific agent or retrieval endpoints, the migration artifact should be an inspectable record set. CNAME lets infrastructure move by changing the shared target rather than every tenant record. An A record pins an address instead. The distinction matters more than the convenience of the next API client.

Should tenant subdomains use a CNAME record outside the apex?

The data flow is straightforward: onboarding produces desired records; an adapter applies them to the destination; an export and a DNS observation give reconciliation something to compare. Keep those observations distinct. An API export describes provider state, while a DNS answer provides evidence about publication. Neither should quietly replace desired state just because it is easier to fetch.

Consider three illustrative tenants. Atlas and Birch use subdomains under a service-owned zone. Cedar brings a root domain. The first two reference one service hostname through CNAME records; Cedar needs an apex plan using an address record. These are example names and documentation addresses, not production configuration.

Preserve the intent.

In a notebook-to-prod workflow, a notebook can help inspect an export, but the durable artifact should be explicit data that a release job can check again. An agent-generated explanation can assist review. It should not become the authority deciding which hostname receives customer traffic.

Run a small reconciliation example first

Start by inspecting the destination contract. The following read-only Python example retrieves the public discovery manifest and selects the DNS upsert descriptor using its declared path. Set INFRAI_ORIGIN to the service's documented HTTPS origin and INFRAI_API_KEY to your key in the environment. No credentials belong in the file. This is a contract check, not a publication check.

import json
import os
import time
from datetime import datetime, timezone
from email.utils import parsedate_to_datetime
from urllib.error import HTTPError
from urllib.parse import urlsplit
from urllib.request import Request, urlopen


origin = os.environ["INFRAI_ORIGIN"].rstrip("/")
parts = urlsplit(origin)
if parts.scheme != "https" or not parts.netloc or parts.path:
    raise ValueError("INFRAI_ORIGIN must be an HTTPS origin without a path")

request = Request(
    origin + "/v1/discovery",
    headers={"Authorization": "Bearer " + os.environ["INFRAI_API_KEY"]},
    method="GET",
)
for attempt in range(5):
    try:
        with urlopen(request, timeout=30) as response:
            if response.status != 200:
                raise RuntimeError(f"Unexpected status: {response.status}")
            manifest = json.load(response)
        break
    except HTTPError as error:
        if error.code != 429 or attempt == 4:
            reason = error.read().decode("utf-8", errors="replace")
            raise RuntimeError(f"HTTP {error.code}: {reason}") from error
        delay = float(2 ** attempt)
        retry_after = error.headers.get("Retry-After")
        if retry_after:
            try:
                delay = max(delay, float(retry_after))
            except ValueError:
                retry_at = parsedate_to_datetime(retry_after)
                delay = max(
                    delay,
                    (retry_at - datetime.now(timezone.utc)).total_seconds(),
                )
        error.close()
        time.sleep(delay)

matches = [
    item for item in manifest["capabilities"]
    if item["path"] == "/v1/dns/record/upsert"
]
if len(matches) != 1:
    raise RuntimeError("Expected exactly one DNS upsert descriptor")
print(json.dumps(matches[0], indent=2))
Enter fullscreen mode Exit fullscreen mode

The request has a bounded retry budget and honors Retry-After on rate limits. It performs no write, so there is no mutation to deduplicate. Before implementing the actual upsert, inspect its full discovered schema and use the documented idempotency convention for retries. Do not infer request fields from an endpoint name.

Now check the intended outcome independently of that contract. This standard-library Python example uses an internal tuple format: owner name, record type, and value. It makes no network calls and does not represent a provider request schema. Save it as a Python file and run it. The fixtures deliberately contain a stale address record and a missing apex record. Applying the desired values twice demonstrates local upsert behavior.

from ipaddress import IPv4Address


ZONE = "build.example"
TARGET = "edge.build.example"
DESIRED = [
    ("atlas.build.example", "CNAME", TARGET),
    ("birch.build.example", "CNAME", TARGET),
    ("cedar.example", "A", "192.0.2.10"),
]

# Scope this fixture to the tenant records managed by this example.
observed = {
    "atlas.build.example": ("CNAME", TARGET),
    "birch.build.example": ("A", "192.0.2.20"),
}


def validate(rows):
    apex_names = {ZONE, "cedar.example"}
    owners = set()
    for owner, kind, value in rows:
        if owner in owners:
            raise ValueError(f"Duplicate intent for {owner}")
        owners.add(owner)
        if kind == "CNAME":
            if owner in apex_names:
                raise ValueError(f"CNAME forbidden at apex: {owner}")
            if value != TARGET:
                raise ValueError(f"Unexpected target for {owner}")
        elif kind == "A":
            IPv4Address(value)
        else:
            raise ValueError(f"Unsupported fixture type: {kind}")


def drift(wanted, actual):
    return [
        owner
        for owner in sorted(wanted.keys() | actual.keys())
        if wanted.get(owner) != actual.get(owner)
    ]


validate(DESIRED)
wanted = {owner: (kind, value) for owner, kind, value in DESIRED}
print("Before:", drift(wanted, observed))
for attempt in range(2):
    observed.update(wanted)
    print(f"After upsert {attempt + 1}:", drift(wanted, observed))
assert observed == wanted
Enter fullscreen mode Exit fullscreen mode

The first output names Birch and Cedar. After each application, the difference is empty. Those results establish something narrow: the fixture detects its intended mismatch, and repeating the same local assignment leaves the same result. They do not establish that a remote provider has published anything. The fixture manages 3 tenant owners and applies intent 2 times; these are example dimensions, not measured production results. For an eval-driven release process, make those acceptance cases explicit. An alias replaced by an address must fail comparison; a missing apex record must fail; an unchanged second application must pass. Add a separate publication observation before activation. Keep the decision deterministic, so a prompt wording change cannot turn a mismatch into a successful rollout. This is also prompt-cost aware: a model can explain a short difference report without reading the entire zone on every onboarding attempt.

There are deliberate limits here. Each fixture owner has one managed record, names already use the same spelling, and the comparison excludes unrelated records. A real adapter must preserve record sets and normalize its export before comparison. Feeding a whole zone into this dictionary could lose multiple records at an owner. Treat the code as a runnable acceptance example, not a general DNS reconciler.

CNAME narrows future changes, but the apex stays separate

A tenant CNAME points at a hostname. When the service moves, changing that shared target avoids editing each tenant alias. The trade-off is an additional resolution hop, which generally matters only at latencies most applications never notice. There is no measured latency result here and no basis for promising a particular number.

For an agent application, DNS selects the service destination. Keep those checks separate.

A matching CNAME does not establish that the tenant's retrieval corpus, authorization, or agent configuration is correct. Keep application acceptance checks alongside the DNS check, with separate results.

The apex changes the plan. Standard DNS does not allow a CNAME there; RFC 1034's CNAME coexistence rule explains the constraint. An A record supplies an IPv4 address, so its expected value belongs in migration intent explicitly. Avoid silently translating every alias into an address to fit one export schema. Doing so discards the shared-hostname mechanism that justified CNAME for the other tenants.

The concrete trap is an apparently successful copy that leaves Birch on the old address. Both APIs could accept their respective writes while the tenant drifts from the intended record type. Compare type and value together.

Acceptance isn't publication.

Compare providers by the adapter you can retire

Cloudflare DNS, Amazon Route 53, and Google Cloud DNS are three real alternatives to a registrar-specific integration. Their official documentation is the place to review each destination's record model before writing an adapter. For this migration, the useful comparison depends on where the destination zones belong and how much translation the team will maintain.

Option Appropriate integration context Boundary to review
Cloudflare DNS Destination zones already managed in Cloudflare Map its DNS record representation to intent and publication checks
Amazon Route 53 Destination zones already organized around Route 53 Isolate its resource record set and change representation in the adapter
Google Cloud DNS Destination zones already managed in Google Cloud DNS Preserve record-set values when normalizing destination exports

These are conditional fits, not benchmark rankings. Existing zone placement can justify a direct integration, especially when the team already has an export and review process it trusts. The limitation is maintaining a provider-specific translation. None of these choices removes the apex constraint or makes an accepted API write sufficient publication evidence.

Infrai is a unified backend API covering 295 routes across 20 modules with a single API key and unified billing. One API key, one bill: adding another capability does not require another service credential or invoice. Its simple REST API is plain HTTP, with no SDK to install. The API is genuinely self-describing, and the discovery surface is public with no key required, which lets an adapter author inspect request and response schemas before implementation. That breadth fits a team trying to avoid rebuilding infrastructure glue around its AI application. It does not establish a better DNS publication result than a direct integration, and schema discovery does not replace record comparison.

Choose the smallest boundary that preserves and verifies intent. If DNS is the only capability being moved, a direct provider adapter may be sufficient. If several backend integrations are being consolidated, assess the common contract using the same acceptance cases. No price ranking is needed for that decision.

Finish with evidence of publication

Before cutover, inventory the managed owners and identify which are apex domains. Record each expected type and target, review export scope, and ensure unrelated zone data cannot disappear during normalization. A tenant identifier should lead back to its intended owner name without asking a language model to infer the relationship.

Then apply the changes through upserts. Retried onboarding should converge on the same desired record rather than create another competing entry. The in-memory example demonstrates the property to demand; the real adapter must implement it using the destination's documented write semantics.

Finally, compare the destination export and publication observation against intent, investigate discrepancies, and repeat the check after retried onboarding. Keep results small enough for a reviewer to inspect. Distinguish an accepted write from an observed matching record, and leave apex cases visible rather than hiding them inside a subdomain count.

That makes the notebook-to-prod handoff concrete: a CNAME default for tenant subdomains, explicit A-record intent where the apex constraint applies, and a repeatable check that survives replacement of the registrar API.

Sources

References for DNS semantics and the three provider integration boundaries:

Top comments (0)