docs: add IPv6 readiness guidance for Compute

compute/compute-and-alb.mdx

@@ -14,7 +14,7 @@ Instances have private IPv6 addresses only, so the internet can't reach them dir
 
 - Select a project, install the `compute` plugin, and get access to Compute. For more information, see [Compute commands](/datumctl/compute/overview).
 - Make sure that you have permission to create networking resources in the project, in addition to compute resources. The **Network Admin** role includes the permissions that publishing needs. The **Gateway Admin** role alone isn't enough.
-- Make sure that your app serves plain HTTP, not HTTPS, on the port that you publish, and listens on IPv6.
+- Make sure that your app serves plain HTTP, not HTTPS, on the port that you publish, and listens on IPv6. See [IPv6 readiness](/compute/troubleshooting#ipv6-readiness).
 
 ## Attach an ALB with datumctl
 

compute/configuration.mdx

@@ -21,7 +21,7 @@
 
 ## Set environment variables
 
-To set an environment variable to a fixed value, pass `--env KEY=VALUE` when you deploy. Repeat the flag for each variable. Values can contain commas. The following command sets two variables:
+To set an environment variable to a fixed value, pass `--env KEY=VALUE` when you deploy. Repeat the flag for each variable. Values can contain commas. Instances have IPv6 addresses only, so use hostnames, not IPv4 addresses, in values such as database URLs. The following command sets two variables:
 
 ```bash
 datumctl compute deploy WORKLOAD_NAME \
@@ -195,7 +195,7 @@
 
 ## Disk volumes
 
 The `spec.template.spec.volumes` field also accepts a `disk` volume type, which `datumctl explain` lists with a size request and a populator. No runtime class serves disk volumes during the preview, so Datum rejects a workload that declares one with the following error:
 
 ```text
 disk-backed volumes are not supported by the "CLASS" runtime class

compute/limitations-and-roadmap.mdx

@@ -18,9 +18,9 @@
 
 - One instance type is available, and you can't set CPU or memory for each container.
 - Persistent disks aren't available. The workload API includes a `disk` volume type, but no runtime class serves it, so Datum rejects a workload that declares one. Files written at runtime are lost when Datum replaces an Instance. For details, see [Disk volumes](/compute/configuration#disk-volumes).
 - Raw devices, GPUs, and custom virtual machine images aren't available.
 - 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.
 
@@ -28,14 +28,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.
 

compute/overview.mdx

@@ -1,11 +1,11 @@
 ---
 title: "Compute"
 sidebarTitle: "Overview"
-description: "Run your apps as isolated Instances in Datum Cloud locations, from a standard container image or a fast-starting unikernel."
+description: "Run your apps as isolated Instances in Datum Cloud locations, from a standard container image or a fast-starting unikernel. Instances are IPv6 only."
 ---
 
 <Note>
 **Working with this product via an AI agent?** [Datum MCP](/agents/datum-mcp) gives agents live access to workloads and Instances through its `compute` toolset, including Compute's own diagnostic tools. For an open-ended question such as "why isn't my workload available?", agents can ask [Patch](/datumctl/ai/assistant) with `datumctl assistant chat`.
 </Note>
 
 Datum Cloud Compute runs your app close to your users. You describe what to run and where, and Datum starts isolated Instances in the locations you choose, connects them to a private network, and can serve them publicly through Datum's Application Load Balancer (ALB).
@@ -20,7 +20,7 @@
 
 - Run an HTTP service or API in more than one location without operating servers.
 - Deploy a container image you already build, with virtual machine isolation.
 - Start small, purpose-built services in a fraction of a second as unikernels.
 
 ## How it works
 
@@ -66,6 +66,10 @@
 - **`datumctl compute`:** A `datumctl` plugin that deploys, publishes, scales, and deletes workloads with a single command each. The guides in this section use it. For the command reference, see [Compute commands](/datumctl/compute/overview).
 - **Manifests:** Workloads are Kubernetes-style resources. You can write them in YAML and manage them with `datumctl apply`, `datumctl get`, and `datumctl describe`, or with GitOps tooling. For more information, see [Kubernetes](/platform/kubernetes).
 
+## IPv6 readiness
+
+Compute and gVPC are IPv6 only. An app that listens only on IPv4, such as `0.0.0.0`, is unreachable, and any IPv4 address in its configuration, such as a database URL, must become a hostname. Before you deploy your own app, see [IPv6 readiness](/compute/troubleshooting#ipv6-readiness).
+
 ## What's next
 
 <CardGroup cols={2}>

compute/troubleshooting.mdx

@@ -10,6 +10,25 @@
   Compute is in preview, and the `v1alpha` API can change.
 </Note>
 
+## IPv6 readiness
+
+Compute and gVPC are IPv6 only. Instances have no IPv4 address, and the internet reaches them only through the ALB. Check these before you deploy your own app:
+
+- **Listen on `::`.** An app bound to `0.0.0.0`, or to `listen 80;` in nginx, is unreachable. Bind the port that you pass to `--http-port` on `::`.
+- **Connect by hostname.** Use a name, not an IPv4 address, for every service the app calls, including database URLs and proxy targets in its config. See [Reach the internet](/galactic-vpc/networks/traffic).
+- **Serve plain HTTP.** Datum terminates TLS at the ALB and connects to your Instances over HTTP.
+
+| Server | Listen on IPv6 |
+| --- | --- |
+| nginx | `listen [::]:80;` |
+| Node.js | `app.listen(8080, "::")` |
+| Python | `uvicorn app:app --host :: --port 8080` |
+| Go | `http.ListenAndServe(":8080", handler)`, which listens on IPv6 and IPv4 |
+
+To check the listen address on a machine with IPv6, run `ss -ltn` and look for `[::]:8080`. An IPv4-only app shows `0.0.0.0:8080` instead.
+
+If you're an agent deploying an app for a user, search the code and config for `0.0.0.0`, `127.0.0.1`, `listen 80`, and IPv4 addresses, change them to `::` and hostnames, and then deploy with `--http-port`.
+
 ## Common problems
 
 The following table lists common errors and states, what they mean, and how to fix them. Errors that Datum returns when you apply a workload appear in the command output. Reasons appear in `datumctl get workloads`, `datumctl get instances`, and `datumctl compute instances describe`.
@@ -31,17 +50,17 @@
 | `ReferencedDataNotReady` with `SourceTooLarge` | A referenced ConfigMap or Secret is larger than 256 KiB, or all of them together exceed 1 MiB. | Make the objects smaller. |
 | `ReferencedDataNotReady` with `SourceUnauthorized` | Datum can't read a referenced ConfigMap or Secret. | Check that the object is in the same project, and contact support if the problem continues. |
 | `ImageUnavailable` | Datum couldn't pull the image. | Check the image reference and tag. For a private registry, check the `imagePullSecrets` Secret. |
 | A standard container image, such as nginx, won't start | You didn't set a runtime class, so the workload uses the default `unikernel` class, which doesn't boot standard container images. | Deploy a new workload with `--runtime-class=general-purpose`. You can't change a workload's runtime class. See [Run a container image](/compute/runtimes/general-compute). |
 | `InstanceCrashing` | The program starts and exits repeatedly. | Check the command, arguments, environment variables, and mounted files. For a `unikernel` workload, rebuild with `datumctl compute build --analyze`. |
 | `ConfigurationError` | Datum refused the configuration before the program ran. | Check the environment variables and volume references. |
 | The Instance stays `Starting` for more than a few minutes | The first image pull can take a while. A program that exits at startup can also stay in this state. | Check the image and configuration. For a `unikernel` workload, run `datumctl compute build --analyze`. If the problem continues, contact support. |
 | The Instance is `Available`, but the ALB's hostname returns an error | The app isn't reachable on the published port, or the container isn't running even though the Instance is `Available`. | Make sure that the app listens on IPv6 (`::`; in nginx, add `listen [::]:8080;` because `listen 8080;` binds IPv4 only), serves plain HTTP, and uses the port that you passed to `--http-port`. Check the logs with `datumctl compute logs WORKLOAD_NAME`. If the container exits at startup, check its `securityContext`. See [Images that use sudo or setuid](/compute/runtimes/general-compute#images-that-use-sudo-or-setuid). For a walkthrough of what IPv6-only means for your app, see [How debugging a 503 turned into an IPv6 crash course](https://www.datum.net/blog/ipv6-crash-course). |
 | The ALB returns `503` for a minute or two after the Instance becomes `Available` | The Instance is running, but the app inside it is still starting. | Wait, or give the app a faster startup. Apps such as JVMs can take a minute or more to listen. |
 | `sudo` or another setuid program fails with a permission error | `allowPrivilegeEscalation` defaults to `false`. | Do the privileged work at build time, or set `allowPrivilegeEscalation: true`. See [Images that use sudo or setuid](/compute/runtimes/general-compute#images-that-use-sudo-or-setuid). |
 | A new image version doesn't show up after a rollout | The image was pushed again under the same tag. | Push each version with a new tag, or reference the image by digest. |
 | An Instance can't connect to an IPv4 address, such as `203.0.113.10` | Instances have IPv6 addresses only. They reach IPv4-only services through DNS64 and NAT64, which work only when the app connects by hostname. | Connect by hostname. If the service has a public IPv4 address but no name, create an `A` record for it in a public DNS zone you control. See [Reach the internet](/galactic-vpc/networks/traffic#reach-the-internet). |
 | An Instance can't connect to an IPv4-only service by hostname | The app or image uses its own DNS resolver without DNS64, such as DNS over HTTPS or a hard-coded public resolver, which returns only IPv4 addresses. | Use the resolvers that Datum configures, in the Instance's `/etc/resolv.conf`. They perform DNS64. |
 | A destination that allowlists source addresses rejects the Instance | Outbound traffic leaves from addresses that are shared with other Datum customers and can change. | Authenticate to the destination with credentials, such as an API key or a client certificate, instead of allowlisting addresses. |
 | `curl` can't resolve the ALB's hostname | The new hostname hasn't propagated. | Wait a few minutes and try again. |
 
 ## See why an Instance won't start

datumctl/compute/deploying-workloads.mdx

@@ -14,6 +14,10 @@ datumctl compute deploy api \
   --http-port=8080
 ```
 
+<Note>
+  Datum networking is IPv6 only, and Instances have no IPv4 address. Before you run a deploy command for your own app, search the app's code and config (including `.env` files, database URLs, and proxy targets) for `0.0.0.0`, `127.0.0.1`, `listen 80`, and IPv4 addresses. Change them to `::` and hostnames, and tell the user what you changed. See [IPv6 readiness](/compute/troubleshooting#ipv6-readiness).
+</Note>
+
 <Warning>
   A new workload without `--runtime-class` runs on the `unikernel` runtime class. For that class, `--image` must point to an image produced by `datumctl compute build`, not a standard OCI image from `docker build` — see [Building images](/datumctl/compute/building-images). To run a standard container image unchanged, add `--runtime-class=general-purpose` — see [Choose a runtime class](/compute/runtimes/overview).
 </Warning>

docs.json

@@ -215,6 +215,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.