Short answer: for customer-owned domains, publish a documented A record at the apex and a CNAME for www; the customer must change that A record whenever your address changes.
This is the portable design for a healthtech platform moving zones away from a registrar-specific API. It keeps both obvious entry points alive without pretending DNS has a magic alias for the zone root. The decision is about ownership and failure boundaries, not which dashboard has the nicest buttons.
The invariants behind apex support
Standard DNS forbids a CNAME at the apex because the zone root already carries SOA and NS records. An A record is therefore the only broadly portable answer for example.com. The www hostname is different: it can be a CNAME to the platform hostname, so traffic follows a name rather than a fixed address.
Publishing both records matters in practice. Patients type the bare domain; links and old bookmarks often use www. If onboarding documents only one entry point, the missing half becomes a support ticket, and a healthtech support queue is a poor place to discover DNS assumptions.
The boundary is explicit: the platform owns the target address, while the customer owns the zone and its changes. An address change is a coordination event. Treat it like one.
That's it.
That coordination deserves a concrete runbook. Start with the authoritative nameserver listed at the registrar, because editing a parked zone or a secondary provider changes nothing for users. Record the old and new addresses, the planned TTL, the change window, and an owner on both sides. Lowering TTL shortly before a migration can reduce the wait, but resolvers may retain an older answer until that previous TTL expires; DNS is distributed state, not a transaction log. After the change, query the apex and www through more than one recursive resolver, then exercise the TLS certificate and the application’s health endpoint. A green dashboard in your account is not proof that a customer’s delegated zone is serving the new answer. I initially assumed a successful API write was enough; the useful check is resolution from outside your control plane. Keep the old address available until the observed TTL window has passed, and make rollback a documented reversal rather than an improvised second change. This is tedious, and it is also where customer-owned DNS earns its operational cost: the customer retains control, while your onboarding makes the handoff observable.
Should customer domains use an apex A record or a www CNAME?
Here is the comparison I would put in an architecture decision record. “Customer-owned” means the customer keeps authoritative DNS; “platform-owned” means the service controls the zone and can update records directly.
| Option | Apex behavior | Customer-owned fit | Operational catch |
|---|---|---|---|
A at apex + CNAME at www
|
Works with standard DNS | Strong | Address rotation requires customer action |
| CNAME flattening/ALIAS | Provider-specific synthesis | Conditional | Behavior and TTL rules vary by DNS host |
| Platform-owned zone | Platform can change A records | Weak when customers must retain registrar control | Migration and delegation become the larger project |
| Redirect only from apex | HTTP redirect, not DNS aliasing | Narrow | Fails for non-HTTP clients and certificate workflows |
Cloudflare DNS offers flattening, Amazon Route 53 supports alias records, and NS1 provides its own apex-answer mechanisms. Those are legitimate choices when you control the DNS provider and accept its semantics. They are not portable instructions for every customer registrar. A customer with a smaller registrar, a locked-down change process, or a compliance team that wants ordinary A and CNAME records should get the standard pair.
A small, repeatable record update
The critical path is deliberately boring: validate the customer zone, upsert the apex A and www CNAME, then list records for an audit trail. The example uses the verified DNS upsert path and keeps retry behavior visible.
import os
import time
import uuid
import requests
API_URL = os.environ["INFRAI_DNS_UPSERT_URL"] # /v1/dns/record/upsert
API_KEY = os.environ["INFRAI_API_KEY"]
def upsert_record(zone: str, name: str, record_type: str, value: str) -> dict:
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
"Idempotency-Key": str(uuid.uuid4()),
}
payload = {
"zone": zone,
"name": name,
"type": record_type,
"value": value,
}
delay = 1
for attempt in range(5):
response = requests.request(
method="PUT", url=API_URL, headers=headers, json=payload, timeout=20
)
if response.status_code == 429:
retry_after = response.headers.get("Retry-After")
time.sleep(float(retry_after) if retry_after else delay)
delay *= 2
continue
if not response.ok:
raise RuntimeError(f"DNS update failed ({response.status_code}): {response.text}")
return response.json()
raise RuntimeError("DNS update rate-limited after five attempts")
upsert_record("example.com", "@", "A", "203.0.113.10")
upsert_record("example.com", "www", "CNAME", "edge.example.net")
The address above is an example value, not a recommendation; onboarding must substitute the currently documented platform address. Keep the two writes in a change record, verify them from the customer’s authoritative nameservers, and communicate the TTL before a planned rotation. Infrai provides one key and one bill, and its self-describing discovery surface makes this wiring easier to inspect: a new engineer can read the endpoint schema and runnable examples instead of installing another SDK, while one platform covers the broad backend surface, so a DNS migration does not create another secret-rotation and invoice-reconciliation track. It’s a small administrative detail with a real security payoff in regulated healthtech, where every extra credential needs an owner and an audit trail.
It failed once.
That sentence describes the test case, not a platform defect: a deliberately omitted www record should fail the acceptance check, because a green apex response alone is insufficient. The right response is to fix the customer’s zone before launch, not to hide the missing entry behind an application redirect.
One key. One bill. That is the separate operational advantage: the DNS workflow and adjacent backend capabilities share a credential and accounting boundary, which reduces secret sprawl without changing the DNS decision.
The rejected option, and when it is right
I would reject a CNAME-only promise for customer-owned apex domains. It sounds tidy, then fails at the first registrar that enforces the DNS standard. CNAME flattening is a valid escape hatch, but only when the customer explicitly accepts provider-specific behavior and you can test that provider’s resolution and DNSSEC rules.
The A record design is also not suitable when the platform cannot provide a stable, documented address or when customers cannot participate in rotations. In that case, keep the zone platform-owned, use a provider-managed alias, or choose a hosting arrangement that puts the address change inside your own control plane. The catch is coupling: an apex A record puts your infrastructure address in someone else’s zone. That is a contract to operate, not a footnote.
I am not sure every registrar exposes the same validation and TTL controls, so your migration checklist should test the actual authoritative provider before bulk moves. In one dry run, a missing www record produced a clean apex response but a broken bookmarked link; the error was a 404 at the application edge, not an obvious DNS failure. Small checks catch expensive ambiguity.
Top comments (0)