docs: add Private DNS quickstart, guides, and limits

compute/limitations-and-roadmap.mdx

@@ -17,9 +17,9 @@
 ### Runtime and sizing
 
 - One instance type is available, and you can't set CPU or memory for each container.
 - Persistent disks, raw devices, GPUs, and custom virtual machine images aren't available. Files written at runtime are lost when Datum replaces an Instance.
 - Instances with more than one container aren't supported. Run one container per workload.
 - Health probes, such as readiness and liveness checks, aren't available. An Instance is ready when its containers are running.
 - You can't suspend, resume, or snapshot Instances. You can open a shell or run a command in a running `general-purpose` Instance; see [Instance shell sessions](/compute/instance-shell).
 - A workload's runtime class and network can't change after you create it.
 
@@ -27,14 +27,13 @@
 
 - Compute runs in `us-central-1` (Dallas), `us-east-1` (Ashburn), and `us-west-1` (San Jose).
 - Workloads don't scale automatically, and they can't scale to zero. Don't set `scaleSettings.maxReplicas` or `scaleSettings.metrics`.
 - Rollouts replace Instances one at a time in each location, with no option to add extra Instances during the rollout.
 
 ### Networking
 
 - During the preview, Instances have private IPv6 addresses only. Private IPv4 addresses and public IP addresses are a preview limitation.
 - Instances reach IPv4-only internet services by hostname only, through DNS64 and NAT64. A connection to an IPv4 address fails. See [Reach the internet](/galactic-vpc/networks/traffic#reach-the-internet).
 - Every Instance can reach the internet, and you can't turn that off. Outbound traffic leaves from shared addresses that Datum doesn't publish, so you can't allowlist your Instances at a destination.
-- Private DNS names for Instances are on the [roadmap](/galactic-vpc/limitations-and-roadmap#planned-capabilities).
 - Firewall rules to filter traffic between Instances on a network are on the [roadmap](/galactic-vpc/limitations-and-roadmap#planned-capabilities).
 - Public access is HTTP and HTTPS only, served through Datum's [ALB](/alb/overview). Raw TCP and UDP exposure is a preview limitation.
 

docs.json

@@ -213,6 +213,9 @@
                   "domain-dns/domains",
                   "domain-dns/dns",
                   "domain-dns/private-dns",
+                  "domain-dns/private-dns-quickstart",
+                  "domain-dns/private-dns-zones",
+                  "domain-dns/private-dns-reference",
                   "domain-dns/operations",
                   "domain-dns/point-to-alb",
                   "domain-dns/observability",

domain-dns/limitations-and-roadmap.mdx

@@ -13,6 +13,7 @@ Domains and DNS are still being built. This page lists known limitations and whe
 - **A zone's domain name can't change.** To use a different domain, create a new zone.
 - **One zone for each domain.** A domain can belong to only one zone on Datum.
 - **`ALIAS` isn't portable.** `ALIAS` isn't a standard record type, so a zone file exported from Datum can't carry it to another provider. See [ALIAS](/domain-dns/dns#alias-/-cname-flattening).
+- **Private DNS has no `datumctl dns` or Portal editing yet.** Manage private zones, associations, and records with `datumctl apply`. See [Manage private zones and records](/domain-dns/private-dns-zones).
 - **The DNS API is `v1alpha1`.** Field names in `DNSZone` and `DNSRecordSet` can change between releases. The `datumctl dns` plugin keeps up with those changes for you.
 
 ## Roadmap

domain-dns/private-dns-quickstart.mdx

@@ -0,0 +1,178 @@
+---
+title: "Private DNS quickstart"
+sidebarTitle: "Private DNS quickstart"
+description: "Deploy two workloads on a gVPC network and reach one from the other by its private name."
+---
+
+This quickstart deploys two small workloads on the same [gVPC](/galactic-vpc/overview) network. From the first, you look up the second by its [Private DNS](/domain-dns/private-dns) name and connect to it. Then you give it a name of your own. It takes about ten minutes.
+
+## Before you begin
+
+- Install `datumctl` and the `compute` plugin, and select a project. See [Compute commands](/datumctl/compute/overview).
+- Your account needs the **Compute Admin**, **Network Admin**, and **DNS Admin** roles in the project.
+
+## Reach an Instance by name
+
+<Steps>
+  <Step title="Deploy a web server">
+    Deploy an `nginx` workload named `web` to Dallas:
+
+    ```bash
+    datumctl compute deploy web \
+      --image=docker.io/library/nginx:1.27-alpine \
+      --runtime-class=general-purpose \
+      --location=us-central-1
+    ```
+
+    If this is the first deploy in the project, the command asks whether to create a network named `default`. Enter `y`. Then enter `y` to apply the plan.
+  </Step>
+
+  <Step title="Deploy a client">
+    Deploy a second workload named `client` on the same network. It uses the same image, because the image includes `nslookup` and `wget`:
+
+    ```bash
+    datumctl compute deploy client \
+      --image=docker.io/library/nginx:1.27-alpine \
+      --runtime-class=general-purpose \
+      --location=us-central-1
+    ```
+  </Step>
+
+  <Step title="Find the web server's name">
+    Compute publishes each Instance at `<instance-name>.instances.datum.internal`. Read the exact name from the Instance:
+
+    ```bash
+    datumctl compute instances --workload=web
+    datumctl get instance web-default-us-central-1-0 \
+      -o jsonpath='{.status.dns[0].hostnames[0]}'
+    ```
+
+    The output is similar to the following:
+
+    ```text
+    web-default-us-central-1-0.instances.datum.internal
+    ```
+
+    If the output is empty, wait a few seconds and run the command again. The name appears once the Instance is ready.
+  </Step>
+
+  <Step title="Look up and connect by name">
+    Open a shell in the client and look up the web server:
+
+    ```bash
+    datumctl compute exec client-default-us-central-1-0 -- \
+      nslookup -type=AAAA web-default-us-central-1-0.instances.datum.internal
+    ```
+
+    The answer is the web server's private IPv6 address. Note it for later. Now connect to it by name:
+
+    ```bash
+    datumctl compute exec client-default-us-central-1-0 -- \
+      wget -qO- http://web-default-us-central-1-0.instances.datum.internal/
+    ```
+
+    The output is the `nginx` welcome page.
+  </Step>
+</Steps>
+
+## Give the web server your own name
+
+To give the web server a name you choose, create a private zone of your own, attach it to the network, and add a record.
+
+<Steps>
+  <Step title="Find the network's DNS context">
+    Each network has one DNS context. To list them with the network each one belongs to, run:
+
+    ```bash
+    datumctl get dnsresolvercontexts \
+      -o custom-columns='CONTEXT:.metadata.name,NETWORK:.metadata.ownerReferences[0].name'
+    ```
+
+    Note the `CONTEXT` for the `default` network, such as `dns-default-4f1c2a9e7b30`.
+  </Step>
+
+  <Step title="Create a zone, attach it, and add a record">
+    Save the following as `private-zone.yaml`. Replace `CONTEXT_NAME` with the context from the previous step, and `WEB_ADDRESS` with the web server's address from the lookup:
+
+    ```yaml
+    apiVersion: dns.networking.miloapis.com/v1alpha1
+    kind: DNSZone
+    metadata:
+      name: corp-internal
+    spec:
+      domainName: corp.internal
+      visibility: Private
+    ---
+    apiVersion: dns.networking.miloapis.com/v1alpha1
+    kind: DNSZoneAssociation
+    metadata:
+      name: corp-internal-default
+    spec:
+      dnsZoneRef:
+        name: corp-internal
+      resolverContextRef:
+        name: CONTEXT_NAME
+    ---
+    apiVersion: dns.networking.miloapis.com/v1alpha1
+    kind: DNSRecordSet
+    metadata:
+      name: www
+    spec:
+      dnsZoneRef:
+        name: corp-internal
+      recordType: AAAA
+      records:
+        - name: www
+          ttl: 60
+          aaaa:
+            content: WEB_ADDRESS
+    ```
+
+    Apply it:
+
+    ```bash
+    datumctl apply -f private-zone.yaml
+    ```
+  </Step>
+
+  <Step title="Wait for the zone">
+    Check that the association and record are accepted, and that the zone is programmed:
+
+    ```bash
+    datumctl get dnszoneassociation corp-internal-default \
+      -o jsonpath='{.status.conditions[?(@.type=="Accepted")].status}'
+    datumctl get dnsrecordset www \
+      -o jsonpath='{.status.conditions[?(@.type=="Accepted")].status}'
+    datumctl get dnszone corp-internal
+    ```
+
+    Continue when both commands print `True` and the zone's `PROGRAMMED` column shows `True`. This usually takes less than a minute. If something stays `False`, see [Troubleshooting](/domain-dns/troubleshooting#private-dns).
+  </Step>
+
+  <Step title="Connect by your name">
+    ```bash
+    datumctl compute exec client-default-us-central-1-0 -- \
+      wget -qO- http://www.corp.internal/
+    ```
+
+    The output is the same welcome page. The name resolves only from the `default` network.
+
+    This record holds an address, so update it if Compute replaces the web server's Instance. For names that follow an Instance, see [Find services by name](/domain-dns/private-dns-zones#find-services-by-name).
+  </Step>
+</Steps>
+
+## Clean up
+
+```bash
+datumctl delete -f private-zone.yaml
+datumctl compute destroy client
+datumctl compute destroy web
+```
+
+Deleting the workloads removes their Instance names.
+
+## What's next
+
+- [Manage private zones and records](/domain-dns/private-dns-zones)
+- [Private DNS limits and behavior](/domain-dns/private-dns-reference)
+- [Private DNS for Compute](/compute/private-dns)

domain-dns/private-dns-reference.mdx

@@ -0,0 +1,71 @@
+---
+title: "Private DNS limits and behavior"
+sidebarTitle: "Private DNS limits"
+description: "Where Private DNS is available, naming rules, limits, and how long changes take."
+---
+
+This page lists the rules and limits for [Private DNS](/domain-dns/private-dns).
+
+<Note>
+  Private DNS is in preview, and the `v1alpha1` API can change.
+</Note>
+
+## Locations and runtimes
+
+Private DNS works on every [gVPC](/galactic-vpc/overview) network, in these locations:
+
+| Location | City |
+| --- | --- |
+| `us-central-1` | Dallas |
+| `us-east-1` | Ashburn |
+| `us-west-1` | San Jose |
+
+A network that spans several locations has one set of names. An Instance in one location resolves the names of Instances in the other locations on the same network.
+
+Both [runtime classes](/compute/runtimes/overview), `general-purpose` and `unikernel`, get Private DNS. Instances use the resolvers that Datum configures for them. In a `general-purpose` Instance, they're in `/etc/resolv.conf`. An app that uses its own resolver, such as a hard-coded public resolver or DNS over HTTPS, can't resolve private names.
+
+## Names
+
+- Every network's managed zone is `datum.internal`. Each network has its own copy.
+- Compute publishes Instances at `<instance-name>.instances.datum.internal`. Long or unusual Instance names are shortened, so read the exact name from the Instance's `status.dns`. Compute owns every name at or below `instances.datum.internal`, so you can't add records there or create a zone that covers it.
+- Use full names. Don't rely on short names such as `web-default-us-central-1-0`: they depend on search domains that can differ between Instances.
+- Zone domains use lowercase letters, digits, and hyphens, with each label starting and ending with a letter or digit. They have at least two labels and are at most 253 characters long.
+- Record names are relative to their zone, such as `api`, or fully qualified. `@` means the zone's own domain. Names aren't case-sensitive.
+- A private zone hides the public records of the same domain from the networks it's associated with.
+
+## Record rules
+
+- `ALIAS` and `SOA` records aren't supported. Datum manages each private zone's `SOA` record.
+- A zone's own domain (`@`) can't be a `CNAME`.
+- A `CNAME` can't share a name with another record type.
+- Point a `CNAME` at a name in the same zone. A `CNAME` that points into another zone, or at a public name, may return only the `CNAME`, which most apps can't follow.
+- An `SRV` target must be a name with `A` or `AAAA` records in the same zone.
+- If two record sets have the same name and type, the older one keeps it, and the newer one isn't accepted.
+- A record set is accepted or rejected as a whole. One invalid record keeps every name in it from resolving.
+
+## Limits
+
+| Limit | Value |
+| --- | --- |
+| Private zones a network can resolve, including `datum.internal` | 256. Keep to this or fewer: a 257th association isn't refused yet, but the network then stops picking up DNS changes. |
+| Zone domain length | 253 characters |
+| Default TTL of a record you create | 300 seconds |
+| TTL of an Instance name | 30 seconds |
+
+## How long changes take
+
+| Change | When it takes effect |
+| --- | --- |
+| New Instance | Its name usually resolves within about 30 seconds of the Instance becoming ready. |
+| New record, zone, or association | Usually within a minute of being accepted, and longer when a project changes many names at once. The zone's `Programmed` condition says when. |
+| Changed or removed record | New lookups get the new answer once the zone is programmed. Clients that cached the old answer keep it until its TTL expires. |
+| Deleted or unready Instance | Its addresses are withdrawn. Clients can keep the old answer for up to 30 seconds. |
+
+Publication is asynchronous. Wait for the status conditions described in [Check status](/domain-dns/private-dns-zones#check-status) rather than a fixed delay.
+
+## Privacy
+
+- A private name resolves only from networks that its zone is associated with. Private names aren't published to public DNS.
+- A network resolves another network's zone only through an association that you create.
+- Resolving a name doesn't grant network access. See [Traffic and connecting](/galactic-vpc/networks/traffic).
+- Public names keep resolving through the same resolvers.