From 7eaed5ba4516bc3edd05fe4be02df6b53c1fd829 Mon Sep 17 00:00:00 2001 From: dlotterman Date: Tue, 10 Nov 2026 17:43:43 -0800 Subject: [PATCH] docs: add Network Load Balancer section Add a top-level NLB section next to ALB for the Network Load Balancer early access: overview, listeners and routes, addresses and hostnames, health checks, traffic handling, operations, observability, troubleshooting, limits and quotas, and limitations and roadmap. The operations page walks through preparing a backend, creating an NLB, and connecting to it. Add a page for pointing a Datum DNS domain at an NLB. Every behaviour is checked against production NLBs: status conditions and their messages, UnsupportedCapability errors, quotas, health check timing, flow hashing, source address, the 1392-byte UDP payload limit, DNS publishing and withdrawal, and delete ordering. The backend, create and connect steps were followed verbatim in a fresh project. Update existing pages that said raw TCP and UDP exposure isn't available, link the NLB from the platform, gVPC, Compute and ALB pages, document UDP ports on network services, and point the NLB changelog entries at the new section. The October 30 entry said IPv4 was available; production refuses it, so it now says IPv4 isn't available yet. --- alb/limitations-and-roadmap.mdx | 2 +- alb/overview.mdx | 2 +- changelog.mdx | 6 +- compute/compute-and-alb.mdx | 1 + compute/limitations-and-roadmap.mdx | 2 +- compute/overview.mdx | 1 + docs.json | 22 ++ domain-dns/point-to-nlb.mdx | 65 ++++ galactic-vpc/limitations-and-roadmap.mdx | 3 +- galactic-vpc/networks/network-services.mdx | 40 +- galactic-vpc/networks/overview.mdx | 2 +- galactic-vpc/networks/traffic.mdx | 2 +- galactic-vpc/operations.mdx | 2 +- galactic-vpc/overview.mdx | 2 +- guides/overview.mdx | 1 + index.mdx | 5 +- nlb/addresses-and-hostnames.mdx | 130 +++++++ nlb/health-checks.mdx | 92 +++++ nlb/limitations-and-roadmap.mdx | 35 ++ nlb/limits-and-quotas.mdx | 51 +++ nlb/listeners-and-routes.mdx | 103 +++++ nlb/observability.mdx | 94 +++++ nlb/operations.mdx | 351 ++++++++++++++++++ nlb/overview.mdx | 92 +++++ nlb/traffic-handling.mdx | 51 +++ nlb/troubleshooting.mdx | 133 +++++++ platform/envoy.mdx | 2 +- platform/galactic.mdx | 3 +- platform/isolation.mdx | 7 +- platform/kubernetes.mdx | 1 + platform/roadmap.mdx | 2 + platform/zerotrust.mdx | 2 +- .../config/vocabularies/Mintlify/accept.txt | 1 + 33 files changed, 1288 insertions(+), 20 deletions(-) create mode 100644 domain-dns/point-to-nlb.mdx create mode 100644 nlb/addresses-and-hostnames.mdx create mode 100644 nlb/health-checks.mdx create mode 100644 nlb/limitations-and-roadmap.mdx create mode 100644 nlb/limits-and-quotas.mdx create mode 100644 nlb/listeners-and-routes.mdx create mode 100644 nlb/observability.mdx create mode 100644 nlb/operations.mdx create mode 100644 nlb/overview.mdx create mode 100644 nlb/traffic-handling.mdx create mode 100644 nlb/troubleshooting.mdx diff --git a/alb/limitations-and-roadmap.mdx b/alb/limitations-and-roadmap.mdx index f219230..604f439 100644 --- a/alb/limitations-and-roadmap.mdx +++ b/alb/limitations-and-roadmap.mdx @@ -9,7 +9,7 @@ The Application Load Balancer is still being built. This page lists known limita ## Limitations - There is no single composite ALB API yet. An ALB is an `HTTPProxy`, a `TrafficProtectionPolicy`, and optional authentication resources. See [What an ALB is made of](/alb/overview#what-an-alb-is-made-of). -- Public traffic is HTTP and HTTPS only. Raw TCP and UDP exposure isn't available. +- An ALB serves HTTP and HTTPS only. To publish raw TCP or UDP traffic, such as a database or a game server, use a [Network Load Balancer](/nlb/overview). - Rule exclusions, score thresholds, rate limiting, and circuit breaking aren't available through `datumctl alb`. Use manifests. See [Web application firewall](/alb/configuration/waf). - A `connector` backend must be the only backend in its rule. - You can't choose which Datum locations serve a load balancer or set its capacity. [Envoy](/platform/envoy) in every location serves every load balancer, and Datum scales the fleet. diff --git a/alb/overview.mdx b/alb/overview.mdx index 059586a..c65467c 100644 --- a/alb/overview.mdx +++ b/alb/overview.mdx @@ -10,7 +10,7 @@ description: "Datum's Application Load Balancer (ALB) is built on Envoy and prov Datum's Application Load Balancer (ALB) is an edge proxy built on [Envoy](/platform/envoy), with a [Coraza](https://www.coraza.io/)-based [web application firewall](/alb/configuration/waf) (WAF). It started life as Datum's "AI Gateway", and it's built for AI and agent traffic as much as for websites and APIs. -Application Load Balancers help you protect and route internet traffic to your backend services. We support HTTP(S) 1.1, HTTP/2, HTTP/3, gRPC, and WebSockets. See [How the load balancer handles requests](/alb/request-handling). +Application Load Balancers help you protect and route internet traffic to your backend services. We support HTTP(S) 1.1, HTTP/2, HTTP/3, gRPC, and WebSockets. See [How the load balancer handles requests](/alb/request-handling). For raw TCP or UDP traffic, such as a database or a game server, use a [Network Load Balancer](/nlb/overview) instead. Running NGINX, Apache, Caddy, or Traefik in front of your app? To replace that container with an ALB, see [Use ALB as your HTTP proxy](/guides/alb-as-httpd). diff --git a/changelog.mdx b/changelog.mdx index 9ee9f5b..4cf47f7 100644 --- a/changelog.mdx +++ b/changelog.mdx @@ -37,7 +37,7 @@ Each entry links to the original announcement in our [changelog discussions](htt - **Fixed:** deleting a listener works on the first try. - **Fixed:** the **Add listener** dialog no longer flashes a warning as it closes. - NLBs are early access. See [Network services](/galactic-vpc/networks/network-services). + NLBs are early access. See [NLB operations](/nlb/operations). @@ -164,14 +164,14 @@ Each entry links to the original announcement in our [changelog discussions](htt Publish a network service on a public TCP or UDP port with a network load balancer (NLB). - - **Addresses and hostnames:** each location gets a public IPv6 address and a generated hostname you can point a CNAME at. IPv4 is available for single-port listeners where Datum has enabled it. + - **Addresses and hostnames:** each location gets a public IPv6 address and a generated hostname you can point a CNAME at. IPv4 isn't available yet. - **Health checks:** NLBs actively check backends and send new connections only to healthy ones. - **UDP ports:** network services now accept UDP ports, and the create-service dialog has a TCP/UDP selector per port. A UDP listener also needs a TCP port on the backend for its health check. - **Portal:** create an NLB, copy its hostname and address, and add, edit, or delete listeners in the [Cloud Portal](https://cloud.datum.net). NLBs are early access. TLS listeners aren't supported yet, but a TCP listener forwards TLS traffic unchanged to your backend. Each route serves one backend. An ALB that points at a UDP port now reports a clear unsupported-protocol error. - See [Network services](/galactic-vpc/networks/network-services). + See [NLB](/nlb/overview). diff --git a/compute/compute-and-alb.mdx b/compute/compute-and-alb.mdx index 7cfd29e..527119b 100644 --- a/compute/compute-and-alb.mdx +++ b/compute/compute-and-alb.mdx @@ -150,3 +150,4 @@ In addition to the [limitations that apply to all of Compute](/compute/limitatio - To run in more locations so that more users reach a nearby Instance, see [Placement and scaling](/compute/placement-and-scaling). - To learn more about `HTTPProxy` routing and options, see [Application Load Balancer](/alb/overview). - To learn how Instances connect privately, see [Traffic and connecting](/galactic-vpc/networks/traffic). +- To publish a TCP or UDP port that isn't HTTP, such as a database or a game server, see [NLB operations](/nlb/operations). diff --git a/compute/limitations-and-roadmap.mdx b/compute/limitations-and-roadmap.mdx index b8f1ffa..f02ffd1 100644 --- a/compute/limitations-and-roadmap.mdx +++ b/compute/limitations-and-roadmap.mdx @@ -37,7 +37,7 @@ The Compute preview has the following limitations. For limitations of each [runt - 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. +- Public HTTP and HTTPS traffic reaches Instances through Datum's [ALB](/alb/overview). Public TCP and UDP traffic reaches them through a [Network Load Balancer](/nlb/overview), which is in early access, serves IPv6 only, and is available only in `us-central-1`, `us-east-1`, and `us-west-1`. For more information about networking, see [gVPC limitations and roadmap](/galactic-vpc/limitations-and-roadmap). To learn which networking capabilities Datum is working on, see [Planned capabilities](/galactic-vpc/limitations-and-roadmap#planned-capabilities). diff --git a/compute/overview.mdx b/compute/overview.mdx index 97f3971..6f42060 100644 --- a/compute/overview.mdx +++ b/compute/overview.mdx @@ -51,6 +51,7 @@ Each Instance reports its own status, and the workload summarizes the status of | Runtime class | The execution tier for a workload's Instances: `general-purpose` or `unikernel`. You choose it when you create the workload. | | Network | The private network your Instances attach to. `datumctl compute deploy` uses a network named `default`. | | ALB | Datum's [Application Load Balancer](/alb/overview), which serves public HTTP and HTTPS traffic to your workload's Instances. | +| NLB | Datum's [Network Load Balancer](/nlb/overview), which forwards public TCP and UDP traffic to your workload's Instances. | ## Runtime classes diff --git a/docs.json b/docs.json index b208b77..9dd5bbc 100644 --- a/docs.json +++ b/docs.json @@ -195,6 +195,27 @@ ], "expanded": false }, + { + "group": "NLB", + "pages": [ + "nlb/overview", + { + "group": "Concepts", + "root": "nlb/listeners-and-routes", + "pages": [ + "nlb/addresses-and-hostnames", + "nlb/health-checks", + "nlb/traffic-handling" + ] + }, + "nlb/operations", + "nlb/observability", + "nlb/troubleshooting", + "nlb/limits-and-quotas", + "nlb/limitations-and-roadmap" + ], + "expanded": false + }, { "group": "Connectors", "pages": [ @@ -217,6 +238,7 @@ "domain-dns/private-dns", "domain-dns/operations", "domain-dns/point-to-alb", + "domain-dns/point-to-nlb", "domain-dns/observability", "domain-dns/troubleshooting", "domain-dns/limits-and-quotas", diff --git a/domain-dns/point-to-nlb.mdx b/domain-dns/point-to-nlb.mdx new file mode 100644 index 0000000..6728225 --- /dev/null +++ b/domain-dns/point-to-nlb.mdx @@ -0,0 +1,65 @@ +--- +title: "Point a domain at an NLB" +description: "Use Datum DNS to give a Network Load Balancer a name on your own domain, with a CNAME to the generated hostname of one of its locations." +sidebarTitle: "Point to an NLB" +--- + +When Datum hosts your domain's DNS, you can give a [Network Load Balancer](/nlb/overview) (NLB) a name on your domain, such as `db.example.com`, with a `CNAME` record. Clients then connect to `db.example.com` on the listener's port. + +An NLB has a generated hostname for each location and each listener, such as `us-central-1.lively-otter-x7k2p.datumproxy.net`. A record on your domain points at one of them, so it sends clients to one location. See [Addresses and hostnames](/nlb/addresses-and-hostnames). + + + If your DNS is hosted somewhere else, you don't need anything on this page. Create a `CNAME` to the NLB's generated hostname at your own DNS provider. + + +Unlike an [Application Load Balancer](/alb/overview), an NLB doesn't need your domain added to it, and it doesn't issue a certificate for it. If clients use TLS, your workload must present a certificate for your domain. + +## Point a domain with datumctl dns + +To install the `dns` plugin, run `datumctl plugin install dns`. + + + + ```bash + datumctl get networkloadbalancer NLB_NAME \ + -o jsonpath='{range .status.endpoints[*]}{.location}{"\t"}{.requestName}{"\t"}{.canonicalHostname}{"\n"}{end}' + ``` + + Each line shows a location, an address request, and its hostname. Pick the hostname for the location and listener that you want. + + + ```bash + datumctl dns zone create example.com + ``` + + Then point your domain at Datum's nameservers. See [Point your domain at Datum](/domain-dns/operations#point-your-domain-at-datum). + + + ```bash + datumctl dns record set example.com db CNAME GENERATED_HOSTNAME. + ``` + + Replace `GENERATED_HOSTNAME` with the NLB's hostname, and keep the trailing dot. + + To use the apex, `example.com`, create an `ALIAS` record instead, because a `CNAME` isn't allowed at the apex. See [ALIAS](/domain-dns/dns#alias-/-cname-flattening). + + ```bash + datumctl dns record set example.com @ ALIAS GENERATED_HOSTNAME. + ``` + + + ```bash + datumctl dns record list example.com --type CNAME,ALIAS + dig +short AAAA db.example.com + ``` + + The record is live when its status is `Programmed`. `dig` returns the NLB's IPv6 address for that location. + + + +To create the same records with `DNSZone` and `DNSRecordSet` manifests, follow [Point a domain with manifests](/domain-dns/point-to-alb#point-a-domain-with-manifests), and use the NLB's hostname as `TARGET`. + +## What's next + +- To learn when a hostname starts serving, see [Generated hostnames](/nlb/addresses-and-hostnames#generated-hostnames). +- To check that the NLB is serving, see [Check that an NLB is serving](/nlb/operations#check-that-an-nlb-is-serving). diff --git a/galactic-vpc/limitations-and-roadmap.mdx b/galactic-vpc/limitations-and-roadmap.mdx index d0fd83c..5e83a74 100644 --- a/galactic-vpc/limitations-and-roadmap.mdx +++ b/galactic-vpc/limitations-and-roadmap.mdx @@ -13,7 +13,7 @@ description: "Review the limitations of gVPC networks and the networking capabil In addition to the [networking limitations that apply to all of Compute](/compute/limitations-and-roadmap#networking), networks have the following limitations: - Each workload attaches to exactly one network through one network interface, and it can't move to another network. -- Instance addresses aren't reachable from the internet. To serve traffic publicly, attach an [ALB](/alb/overview) to the workload. +- Instance addresses aren't reachable from the internet. To serve traffic publicly, attach an [ALB](/alb/overview) to the workload for HTTP and HTTPS, or an [NLB](/nlb/overview) for TCP and UDP. - 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`. @@ -42,4 +42,5 @@ For what Datum is building next across the platform, see the [Platform roadmap]( - To learn which traffic a network carries, see [Traffic and connecting](/galactic-vpc/networks/traffic). - To serve a workload publicly through Datum's ALB, see [Publish a workload](/compute/compute-and-alb). +- To publish a TCP or UDP port, see [NLB operations](/nlb/operations). - To run Instances in more locations, see [Placement and scaling](/compute/placement-and-scaling). diff --git a/galactic-vpc/networks/network-services.mdx b/galactic-vpc/networks/network-services.mdx index bfba75c..22342e7 100644 --- a/galactic-vpc/networks/network-services.mdx +++ b/galactic-vpc/networks/network-services.mdx @@ -4,7 +4,7 @@ sidebarTitle: "Network services" description: "Give a workload's Instances a stable name and named ports on a gVPC network, and send load balancer traffic to them." --- -A network service gives a workload's Instances on one network a stable name and named ports. Datum keeps the service's membership current as Instances start, stop, and move between locations, and sends each request to the nearest location that has a ready Instance. Datum's [Application Load Balancer](/alb/overview) reaches a workload through a network service. +A network service gives a workload's Instances on one network a stable name and named ports. Datum keeps the service's membership current as Instances start, stop, and move between locations, and sends each request to the nearest location that has a ready Instance. Datum's [Application Load Balancer](/alb/overview) and [Network Load Balancer](/nlb/overview) reach a workload through a network service. gVPC is in preview, and the `networking.datumapis.com/v1alpha` API can change. @@ -15,7 +15,7 @@ A network service gives a workload's Instances on one network a stable name and A network service is a `NetworkService` resource with two parts: - **A selector:** labels that an Instance's network interface must carry to belong to the service. Every Instance of a workload carries the workload's name as a label, so a service usually selects one workload. -- **Ports:** the ports the Instances listen on, each with a name, such as `http` on port `8080`. A load balancer refers to a port by its name, not its number. +- **Ports:** the ports the Instances listen on, each with a name, a number, and a protocol, `TCP` or `UDP`, such as `http` on TCP port `8080`. A load balancer refers to a port by its name, not its number. Keep the following points in mind: @@ -51,6 +51,8 @@ Replace the following: To add more ports, repeat `--port`. A service takes up to 16 ports, and each name and number must be unique. +`datumctl network service create` creates TCP ports only. To add a UDP port, use the Cloud Portal or a manifest. See [Add UDP ports](#add-udp-ports). + By default, a load balancer connects to a port over HTTP/1.1. For a port that serves gRPC or another HTTP/2 app without TLS (h2c), use the long form of `--port` with `app-protocol=h2c`, such as `--port=name=grpc,port=9090,app-protocol=h2c`. The load balancer then sends every request on that port as HTTP/2. Most servers accept WebSockets only over HTTP/1.1, so serve WebSockets on a different port. To select Instances by label instead of by workload, use `--selector`, such as `--selector app=web`. The labels must be on the Instances' network interfaces, not only on the workload. @@ -67,6 +69,37 @@ datumctl alb create LOAD_BALANCER_NAME \ For more information, see [Create a load balancer](/alb/operations/overview#create-a-load-balancer). +To publish a port on a public TCP or UDP port, send a [Network Load Balancer](/nlb/overview)'s traffic to it with a route instead. A route names the service and one of its port names, and the port's protocol must match the NLB listener's. See [Listeners and routes](/nlb/listeners-and-routes). + +## Add UDP ports + +To give a service a UDP port, such as for an NLB, describe the service in a manifest and set `protocol` on each port. The following service has a UDP port for a game server, and a TCP port for the NLB's health check: + +```yaml game-service.yaml +apiVersion: networking.datumapis.com/v1alpha +kind: NetworkService +metadata: + name: game +spec: + networkInterfaces: + selector: + matchLabels: + compute.datumapis.com/workload-name: game + ports: + - name: game + port: 7777 + protocol: UDP + - name: health + port: 8080 + protocol: TCP +``` + +The `compute.datumapis.com/workload-name` label selects every Instance of the named workload. To create the service, run `datumctl apply -f game-service.yaml`. + +In the [Cloud Portal](https://cloud.datum.net), the create-service dialog has a **TCP** or **UDP** choice for each port. + +An ALB can't send traffic to a UDP port. + ## Check a network service To see what a service selects, its ports, and where it's serving, run the following command: @@ -109,8 +142,11 @@ datumctl network service delete SERVICE_NAME Before it asks you to confirm, the command lists the load balancers that send traffic to the service. Those load balancers stop reaching anything on that route. +Deleting a network service with `datumctl delete networkservice` doesn't check for NLB routes. An NLB whose route uses the service stops serving, and the route reports `BackendNotFound`. See [Delete an NLB](/nlb/operations#delete-an-nlb). + ## What's next - To manage networks and Instances' network interfaces from the command line, see [Operations](/galactic-vpc/operations). - To publish a workload with a load balancer in one step, see [Compute and ALB](/compute/compute-and-alb). +- To publish a TCP or UDP port, see [NLB operations](/nlb/operations). - To learn how Instances connect privately, see [Traffic and connecting](/galactic-vpc/networks/traffic). diff --git a/galactic-vpc/networks/overview.mdx b/galactic-vpc/networks/overview.mdx index 29d4f91..1f4cdc8 100644 --- a/galactic-vpc/networks/overview.mdx +++ b/galactic-vpc/networks/overview.mdx @@ -19,7 +19,7 @@ A network belongs to a project, not to a location. The following list describes - **Many workloads on one network:** Several workloads can name the same network. For example, a frontend workload and a backend workload can share a network. - **Addresses are private IPv6:** Each network gets its own private IPv6 prefix from the unique local address range. Each Instance gets an address from that prefix. The addresses aren't reachable from the internet. For more information, see [Addressing](/galactic-vpc/networks/addressing). - **Networks are isolated:** Each network is separate from every other network, including other networks in the same project and other customers' networks. -- **Public traffic arrives through Datum's ALB:** To serve a workload on the internet, attach Datum's [Application Load Balancer](/alb/overview) to it. The ALB reaches a workload through a [network service](/galactic-vpc/networks/network-services), which gives the workload's Instances a stable name and named ports, and forwards each request to an Instance over the private network. For more information, see [Compute and ALB](/compute/compute-and-alb). +- **Public traffic arrives through a load balancer:** To serve a workload on the internet, attach Datum's [Application Load Balancer](/alb/overview) to it for HTTP and HTTPS, or a [Network Load Balancer](/nlb/overview) for raw TCP and UDP. The ALB reaches a workload through a [network service](/galactic-vpc/networks/network-services), which gives the workload's Instances a stable name and named ports, and forwards each request to an Instance over the private network. For more information, see [Compute and ALB](/compute/compute-and-alb). ## The default network diff --git a/galactic-vpc/networks/traffic.mdx b/galactic-vpc/networks/traffic.mdx index d436ee9..39ef92d 100644 --- a/galactic-vpc/networks/traffic.mdx +++ b/galactic-vpc/networks/traffic.mdx @@ -19,7 +19,7 @@ The following table describes which kinds of traffic are possible: | Between Instances on the same network in different locations | Yes | A network spans locations, and Instances can connect to each other privately across locations using their private IPv6 addresses. | | 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. | +| Inbound from the internet | Through a load balancer | Instance addresses aren't reachable from the internet directly. Public HTTP and HTTPS traffic reaches Instances through Datum's [Application Load Balancer](/alb/overview). Public TCP and UDP traffic reaches them through a [Network Load Balancer](/nlb/overview), over IPv6. | | 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). | diff --git a/galactic-vpc/operations.mdx b/galactic-vpc/operations.mdx index ad3097f..fb863c7 100644 --- a/galactic-vpc/operations.mdx +++ b/galactic-vpc/operations.mdx @@ -64,7 +64,7 @@ If Instances still hold addresses on the network, the network stays in deletion ## Manage network services -The `datumctl network service` commands create, describe, change, and delete network services. For more information, see [Network services](/galactic-vpc/networks/network-services). +The `datumctl network service` commands create, describe, change, and delete network services. They create TCP ports only. For UDP ports, which a [Network Load Balancer](/nlb/overview) can publish, use a manifest. For more information, see [Network services](/galactic-vpc/networks/network-services). ```bash datumctl network service create api --workload=api --port=http:8080 diff --git a/galactic-vpc/overview.mdx b/galactic-vpc/overview.mdx index 9f614a9..b9b50a7 100644 --- a/galactic-vpc/overview.mdx +++ b/galactic-vpc/overview.mdx @@ -33,7 +33,7 @@ gVPC provides the following features: - **One network across locations:** A network is a single project-wide resource. Every workload that names it, in any location, attaches to the same network, and each Instance gets a private IPv6 address on it. - **Automatic addressing:** Datum assigns address space to each network and an address to each Instance. You don't plan subnets. - **Stable addresses when you need them:** Instances keep their addresses when Datum replaces them, and a workload can keep addresses reserved when it scales down. -- **Network services:** A [network service](/galactic-vpc/networks/network-services) gives a workload's Instances a stable name and named ports, so a load balancer can send traffic to them. +- **Network services:** A [network service](/galactic-vpc/networks/network-services) gives a workload's Instances a stable name and named ports, so an [Application Load Balancer](/alb/overview) or a [Network Load Balancer](/nlb/overview) can send traffic to them. - **Declarative:** Networks are Kubernetes-style resources that you manage with the [`datumctl network` plugin](/galactic-vpc/operations), manifests, or GitOps tooling. To learn what Datum is working on next, see [Planned capabilities](/galactic-vpc/limitations-and-roadmap#planned-capabilities). diff --git a/guides/overview.mdx b/guides/overview.mdx index ed078fc..e4ecd4c 100644 --- a/guides/overview.mdx +++ b/guides/overview.mdx @@ -17,5 +17,6 @@ description: "Step-by-step guides for common Datum tasks: replace your web serve - [Serve traffic on your own domain](/alb/operations/custom-domains) with an Application Load Balancer. - [Require sign-in](/alb/authentication/overview) before requests reach your app. - [Point a domain at a load balancer](/domain-dns/point-to-alb) with Datum DNS. +- [Point a domain at an NLB](/domain-dns/point-to-nlb) with Datum DNS. Have a guide you'd like to see? Suggest it in [GitHub discussions](https://github.com/orgs/datum-cloud/discussions/categories/feature-requests). diff --git a/index.mdx b/index.mdx index a1cf034..91d5829 100644 --- a/index.mdx +++ b/index.mdx @@ -4,7 +4,7 @@ sidebarTitle: "Overview" description: "Datum is a modern edge cloud, backed by open source, focused on the builders and service providers of the AI era." --- -Datum is an edge cloud where you can run containers close to your users, publish them behind a load balancer with HTTPS, connect your existing services through secure tunnels, and host DNS for your domains. +Datum is an edge cloud where you can run containers close to your users, publish them behind a load balancer with HTTPS or on raw TCP and UDP ports, connect your existing services through secure tunnels, and host DNS for your domains. - We are 100% focused on builders and modern, "alt cloud" service providers. - Our code is open source (AGPLv3), so you can run it anywhere if needed. @@ -38,6 +38,9 @@ Datum is still being built. The product is evolving quickly, documentation is gr Intelligent edge proxies and routing purpose-built for AI workloads and agent traffic. + + Publish TCP and UDP services, such as databases and game servers, on public ports. + Secure tunnels to bridge your existing infrastructure into Datum's edge cloud. diff --git a/nlb/addresses-and-hostnames.mdx b/nlb/addresses-and-hostnames.mdx new file mode 100644 index 0000000..68b72fa --- /dev/null +++ b/nlb/addresses-and-hostnames.mdx @@ -0,0 +1,130 @@ +--- +title: "Addresses and hostnames" +sidebarTitle: "Addresses and hostnames" +description: "Which public IPv6 addresses and generated hostnames an NLB gets in each location, how to choose its locations, and how to point your own domain at it." +--- + +An NLB requests public addresses in `spec.exposure.addresses`. Datum allocates each address request an IPv6 address and a generated hostname in every location where it serves, and reports them in the NLB's status. + + + NLBs are in early access. They serve public IPv6 addresses only, in `us-central-1` (Dallas), `us-east-1` (Ashburn), and `us-west-1` (San Jose). IPv4 isn't available yet. + + +## Address requests + +An address request is an entry in `spec.exposure.addresses`, and listeners refer to it by name in `addressRefs`: + +```yaml +spec: + exposure: + addresses: + - name: tcp-5432 + families: ["IPv6"] + listeners: + - name: tcp-5432 + protocol: TCP + port: 5432 + addressRefs: ["tcp-5432"] +``` + +| Field | Description | +| --- | --- | +| `name` | Required. A name for the address request, up to 63 lowercase letters, numbers, and hyphens. | +| `families` | Required. `["IPv6"]`. Early access refuses `IPv4`. | +| `locations` | Optional. Which locations get an address. See [Choose locations](#choose-locations). | + +In early access, each listener needs its own address request, and two listeners can't share one. So an NLB with a TCP listener and a UDP listener has two IPv6 addresses and two hostnames in each location, one for each listener. An NLB takes up to 16 address requests. + +## Choose locations + +By default, an address request gets an address in each location where the backend's Instances run. If you add the workload to another supported location, the NLB gets an address there too, and the addresses in the other locations don't change. + +To choose locations yourself, set `locations`: + +```yaml +addresses: + - name: tcp-5432 + families: ["IPv6"] + locations: + from: Names + names: ["us-east-1", "us-west-1"] +``` + +| `from` | Locations | +| --- | --- | +| `Backends` | Each location where the backend's Instances run. This is the default. | +| `All` | Every location where NLBs are available. | +| `Names` | The locations in `names`. | + +An address only serves traffic in a location where the backend has a healthy Instance, because traffic to a location's address goes only to Instances in that location. A location with an address and no Instances has nothing to send traffic to. + +With the default, an address request gets an address only once a route attaches to its listener and the route's network service has Instances. Until then, the NLB reports `AllocationPending`. + +NLB addresses are available in `us-central-1`, `us-east-1`, and `us-west-1`, the locations where Compute runs. `datumctl apply` accepts other location names in `names`, and the NLB then reports `AllocationPending` with the message `no pool offers this class`. + +## Find the addresses and hostnames + +Each entry in the NLB's `status.endpoints` describes one address request in one location: + +```bash +datumctl get networkloadbalancer NLB_NAME -o yaml +``` + +```yaml +status: + endpoints: + - requestName: tcp-5432 + location: us-central-1 + canonicalHostname: us-central-1.lively-otter-x7k2p.datumproxy.net + addresses: + - family: IPv6 + value: 2001:db8:10c:1000::5 + announced: true + dnsPublished: true +``` + +| Field | Description | +| --- | --- | +| `requestName` | The address request. | +| `location` | The location. | +| `canonicalHostname` | The generated hostname for this address request in this location. | +| `addresses[].value` | The public IPv6 address. | +| `addresses[].announced` | `true` while Datum announces the address to the internet. While the location has no healthy Instance, Datum stops announcing the address, and the field is missing. | +| `addresses[].dnsPublished` | `true` once Datum has published the hostname's DNS record. | + +To list only the hostnames, run the following command: + +```bash +datumctl get networkloadbalancer NLB_NAME \ + -o jsonpath='{range .status.endpoints[*]}{.location}{"\t"}{.requestName}{"\t"}{.canonicalHostname}{"\n"}{end}' +``` + +In the [Cloud Portal](https://cloud.datum.net), the NLB's page lists the same addresses and hostnames, with a copy button for each. + +## Generated hostnames + +A generated hostname has the form `.