From fd3687bdd05ba5f715bcff445f945f991b31e7ec Mon Sep 17 00:00:00 2001 From: dlotterman Date: Tue, 3 Nov 2026 14:04:47 -0800 Subject: [PATCH] docs: add IPv6 readiness guidance for Compute Compute and gVPC are IPv6 only. Apps that bind to IPv4 (0.0.0.0, listen 80;) or connect to IPv4 addresses fail, and the docs didn't say so until a deploy failed. - Add an "IPv6 readiness" section to Compute troubleshooting with the pre-deploy checklist, bind examples, a local check, and steps for agents. - Add a short "IPv6 readiness" section to the Compute overview that links to it, and note that Instances are IPv6 only. - Link the first-workload tutorial and the ALB prerequisites to the readiness section. - Tell agents on the deploy-workloads page to search the app's code and config for IPv4 addresses before they deploy, and note in the configuration page that env values should use hostnames. --- compute/compute-and-alb.mdx | 2 +- compute/configuration.mdx | 2 +- compute/overview.mdx | 6 +++++- compute/troubleshooting.mdx | 19 +++++++++++++++++++ datumctl/compute/deploying-workloads.mdx | 4 ++++ getting-started/first-workload.mdx | 6 +++++- 6 files changed, 35 insertions(+), 4 deletions(-) diff --git a/compute/compute-and-alb.mdx b/compute/compute-and-alb.mdx index c1793b3..e83ca12 100644 --- a/compute/compute-and-alb.mdx +++ b/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 diff --git a/compute/configuration.mdx b/compute/configuration.mdx index 962cb58..2a39d18 100644 --- a/compute/configuration.mdx +++ b/compute/configuration.mdx @@ -21,7 +21,7 @@ You can set environment variables, and load or mount whole ConfigMaps and Secret ## 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 \ diff --git a/compute/overview.mdx b/compute/overview.mdx index 812b344..e1b161b 100644 --- a/compute/overview.mdx +++ b/compute/overview.mdx @@ -1,7 +1,7 @@ --- 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." --- @@ -66,6 +66,10 @@ If you don't name a runtime class, Datum uses `unikernel`. For a detailed compar - **`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 diff --git a/compute/troubleshooting.mdx b/compute/troubleshooting.mdx index 21ff20f..a199c71 100644 --- a/compute/troubleshooting.mdx +++ b/compute/troubleshooting.mdx @@ -10,6 +10,25 @@ This page lists common Compute errors and states, what they mean, and how to fix Compute is in preview, and the `v1alpha` API can change. +## 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`. diff --git a/datumctl/compute/deploying-workloads.mdx b/datumctl/compute/deploying-workloads.mdx index f3c48bc..82965f1 100644 --- a/datumctl/compute/deploying-workloads.mdx +++ b/datumctl/compute/deploying-workloads.mdx @@ -14,6 +14,10 @@ datumctl compute deploy api \ --http-port=8080 ``` + + 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). + + 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). diff --git a/getting-started/first-workload.mdx b/getting-started/first-workload.mdx index fd048bc..d7c621e 100644 --- a/getting-started/first-workload.mdx +++ b/getting-started/first-workload.mdx @@ -7,6 +7,10 @@ description: "Deploy draw.io to Datum Compute and open it in your browser throug Compute is in preview. The `v1alpha` APIs can change, and Datum reviews Compute access requests manually. + + Datum networking is IPv6 only. draw.io already listens on IPv6, so this tutorial works as written. To deploy your own app, make it listen on `::` first. See [IPv6 readiness](/compute/troubleshooting#ipv6-readiness). + + ## Before you begin - Create a Datum Cloud account, an organization, and a project. For more information, see [Account setup](/getting-started/account-setup). @@ -106,7 +110,7 @@ This page deploys [draw.io](https://www.drawio.com/), an open source diagramming ## What's next -- To deploy your own image, check that your app listens on IPv6 and serves plain HTTP. During the preview, Instances have no persistent disks and no readiness checks. For details, see [Compute limitations](/compute/limitations-and-roadmap#limitations). +- To deploy your own image, check that your app listens on IPv6 and serves plain HTTP. See [IPv6 readiness](/compute/troubleshooting#ipv6-readiness). During the preview, Instances have no persistent disks and no readiness checks. For details, see [Compute limitations](/compute/limitations-and-roadmap#limitations). - To pass configuration and secrets to a workload, see [Compute configuration](/compute/configuration). - To package your own app as a fast-starting unikernel, see [Unikernels](/compute/runtimes/unikernels). - To run in more locations or with more Instances, see [Placement and scaling](/compute/placement-and-scaling).