docs: document the datumctl dns plugin and Datum's DNS model - #52
Draft
scotwells wants to merge 2 commits into
Draft
docs: document the datumctl dns plugin and Datum's DNS model#52scotwells wants to merge 2 commits into
scotwells wants to merge 2 commits into
Conversation
Datum hosts authoritative DNS, but the documentation stopped at a feature list and a glossary. Nothing explained how a domain becomes a working zone, and the `datumctl dns` plugin — which is how most people will drive it — was not documented at all. The datumctl section gains a task-oriented guide for the plugin: install it, create a zone, point the registrar at Datum's nameservers, add and change records, import an existing zone file, export, and script against the output. The Domains & DNS section becomes real product documentation. Domain ownership verification gets its own page, because it is the gate that decides whether a zone is provisioned at all and it was previously undocumented. Zones, records, ALIAS, and migrating a zone in or out each get a page, and the overview explains how a domain and a zone relate. One correction outside the section: the ALB DNS setup page attributed a zone stuck at PROGRAMMED=False to missing delegation and told readers to change their nameservers. Delegation happens at the registrar and has no bearing on whether Datum provisions a zone; the usual cause is an unverified domain. That row now names the real cause and links to the verification page. Every command, flag, and status word is taken from the released plugin's own help output or from the operator's source. Behaviour that is not yet released is deliberately absent.
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
The DNS page sat in the same "Plugins" group as the four pages about plugin machinery — installing, trusting, adding catalogs, publishing them, writing your own. A reader looking for what DNS can do had to pick it out from a list otherwise about how plugins work at all. Splitting the group separates the two questions. "Available plugins" answers what you can install and comes first, since that is what most people arrive wanting; "Managing plugins" keeps the mechanics together below it. The split also gives compute and any later plugin an obvious home rather than lengthening a single mixed list. The page is now "DNS" in the sidebar. Under a heading that already says these are plugins, "DNS plugin" repeated the word for no gain, and the surrounding pages follow the same split of a Title Case title and a sentence case sidebar entry. Adds one line to Using Plugins pointing at the new group, so the plugins with real guides are discoverable from the page that explains searching for them. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Draft — the content is complete and checked, but see Before this merges below.
Datum hosts authoritative DNS, but the docs stopped at a feature list and a glossary. Nothing explained how a domain becomes a working zone, and the
datumctl dnsplugin — how most people will actually drive it — was not documented at all.datumctl
One new page,
datumctl/plugins/dns, placed afterusing-pluginsso the general plugin mechanics come first. It follows the journey: install, create a zone, point the registrar at Datum's nameservers, add and change records, import an existing zone file, export, and script against the output.Domains & DNS
The section grows from two pages to seven:
dnsdomainsdomain-verificationdns-zonesdns-recordsalias-recordsmigrate-dnsDomain verification gets its own page because it is the single thing most likely to leave someone stuck, and it was documented nowhere.
A correction outside this section
alb/dns-setup.mdxtold readers that a zone stuck atPROGRAMMED=Falsemeant the domain was not delegated, and to change their nameservers at the registrar. Delegation happens at the registrar and has no bearing on whether Datum provisions a zone — anyone following that advice changes their nameservers and stays stuck. The usual cause is an unverified domain. That row now names the real cause and links to the new verification page. Two lines changed; the rest of the page is untouched.Rejected does not mean refused
Worth calling out for review, because it is counter-intuitive and now has its own section: a zone whose domain is not yet verified reports Rejected, not Pending. The word reads as a permanent refusal, and readers will assume they did something wrong, when the real state is "waiting for you to publish a TXT record".
How this was checked
Every command, flag, argument, and status word comes from the released plugin's own
--helpoutput or from the operator source; no console output was invented. All internal links resolve.docs.jsonis a seven-line change and remains valid JSON.Several things were deliberately left unwritten rather than guessed: DNSSEC, propagation times, zone and record limits, portal screens, nameserver assignment mechanics, and whether an ALIAS can share a name with other record types.
Before this merges
The CLI guide documents
v0.7.0-dev.1, the current published preview, and says so on the page. Behaviour that is merged but unreleased is deliberately absent — in particular--no-managedand the table shortening long names and values (dns-operator#107, #108, #109). Once those ship in a new tag, that page needs a follow-up.Two open questions for a reviewer who knows the product:
ns1–ns4.datumdomains.netlist that was already there.