From b21e358d0d5a8fd1933e119fe0d1d1a45f2d3fb5 Mon Sep 17 00:00:00 2001 From: dlotterman Date: Tue, 3 Nov 2026 12:33:26 -0800 Subject: [PATCH] docs: document Compute outbound internet access (NAT66/NAT64/DNS64) and refresh Private DNS pages --- compute/limitations-and-roadmap.mdx | 2 + compute/overview.mdx | 2 +- compute/private-dns.mdx | 79 +++++++++++------------- compute/troubleshooting.mdx | 3 + domain-dns/dns.mdx | 2 +- domain-dns/overview.mdx | 6 +- domain-dns/private-dns.mdx | 77 +++++++++++------------ galactic-vpc/limitations-and-roadmap.mdx | 7 ++- galactic-vpc/networks/traffic.mdx | 26 ++++++-- galactic-vpc/troubleshooting.mdx | 1 + index.mdx | 2 +- 11 files changed, 112 insertions(+), 95 deletions(-) diff --git a/compute/limitations-and-roadmap.mdx b/compute/limitations-and-roadmap.mdx index 0af6a6c..90b8933 100644 --- a/compute/limitations-and-roadmap.mdx +++ b/compute/limitations-and-roadmap.mdx @@ -32,6 +32,8 @@ The Compute preview has the following limitations. For limitations of each [runt ### 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. diff --git a/compute/overview.mdx b/compute/overview.mdx index e01339e..812b344 100644 --- a/compute/overview.mdx +++ b/compute/overview.mdx @@ -26,7 +26,7 @@ Compute is a good fit if you want to: You create a *workload*. A workload holds a template for the Instances you want (image, command, environment variables, and ports) and one or more *placements* that say where to run them and how many to run in each location. -For each location in a placement, Datum starts the requested number of Instances there. Every Instance attaches to a [network](/galactic-vpc/overview) in your project and receives a private IPv6 address. To reach a workload from the internet, attach Datum's [Application Load Balancer (ALB)](/alb/overview) to it. +For each location in a placement, Datum starts the requested number of Instances there. Every Instance attaches to a [network](/galactic-vpc/overview) in your project and receives a private IPv6 address. Instances can connect out to the internet, including to IPv4-only services by hostname; see [Reach the internet](/galactic-vpc/networks/traffic#reach-the-internet). To reach a workload from the internet, attach Datum's [Application Load Balancer (ALB)](/alb/overview) to it. The following diagram shows a workload with one placement in two locations: diff --git a/compute/private-dns.mdx b/compute/private-dns.mdx index a1c9231..4e77e9f 100644 --- a/compute/private-dns.mdx +++ b/compute/private-dns.mdx @@ -1,75 +1,68 @@ --- title: "Private DNS for Compute" sidebarTitle: "Private DNS" -description: "How Compute publishes stable private names for instances attached to a Datum VPC." +description: "How Compute publishes stable private names for Instances on a gVPC network." --- Compute integrates with [Private DNS](/domain-dns/private-dns) to publish a -predictable name for an instance in each VPC to which it is attached. The name -resolves to the instance's programmed private IPv4 and IPv6 addresses and is -visible only within the associated VPC's DNS context. - - - The Compute integration is under active development and is not yet a stable, - generally available interface. - +predictable name for each Instance on the [network](/galactic-vpc/overview) +that it attaches to. The name resolves to the Instance's private addresses and +resolves only from inside that network. ## Instance names -Compute publishes instance identity names beneath the `instances` subtree of -the VPC's managed namespace. A name has this general form: +Compute publishes Instance names beneath the `instances` subtree of the +network's managed DNS suffix. A name has this general form: ```text -.instances. +.instances. ``` -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. +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. -Treat the complete name reported by the service as an output. The managed -suffix is a platform allocation and should not be constructed or parsed by -applications. +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. -The allocated hostname and its publication state are reported for each network -in `Instance.status.dns`. +Datum reports the allocated hostname and its publication state in +`Instance.status.dns`. ## Published addresses Compute publishes: -- `A` records for private IPv4 addresses. - `AAAA` records for private IPv6 addresses. +- `A` records for private IPv4 addresses. Instances have IPv6 addresses only + during the preview, so they have no `A` records. -An address is eligible only while the instance is ready, its runtime is ready, -and its network interface reports that the address is both allocated and -programmed. Public addresses and delegated prefixes are not published as -instance identity records. +An address is published only while the Instance is ready, its runtime is +ready, and its network interface reports that the address is both allocated +and programmed. Public addresses and delegated prefixes aren't published as +Instance records. -Instance readiness covers the managed runtime and network attachment. Use the -application's own health checks or a service-specific discovery mechanism when -traffic should be sent only to healthy application endpoints. +Instance readiness covers the runtime and the network attachment, not your +app. To send traffic only to healthy app endpoints, use your app's own health +checks or a [network service](/galactic-vpc/networks/network-services). ## Lifecycle behavior -Compute continuously reconciles the DNS records from current instance and -network state: +Compute keeps the DNS records in step with the current Instance and network +state: -- Address changes update the records behind the stable identity name. +- Address changes update the records behind the stable name. - An unavailable or deprogrammed interface withdraws its addresses. -- Deleting the instance removes its published records. -- Resource lifetime checks prevent an old instance from publishing addresses - after it has been replaced. -- An instance attached to more than one VPC receives independently isolated - DNS state for each VPC. - -Publication is asynchronous. A running instance can become ready before its -name is visible in every resolver, and clients can retain an older answer until +- Deleting the Instance removes its records. +- An old Instance can't publish addresses after it has been replaced. + +Publication is asynchronous. A running Instance can become ready before its +name is visible in every resolver, and clients can keep an older answer until the DNS TTL expires. ## Network access -Resolving an instance name does not grant access to the instance. The client -must still have a valid route and be permitted by the applicable network -policy. Clients outside the associated VPC context cannot resolve the private -instance name through public DNS. +Resolving an Instance name doesn't grant access to the Instance. The client +must still be able to reach the Instance on the network. Firewall rules aren't +available yet, so any Instance on the same network can connect to any port. +See [Traffic and connecting](/galactic-vpc/networks/traffic). Clients outside +the network can't resolve the name through public DNS. diff --git a/compute/troubleshooting.mdx b/compute/troubleshooting.mdx index fb81421..21ff20f 100644 --- a/compute/troubleshooting.mdx +++ b/compute/troubleshooting.mdx @@ -39,6 +39,9 @@ The following table lists common errors and states, what they mean, and how to f | 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 diff --git a/domain-dns/dns.mdx b/domain-dns/dns.mdx index d3dc517..6c8cf8a 100644 --- a/domain-dns/dns.mdx +++ b/domain-dns/dns.mdx @@ -10,7 +10,7 @@ sidebarTitle: "Authoritative DNS" To manage zones and records from the terminal with the `datumctl dns` plugin, see [Operations](/domain-dns/operations). -Looking for names that resolve only inside a VPC? See [Private DNS](/domain-dns/private-dns). +Looking for names that resolve only inside a gVPC network? See [Private DNS](/domain-dns/private-dns). ## Current features diff --git a/domain-dns/overview.mdx b/domain-dns/overview.mdx index 65525a0..246e90f 100644 --- a/domain-dns/overview.mdx +++ b/domain-dns/overview.mdx @@ -1,12 +1,12 @@ --- title: "Domains and DNS" sidebarTitle: "Overview" -description: "Track and verify domains, host authoritative DNS, and resolve private names inside Datum VPCs." +description: "Track and verify domains, host authoritative DNS, and resolve private names inside gVPC networks." --- Datum treats domains and DNS zones as resources in your project. You can track and verify domains, host public zones on Datum's global anycast network, and use -Private DNS to resolve resources inside your VPCs. +Private DNS to resolve resources inside your gVPC networks. @@ -16,7 +16,7 @@ Private DNS to resolve resources inside your VPCs. Host authoritative DNS for your zones on Datum's global anycast network. - Resolve private resource and service names inside your VPCs. + Resolve private resource and service names inside your gVPC networks. diff --git a/domain-dns/private-dns.mdx b/domain-dns/private-dns.mdx index f51c9e8..8dfb8df 100644 --- a/domain-dns/private-dns.mdx +++ b/domain-dns/private-dns.mdx @@ -1,35 +1,30 @@ --- title: "Private DNS" -description: "Resolve private service and resource names within a Datum VPC." +description: "Resolve private service and resource names within a gVPC network." --- -Private DNS gives resources in a Datum VPC names that resolve only from that -VPC. It provides a consistent discovery layer for private addresses without -requiring every product or workload to run its own DNS server. - - - Private DNS is under active development. Availability and supported service - integrations may vary while the feature is in preview. - +Private DNS gives resources in a [gVPC](/galactic-vpc/overview) network names +that resolve only from that network. It provides a consistent discovery layer +for private addresses without requiring every product or workload to run its +own DNS server. ## What you can do With Private DNS, you can: - **Reach resources by name:** Use DNS names instead of private IP addresses - that may change over a resource's lifetime. + that can change over a resource's lifetime. - **Use automatic service names:** Integrated Datum services publish names for - resources such as Compute instances. -- **Create private namespaces:** Organize internal applications under private - zones that are available only to associated VPCs. -- **Reuse internal names safely:** Different VPCs can use the same names and - overlapping private addresses without exposing answers to each other. + resources such as Compute Instances. +- **Create private namespaces:** Organize internal apps under private zones + that only associated networks can resolve. +- **Reuse internal names safely:** Different networks can use the same names + and overlapping private addresses without exposing answers to each other. - **Keep records aligned with resources:** Service-managed records update or disappear as their resources and addresses change. -Applications use ordinary DNS lookups. When they run in an associated VPC, -private names resolve alongside public names without application-specific -resolver configuration. +Apps use ordinary DNS lookups. On an associated network, private names +resolve alongside public names with no resolver configuration in the app. ## Private and public DNS @@ -38,46 +33,46 @@ Datum offers two complementary DNS capabilities: | Capability | Where names resolve | Typical use | | --- | --- | --- | | [Authoritative DNS](/domain-dns/dns) | The public internet | Websites, public APIs, email, and domain records | -| Private DNS | Inside an associated VPC | Private instances, internal services, and service discovery | +| Private DNS | Inside an associated network | Private Instances, internal services, and service discovery | -Private DNS records are not published to the public DNS. Creating a private -name does not make a resource reachable from the internet or grant network -access to it. +Private DNS records aren't published to public DNS. A private name doesn't +make a resource reachable from the internet or grant network access to it. ## Names and zones -Each VPC receives a managed DNS suffix for automatic service names. You can -also associate private zones with a VPC for organization-specific names. +Each network receives a managed DNS suffix for automatic service names. You can +also associate private zones with a network for your own names. -- **Managed names:** Datum services publish predictable names beneath the VPC's - managed suffix. -- **Private zones:** Your internal names are visible only from the VPCs with - which the zone is associated. +- **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. -The complete service-managed name includes the VPC's allocated suffix. Use the -name reported by the service instead of constructing it in application code. +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. ## Service integrations -The resource name, published record types, and eligibility rules are defined by -the service that owns the resource. +The service that owns a resource defines its name, its record types, and when +it's published. - Learn how Compute publishes stable private names for instance addresses. + Learn how Compute publishes stable private names for Instances. -Additional Datum services will be documented here as Private DNS integrations +Datum will document more services here as their Private DNS integrations become available. -## What Private DNS does not do +## What Private DNS doesn't do -- **Provide public discovery:** Private names are not available through public +- **Provide public discovery:** Private names aren't available through public DNS. -- **Grant network access:** Routing and access policy still determine whether a - client can reach the returned address. -- **Replace application health checks:** A name can resolve while the - application itself is unavailable. -- **Remove cached answers immediately:** Clients may retain an older answer +- **Grant network access:** Whether a client can reach the returned address + depends on the network, not on DNS. See + [Traffic and connecting](/galactic-vpc/networks/traffic). +- **Replace app health checks:** A name can resolve while the app itself is + unavailable. +- **Remove cached answers immediately:** Clients can keep an older answer until its DNS TTL expires. diff --git a/galactic-vpc/limitations-and-roadmap.mdx b/galactic-vpc/limitations-and-roadmap.mdx index 19e03bf..d0fd83c 100644 --- a/galactic-vpc/limitations-and-roadmap.mdx +++ b/galactic-vpc/limitations-and-roadmap.mdx @@ -17,6 +17,9 @@ In addition to the [networking limitations that apply to all of Compute](/comput - The `networkPolicy` field of a network interface has no effect. Don't rely on it to restrict traffic. Firewall rules are a planned capability. - You can't choose a network's address ranges or create your own subnets. - Networks carry Compute traffic only in the locations where Compute runs: `us-central-1`, `us-east-1`, and `us-west-1`. +- Every network can reach the internet, and you can't turn that off. +- Outbound internet traffic leaves from addresses that are shared with other Datum customers. Datum doesn't publish them, so a destination can't allowlist your Instances by address. +- Instances reach IPv4-only internet services by hostname only. A connection to an IPv4 address fails. See [Reach the internet](/galactic-vpc/networks/traffic#reach-the-internet). ## Planned capabilities @@ -24,8 +27,10 @@ Datum is working on the following networking capabilities: - **Firewall rules:** Security groups that control the traffic to and from your Instances. - **Private DNS:** Private DNS names, so Instances can find each other without IP addresses. +- **Internet access setting:** A setting that turns internet access on or off for every Instance on a network. +- **Datum DNS resolver:** A DNS resolver that Datum runs for Instances, which also performs DNS64. -Outbound internet access, including IPv4 destinations, and viewing networks in the Datum Cloud portal are already available. For details, see [Traffic and connecting](/galactic-vpc/networks/traffic). +Outbound internet access, including IPv4 destinations, and viewing networks in the Datum Cloud portal are already available. For details, see [Reach the internet](/galactic-vpc/networks/traffic#reach-the-internet). For what Datum is building next across the platform, see the [Platform roadmap](/platform/roadmap). diff --git a/galactic-vpc/networks/traffic.mdx b/galactic-vpc/networks/traffic.mdx index b4e3fa2..d436ee9 100644 --- a/galactic-vpc/networks/traffic.mdx +++ b/galactic-vpc/networks/traffic.mdx @@ -1,9 +1,9 @@ --- title: "Traffic and connecting" -description: "Learn which traffic a gVPC network carries and how Instances connect to each other." +description: "Learn which traffic a gVPC network carries, how Instances connect to each other, and how they reach IPv6 and IPv4 internet services." --- -A network carries private traffic between Instances. This page describes which kinds of traffic are possible and how Instances connect to each other. To learn how Instances get their addresses, see [Addressing](/galactic-vpc/networks/addressing). +A network carries private traffic between Instances. This page describes which kinds of traffic are possible, how Instances connect to each other, and how they reach the internet. To learn how Instances get their addresses, see [Addressing](/galactic-vpc/networks/addressing). [gVPC](/galactic-vpc/overview) is in preview, and the `networking.datumapis.com/v1alpha` API can change. @@ -20,8 +20,8 @@ The following table describes which kinds of traffic are possible: | Between different networks | No | Networks are isolated from each other. | | To or from other addresses through an Instance | No | A network only delivers a packet addressed to an Instance's own address, and only accepts a packet from an Instance's own address. An Instance can't route traffic for other addresses, so a router or VPN appliance needs an overlay, such as VXLAN or a UDP tunnel, between Instances. | | Inbound from the internet | Through Datum's ALB | Instance addresses aren't reachable from the internet directly. Public HTTP and HTTPS traffic reaches Instances through Datum's [Application Load Balancer](/alb/overview). Raw TCP and UDP exposure is a preview limitation. | -| Outbound to the internet | Yes | Instances can reach internet destinations, including services that have only IPv4 addresses. | -| Lookups by name | Not in the preview | Private DNS names for Instances are on the [roadmap](/galactic-vpc/limitations-and-roadmap#planned-capabilities). Use IPv6 addresses in the preview. | +| Outbound to the internet | Yes | Instances can reach internet destinations over IPv6, and services that have only IPv4 addresses by hostname. See [Reach the internet](#reach-the-internet). | +| Lookups by name | Public names only | Instances resolve public DNS names. Private DNS names for Instances are on the [roadmap](/galactic-vpc/limitations-and-roadmap#planned-capabilities). Use IPv6 addresses to reach other Instances in the preview. | | Firewall filtering | Not in the preview | Firewall rules to filter traffic between Instances on a network are on the [roadmap](/galactic-vpc/limitations-and-roadmap#planned-capabilities). | The workload API accepts a `networkPolicy` field on each network interface, but the field has no effect. Don't rely on it to restrict traffic. To limit who can reach a service, check credentials in your app, or put services that must stay apart on different networks. Firewall rules for networks are on the [roadmap](/galactic-vpc/limitations-and-roadmap#planned-capabilities). @@ -34,6 +34,24 @@ To connect from one Instance to another on the same network, use the peer's priv - In a URL, put an IPv6 address in square brackets, such as `http://[fd20:4a3b:91c2:1::1:0:2]:8080/`. - Private DNS names aren't available in the preview. To tell an app about its peers, pass their addresses in environment variables or a ConfigMap. +## Reach the internet + +Instances can connect to the internet with no setup. Every network has internet access in every location. + +Instances have private IPv6 addresses only, so Datum's edge translates their outbound traffic: + +- **To IPv6 destinations:** Datum replaces the Instance's private source address with a public IPv6 address (NAT66). +- **To IPv4-only destinations:** When an app looks up a name that has only IPv4 addresses, the Instance's DNS resolver answers with a synthesized IPv6 address that stands for the IPv4 address (DNS64). Datum's edge translates connections to that address into IPv4 (NAT64). The app connects by name as usual and doesn't see the translation. + +TCP, UDP, and ICMP, such as `ping`, work to both IPv6 and IPv4 destinations. + +Keep the following points in mind: + +- **Connect to IPv4 services by hostname, not by IPv4 address.** An Instance has no IPv4 address or route, so a connection to an IPv4 address such as `203.0.113.10` fails. If a service has only a public IPv4 address and no name, create an `A` record for it in a public [DNS zone](/domain-dns/dns) you control, and connect by that name. Private IPv4 addresses, such as `10.0.0.5`, aren't reachable. +- **Use the DNS resolvers that the Instance is given.** Datum configures resolvers that perform DNS64. In a `general-purpose` Instance, they're in `/etc/resolv.conf`. An app or image that uses its own resolver without DNS64, such as DNS over HTTPS or a hard-coded public resolver, gets only IPv4 addresses for IPv4-only names, and can't connect to them. The resolver addresses can change, so don't hard-code them. +- **Outbound traffic leaves from shared addresses.** The Instances in a location share their outbound addresses with each other and with other Datum customers. Datum doesn't publish these addresses, and they can change. Don't ask a destination to allowlist them. Authenticate to the destination instead, for example with an API key or a client certificate. +- **You can't turn off internet access.** Every Instance can reach the internet. A setting to turn off internet access for a network is on the [roadmap](/galactic-vpc/limitations-and-roadmap#planned-capabilities). + ## What's next - To serve a workload publicly through Datum's ALB, see [Compute and ALB](/compute/compute-and-alb). diff --git a/galactic-vpc/troubleshooting.mdx b/galactic-vpc/troubleshooting.mdx index 3a94962..ceb8aa6 100644 --- a/galactic-vpc/troubleshooting.mdx +++ b/galactic-vpc/troubleshooting.mdx @@ -23,6 +23,7 @@ Start with `datumctl network describe NETWORK_NAME` or `datumctl network service | A network is rejected for not including IPv6 | `spec.ipFamilies` doesn't include `IPv6`. | Keep the default, `[IPv6]`. | | Connections between locations stall | `spec.mtu` is larger than the default of `1440`. | Keep the default MTU. | | An Instance can't reach a peer | The app listens only on IPv4, or the URL doesn't bracket the IPv6 address. | Listen on `::` and use `http://[ADDRESS]:PORT/`. See [Traffic and connecting](/galactic-vpc/networks/traffic#connect-to-other-instances). | +| An Instance can't reach an IPv4-only internet service | The app connects to an IPv4 address instead of a hostname, or uses its own DNS resolver instead of the ones that Datum configures. | Connect by hostname, and use the Instance's resolvers. See [Reach the internet](/galactic-vpc/networks/traffic#reach-the-internet). | | `NoMatchingInterfaces`, `MultipleNetworks`, or `NoServingLocations` | A network service isn't serving. | See [Check a network service](/galactic-vpc/networks/network-services#check-a-network-service). | ## MTU diff --git a/index.mdx b/index.mdx index 3c0cfab..a1cf034 100644 --- a/index.mdx +++ b/index.mdx @@ -42,7 +42,7 @@ Datum is still being built. The product is evolving quickly, documentation is gr Secure tunnels to bridge your existing infrastructure into Datum's edge cloud. - Track domains, host authoritative DNS, and resolve private names inside your VPCs. + Track domains, host authoritative DNS, and resolve private names inside your gVPC networks. Datum's global footprint of Regions and Availability Zones.