Zones and records

DTM answers DNS authoritatively for the zones you create on it. Everything else about traffic management, health, load balancing, and failover, is expressed as records inside those zones.

Zones

A zone is a DNS namespace DTM owns, such as example.internal.. Create a zone before adding records to it. Each zone has:

• A name (a fully-qualified domain, with a trailing dot, e.g. example.internal.).
• A default TTL applied to records that do not set their own.
• An optional default load-balancing policy inherited at resolve time by records that do not set their own (a record’s own policy always wins).
• SOA fields (primary nameserver, admin contact, refresh, retry, expire, minimum). DTM fills sensible defaults; you only set these if you need specific values. The zone serial is managed for you.

DTM synthesizes the zone’s SOA and NS records automatically, so you never maintain those by hand. If you do create explicit apex NS records (or nameserver host records), yours replace the synthesized ones everywhere, including zone transfers.

A zone is created active and reaches the rest of the cluster within moments. pending appears only when a zone is explicitly created with status: "pending" (replication-aware activation); it flips to active once the node has finished sending it to its peers, normally within a few seconds and at most about 10. See troubleshooting if a zone stays pending.

That propagation is how every change works in DTM: create or update a zone or record on any node, through any management surface, and it is stored durably and replicated to every other node, so every node serves the same answers and losing a node loses no data.

You can create zones from the web UI, the REST API, or the Terraform provider. You can also import existing zones from BIND, Windows DNS, Azure DNS, and other sources.

Deletion locks

A zone can carry a deletion lock. While it is set, deleting the zone fails with a conflict (409) on every surface: the lock is enforced server-side, so the API, Terraform, and the UI all honour it. Deleting a locked zone is a deliberate two-step: clear the lock first, then delete. There is no one-shot force override.

A per-node default (default_zone_deletion_lock, set alongside the bulk-delete cap) makes new zones created through that node start life locked. The default itself does not replicate: a zone created through a node where it was never set is born unlocked, so set it on every node (or declare one dtm_delete_guardrail_config per node endpoint). It applies at creation only: turning it on never retroactively locks existing zones, and an explicit deletion_lock: false on create always wins over the default. A zone’s lock, once set, replicates like any other zone state, so a lock set on one node is enforced on each node once that node has received it: within seconds on every reachable node. Until then, a delete made through a node that has not received the lock is not refused.

Individual records have their own guardrail, the protected flag; see delete guardrails.

Records

A record has a name (relative to the zone, or @ for the zone apex), a type, a TTL, and one or more values. Supported types:

Type	Holds	Notes
A	IPv4 address	Load-balanceable, health-checkable
AAAA	IPv6 address	Load-balanceable, health-checkable
CNAME	Canonical hostname	Exclusive at a name (enforced). Refused at the apex (@) from v1.0.4; use ALIAS there (see below)
MX	Mail exchanger	Uses priority
NS	Delegation nameserver
PTR	Reverse pointer
SRV	Service location	Uses priority, weight, port
TXT	Text
CAA	Issuance authorization (RFC 8659)	tag is issue, issuewild, or iodef; the CAA flag (0 to 255) rides the priority field.
ALIAS	Downstream hostname(s)	Apex-safe; DTM keeps the targets resolved and health-checked for you. See ALIAS records

Changed in v1.0.4: no CNAME at the zone apex

The DNS rules forbid a CNAME at the zone apex, because the apex holds the zone’s SOA and NS records and a CNAME must be the only record at its name. DTM now refuses one: creating a CNAME at @, or renaming one onto it, returns 400; the zone-file, bulk and Azure Private DNS importers skip that record, name it in the zone’s errors and import the rest; a dynamic DNS update carrying one is answered REFUSED. A CNAME already at the apex keeps serving and can still be edited in place, and GET /api/v1/diagnose lists it under apex_cname. To replace it, delete the CNAME first, then create an ALIAS at @ (an ALIAS cannot be created while the CNAME owns the name, so the apex answers nothing between the two calls).

CNAME answers include the target

From v1.0.5, a query for a name that holds a CNAME gets the CNAME followed by the target’s records, as RFC 1034 describes. An A query for www, a CNAME to web in the same zone, returns both the CNAME and web’s addresses. Earlier releases returned the CNAME alone, so a client resolver that does not look up the target itself, such as a container’s resolver or a forwarding proxy, got no address. Zones imported from other DNS servers often use in-zone CNAMEs.

• Targets inside DTM are answered from DTM’s own data: a record in any DTM zone, or a static override. Each step gets the target’s own health filtering, region and load-balancing selection for the asking client, exactly as a direct query would.
• Targets outside DTM depend on whether the client asks for recursion. A client resolver asks by default, and gets the target resolved through the same forwarders a direct query would use, with the forwarder’s allowlist applied to the target. A resolver that treats DTM as authoritative and does not ask for recursion gets the chain within the queried zone only, as BIND does.
• When the outside target is not resolved. If forwarding is off, the allowlist refuses the target, or the rate limit applies, the client gets the chain so far with NOERROR. If a forwarder was asked and failed, the answer is SERVFAIL.
• The blocklist is checked at every CNAME target DTM follows. A blocked target ends the answer with NXDOMAIN after the chain so far. Names inside a forwarded answer are passed on as the forwarder returned them.
• Limits. A loop, or a chain of more than 8 CNAMEs that DTM follows, answers SERVFAIL.
• Visibility. dtm_dns_cname_chain_total counts answers that followed a CNAME, by how the chain ended (its outcome label).

Automatic reverse (PTR) records

Set Maintain reverse (PTR) records on a forward zone (the maintain_reverse flag, available in the web UI, the API, and the dtm_zone Terraform resource) and DTM maintains the matching PTR record whenever an A or AAAA record in that zone is created, updated, or deleted through the record API. The target reverse zone (in-addr.arpa / ip6.arpa) must already exist on DTM and be active; DTM never creates it for you. Auto-generated PTRs are owner-tagged: DTM only ever updates or removes the ones it created, never a PTR you wrote yourself, and a failure to maintain a PTR never fails the forward write.

Note

PTR maintenance currently covers records changed through the API (and UI and Terraform, which use it). Records arriving via RFC 2136 dynamic updates or bulk import do not generate PTRs today.

Values

A record can carry several values. For A/AAAA records, each value is a backend address that DTM can health-check and load-balance. A value may also carry:

• a region tag, used by region-aware load balancing (DTM can also infer it from the address using your subnet mappings);
• priority, weight, and port for record types that use them (MX, SRV).

Wildcard records

DTM serves standard single-label wildcard records: a record named * (or with * as the left-most label, such as *.apps) answers queries for names one label below it that do not otherwise exist.

• One label per wildcard. *.example.internal. answers web.example.internal but not web.eu.example.internal; create *.eu if you need the deeper level. Wildcards can be nested (*.apps and *.svc.apps coexist, each covering its own level).
• An exact record always wins over the wildcard for its name.
• Standard DNS wildcard rules apply (RFC 1034): a name that exists with any record type is never answered by the wildcard (a name holding only a TXT record returns an empty answer for an A query rather than the wildcard’s address), and the zone apex is never covered by *.
• A wildcard CNAME answers queries of any type for matching names.
• At resolution time a wildcard record behaves like any other record: its values pass through the same health-filtering and load-balancing pipeline.
• Not in a Microsoft privatelink zone (changed in v1.0.6). A wildcard such as * in privatelink.blob.core.windows.net would answer for every account name of that service, including accounts you do not own, so it is refused on every write path: the API, the zone importers and RFC 2136 updates. Create one record per private endpoint instead. A wildcard already stored there, on an upgraded node for example, synthesises no answer, is left out of zone transfers, is written as a comment in the BIND export, and is named in a warning at start-up and by GET /api/v1/diagnose under the rule privatelink_wildcard. Delete it, or rename it away, to clear the report. A wildcard in any other zone is unaffected.

Create a wildcard like any other record: use * (or *.sub) as the record name in the UI, API, or Terraform, or import it in a BIND zone file. The * must be the whole leftmost label; partial names such as web-* are rejected.

TTL

The TTL controls how long resolvers cache the answer. Because DTM serves private zones where you control the resolvers, low TTLs (for example 30 or 60 seconds) are practical and give fast failover. A record with no TTL (or an explicit 0) inherits the zone’s default; the ceiling is the DNS wire maximum of 2147483647 seconds (RFC 2181), and the API rejects anything larger.

Load balancing and health

Two optional pieces turn a plain record into a traffic-managed one:

• A load-balancing policy decides which of the healthy values to return to a given client. See load-balancing methods.
• A health-check template tells DTM how to probe each value so it can return only the healthy ones. See health checks.

A record with neither, in a zone with no default policy, returns its healthy values in declaration order, after the region filter described in load balancing: values with region tags are narrowed to the client’s region.

Beyond plain records

• ALIAS records (GSLB) point a name at downstream hostnames (even at the zone apex) and resolve, health-check, and region-balance them for you.
• Override records make a single name in an otherwise forwarded zone health-aware, without recreating the zone.
• Forwarders and stub zones hand queries for other namespaces off to upstream resolvers.