From d823c0bc09ae0eebae77f25717dbe703802a62b0 Mon Sep 17 00:00:00 2001 From: Scot Wells Date: Tue, 3 Nov 2026 19:11:41 -0600 Subject: [PATCH 1/2] docs: name the Private DNS zone and instance hostnames State that every VPC's managed zone is datum.internal and that instances resolve at .instances.datum.internal, with examples, the search domain, TTL, and how instance names become DNS labels. --- compute/private-dns.mdx | 43 +++++++++++++++++++++++++++++--------- domain-dns/private-dns.mdx | 24 ++++++++++++++------- 2 files changed, 49 insertions(+), 18 deletions(-) diff --git a/compute/private-dns.mdx b/compute/private-dns.mdx index 4e77e9f..e1b5fad 100644 --- a/compute/private-dns.mdx +++ b/compute/private-dns.mdx @@ -11,22 +11,45 @@ resolves only from inside that network. ## Instance names -Compute publishes Instance names beneath the `instances` subtree of the -network's managed DNS suffix. A name has this general form: +Compute publishes each Instance under the `instances` subdomain of the +network's `datum.internal` zone: ```text -.instances. +.instances.datum.internal ``` -Compute normalizes the Instance name into a valid DNS label when necessary. If -two Instance names normalize to the same DNS name, Private DNS keeps the first -claim and reports a name conflict for the other Instance. +For example, from another Instance on the same network: -Treat the complete name that Datum reports as an output. The managed suffix is -a platform allocation, so don't build or parse it in your app. +```shell +$ dig +short AAAA web-01.instances.datum.internal +fd20:1::5 +$ curl http://web-01.instances.datum.internal:8080/ +``` -Datum reports the allocated hostname and its publication state in -`Instance.status.dns`. +Instances get `datum.internal` as a search domain, so `web-01.instances` also +works. Records have a 30 second TTL. + +Compute turns the Instance name into a valid DNS label: it lowercases the +name, replaces characters other than letters, digits, and `-` with `-`, and +trims leading and trailing `-`. An Instance named `Web_01` is +`web-01.instances.datum.internal`. Names longer than 63 characters are +shortened and given a hash suffix. If two Instances end up with the same DNS +name, Private DNS keeps the first and reports a name conflict for the other. + +Each Instance reports its hostname and whether it's published in +`Instance.status.dns`: + +```yaml +status: + dns: + - network: + name: default + hostnames: [web-01.instances.datum.internal] + conditions: + - type: Ready + status: "True" + reason: Published +``` ## Published addresses diff --git a/domain-dns/private-dns.mdx b/domain-dns/private-dns.mdx index 8dfb8df..452870e 100644 --- a/domain-dns/private-dns.mdx +++ b/domain-dns/private-dns.mdx @@ -40,16 +40,24 @@ make a resource reachable from the internet or grant network access to it. ## Names and zones -Each network receives a managed DNS suffix for automatic service names. You can -also associate private zones with a network for your own names. +Every network gets a managed private zone named `datum.internal`. Datum +services publish their names in it, so an Instance named `web-01` is reachable +at: -- **Managed names:** Datum services publish predictable names beneath the - network's managed suffix. -- **Private zones:** Your internal names resolve only from the networks that - the zone is associated with. +```text +web-01.instances.datum.internal +``` -The complete service-managed name includes the network's allocated suffix. Use -the name that the service reports instead of building it in your app. +Every network uses the same zone name, but each network has its own copy. A +lookup of `web-01.instances.datum.internal` returns the `web-01` on the +client's network, and returns nothing on any other network. + +Instances also get `datum.internal` as a DNS search domain, so the shorter +`web-01.instances` works too. Use the full name in configuration that might +run somewhere without that search domain. + +You can also associate private zones with a network for your own names. Their +records resolve only from the networks the zone is associated with. ## Service integrations From ff9c0787dd1cfa039dcb129aba3ab2e321ba35ef Mon Sep 17 00:00:00 2001 From: Scot Wells Date: Tue, 3 Nov 2026 19:18:07 -0600 Subject: [PATCH 2/2] docs: fix Private DNS name details from review Use a Workload-style Instance name in examples, drop the search-domain and name-conflict claims, describe label rules as code applies them, and point readers at status.dns for the exact hostname. --- compute/private-dns.mdx | 27 ++++++++++++--------------- domain-dns/private-dns.mdx | 15 ++++++--------- 2 files changed, 18 insertions(+), 24 deletions(-) diff --git a/compute/private-dns.mdx b/compute/private-dns.mdx index e1b5fad..26e2f43 100644 --- a/compute/private-dns.mdx +++ b/compute/private-dns.mdx @@ -18,33 +18,30 @@ network's `datum.internal` zone: .instances.datum.internal ``` -For example, from another Instance on the same network: +The Instance name is the one `datumctl get instances` shows. Instances that a +Workload creates are named `---`, so the +first Instance of a Workload named `web` is reachable from another Instance on +the same network at: ```shell -$ dig +short AAAA web-01.instances.datum.internal +$ dig +short AAAA web-default-us-central-1-0.instances.datum.internal fd20:1::5 -$ curl http://web-01.instances.datum.internal:8080/ +$ curl http://web-default-us-central-1-0.instances.datum.internal:8080/ ``` -Instances get `datum.internal` as a search domain, so `web-01.instances` also -works. Records have a 30 second TTL. +Records have a 30 second TTL. -Compute turns the Instance name into a valid DNS label: it lowercases the -name, replaces characters other than letters, digits, and `-` with `-`, and -trims leading and trailing `-`. An Instance named `Web_01` is -`web-01.instances.datum.internal`. Names longer than 63 characters are -shortened and given a hash suffix. If two Instances end up with the same DNS -name, Private DNS keeps the first and reports a name conflict for the other. - -Each Instance reports its hostname and whether it's published in -`Instance.status.dns`: +Compute turns the Instance name into a valid DNS label by replacing `.` with +`-`. Names longer than 63 characters are shortened and given a hash suffix. +Read the exact hostname from `Instance.status.dns` rather than building it +yourself: ```yaml status: dns: - network: name: default - hostnames: [web-01.instances.datum.internal] + hostnames: [web-default-us-central-1-0.instances.datum.internal] conditions: - type: Ready status: "True" diff --git a/domain-dns/private-dns.mdx b/domain-dns/private-dns.mdx index 452870e..1adba59 100644 --- a/domain-dns/private-dns.mdx +++ b/domain-dns/private-dns.mdx @@ -41,20 +41,17 @@ make a resource reachable from the internet or grant network access to it. ## Names and zones Every network gets a managed private zone named `datum.internal`. Datum -services publish their names in it, so an Instance named `web-01` is reachable -at: +services publish their names in it. For example, an Instance named +`web-default-us-central-1-0` is reachable at: ```text -web-01.instances.datum.internal +web-default-us-central-1-0.instances.datum.internal ``` Every network uses the same zone name, but each network has its own copy. A -lookup of `web-01.instances.datum.internal` returns the `web-01` on the -client's network, and returns nothing on any other network. - -Instances also get `datum.internal` as a DNS search domain, so the shorter -`web-01.instances` works too. Use the full name in configuration that might -run somewhere without that search domain. +lookup of that name returns the Instance on the client's network, and returns +nothing on any other network. Use the full name: short names depend on the +search domains the client is configured with. You can also associate private zones with a network for your own names. Their records resolve only from the networks the zone is associated with.