Skip to content

docs: add Private DNS quickstart, guides, and limits - #120

Merged
dlotterman merged 10 commits into
mainfrom
docs/private-dns-guides
Nov 18, 2026
Merged

dlotterman merged 10 commits into
mainfrom
docs/private-dns-guides

Conversation

@scotwells

@scotwells scotwells commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

Requested by Scot Schuchert-Wells

Adds the customer docs for Private DNS:

  • Quickstart: deploy two workloads, reach one from the other by its Instance name, then give it a name in your own private zone.
  • Private zones and records: add records to a network's datum.internal zone, create private zones, choose which networks resolve them, and find services by name.
  • Limits and behavior: supported locations and runtimes, naming and record rules, limits, and how long changes take.
  • Troubleshooting: what to check when a private name doesn't resolve, and what each status reason means.

It also removes "Private DNS is planned" from the gVPC and Compute pages, and documents editing private records with datumctl dns record --vpc. The pages match dns-operator v0.15.0, which production runs: private zones need no zone class, and an association past 256 zones is refused with ZoneLimitExceeded.

Builds on #119, which names the zone and Instance hostnames.

Test plan

  • Ran the quickstart end to end in a production project: Instance name lookup and connection, then a private zone, association and AAAA record, all resolving from the network. Cleaned up afterward.
  • Quickstart re-run end to end on Nov 18 passed (see the PR conversation).

Related: datum-cloud/enhancements#921

Add a quickstart that reaches an Instance by its private name and then
by a custom name, a guide to private zones, records, and network
associations, a limits and behavior reference, and Private DNS
troubleshooting. Stop describing Private DNS as planned.
@mintlify

mintlify Bot commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated
Datum 🟢 Ready View Preview Nov 18, 2026, 3:10 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

Use an AAAA record in the quickstart, since CNAMEs into another zone
are not followed yet. Add the Network Admin role, use made-up names in
examples, and correct the troubleshooting reasons.
@cla-assistant

cla-assistant Bot commented Nov 4, 2026 •

Copy link
Copy Markdown

CLA assistant check
All committers have signed the CLA.

Private zones no longer need a zone class.

@ecv ecv left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hold.

The pages are consistent with the contract and with the code I could check (managed domain datum.internal, status.dns[].hostnames, record types, record-set shape, reasons, the 300 and 30 second TTLs). Merging publishes them, and today they promise availability and network isolation that production does not yet have, plus a limit that is not enforced. Re-request once Private DNS is on in production and the points below are fixed.

  • Public docs state Private DNS works on every gVPC network in all three locations and drop it from both roadmaps. Production enablement is still in rollout (NSO internalDNS, Compute publishing, preflight in infra), staging only today, and NSO#859 says "before enablement outside staging". Keep this unmerged until prod is on.
  • The quickstart and zones page create a private zone with no dnsZoneClassName. That is rejected until dns-operator#479 is deployed. Same for the DNS Admin claims: customer writes to registrations and naming policies are only removed by dns-operator#480.
  • "Networks never see each other's private zones" and the privacy section rest on NSO#859 and the admission policy being applied in the project API. Say nothing stronger than what #859 enforces until it is in production.
  • "Private zones a network can resolve: 256" is stated as a limit, but the contract (#476) lists it as not enforced: a 257th association is accepted and the network's serving config then fails to update. Reword as a recommended maximum or note the behavior.
  • "Zone domains use lowercase letters, digits, and hyphens" is narrower than the contract (any lowercase DNS name); pick one.

Follow-ups:

  • Docs state "no datumctl dns or Portal editing yet", which matches the CLI today (no --visibility on zone create).

Describe private zone visibility only as association-based, and say
what happens past 256 zones on a network, since that isn't refused yet.
ecv
ecv previously requested changes Nov 4, 2026

@ecv ecv left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Request changes.

The delta since ca3dd44 is two files and four lines: the 256 limit, the zone-label rule and the isolation wording are fixed, but the quickstart and zones pages still publish a flow production rejects, and the isolation claim still rests on an unmerged policy.

  • Zone class is not fixed by the docs. The quickstart and zones page omit dnsZoneClassName, which only works once dns-operator#479 is deployed. #479 and #480 merged today (20:11Z), after the latest release v0.13.0 (Nov 3), and production is pinned to v0.13.0 (apps/dns-operator/internal-dns/production/source.yaml). A customer following the quickstart today gets the zone rejected. Hold until a dns-operator release with #479 and #480 is pinned in production, or put the class back in the examples until then.
  • The DNS Admin claims (quickstart roles, zones page) depend on #480 the same way: customers can still write registrations and naming policies in production until it ships.
  • Isolation is softened but still asserted. "A private name resolves only from networks that its zone is associated with" and "each gets its own answers" still depend on the production admission policy, infra#8596, which is approved but not merged or released. NSO#859 merged, but its review notes an incomplete annotation set still reaches the hub unverified. Either hold for #8596 or drop the claim to what production enforces today.
  • Availability is now true. internalDNS.enabled: true is in production's NSO and Compute config, and Compute publishing has been in tag v0.84.214 since Nov 3. The roadmap edits (all three locations, DNS resolver items removed) match that, so the original availability point is resolved.
  • The 256 limit now says a 257th association is not refused and the network stops picking up DNS changes. The zone-label rule is now exact. Both resolved.

Follow-ups:

  • Re-check the quickstart end to end against production after the dns-operator release is pinned, since the whole page is written against the class-optional behavior.

@ecv
ecv requested a review from andrewb3000 November 5, 2026 04:25
andrewb3000
andrewb3000 previously approved these changes Nov 5, 2026

@kevwilliams kevwilliams left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hold: the limits and CLI pages contradict dns-operator v0.15.0, which is now live.

  • A 257th zone association is now refused with ZoneLimitExceeded; reword the limits row and add the reason to the troubleshooting table.
  • datumctl dns record commands now edit private zones with --vpc; narrow the "no datumctl dns" bullet to zone creation and associations.
  • The earlier zone class, DNS Admin and isolation points are resolved by released code; re-run the quickstart end to end.

@dlotterman

Copy link
Copy Markdown
Contributor

I re-ran the quickstart through Sonnet, passed cleanly.

dlotterman and others added 2 commits November 18, 2026 15:02
- State that a 257th zone association is refused with ZoneLimitExceeded,
  and add the reason to the troubleshooting table.
- Narrow the "no datumctl dns" limitation to zone creation, associations
  and Portal editing, and document datumctl dns record with --vpc for
  editing records in private zones.

@dlotterman dlotterman left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@dlotterman
dlotterman dismissed ecv’s stale review November 18, 2026 15:11

Handled via various updates

@dlotterman
dlotterman merged commit 9bd483e into main Nov 18, 2026
5 checks passed
@dlotterman
dlotterman deleted the docs/private-dns-guides branch November 18, 2026 15:12

This branch was successfully deployed

1 active deployment
staging — 440f1734 Deployed Nov 18, 2026 by mintlify[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants