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 4ed53c6..b04a276 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 4c0c1b5..0fcd883 100644 --- a/changelog.mdx +++ b/changelog.mdx @@ -202,7 +202,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). Details: [Give the NLB page a traffic path layout](https://github.com/datum-cloud/network-services-operator/pull/890) (#890) @@ -349,14 +349,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). Details: [Add network load balancers to the portal](https://github.com/datum-cloud/network-services-operator/pull/812) (#812) 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 c0f0c24..022e7f0 100644 --- a/compute/limitations-and-roadmap.mdx +++ b/compute/limitations-and-roadmap.mdx @@ -36,7 +36,7 @@ The Compute preview has the following limitations. For limitations of each [runt - 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. - 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 e402332..9a94ca6 100644 --- a/docs.json +++ b/docs.json @@ -194,6 +194,21 @@ ], "expanded": false }, + { + "group": "NLB", + "pages": [ + "nlb/overview", + "nlb/configuration", + "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": [ diff --git a/domain-dns/operations.mdx b/domain-dns/operations.mdx index 36b05b6..25a29da 100644 --- a/domain-dns/operations.mdx +++ b/domain-dns/operations.mdx @@ -114,7 +114,7 @@ Two rules catch most mistakes: - **Names are relative.** Use `www`, not `www.example.com`. Use `@` for the domain itself. - **Targets are absolute.** End every hostname inside a value with a dot: `mail.example.com.`, not `mail`. -For the record types Datum supports, see [Authoritative DNS](/domain-dns/dns). To point a name at a load balancer, see [Point a domain at a load balancer](/domain-dns/point-to-alb). +For the record types Datum supports, see [Authoritative DNS](/domain-dns/dns). To point a name at an Application Load Balancer, see [Point a domain at a load balancer](/domain-dns/point-to-alb). For a Network Load Balancer, see [Use your own domain](/nlb/configuration#use-your-own-domain). ### Set a TTL diff --git a/galactic-vpc/limitations-and-roadmap.mdx b/galactic-vpc/limitations-and-roadmap.mdx index 7e65830..886167e 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`. @@ -40,4 +40,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..afa4dbd 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 [Routes](/nlb/configuration#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 0b31e5a..9b1b3f1 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 | Yes | Instances resolve public names, and the [Private DNS](/domain-dns/private-dns) names of other Instances on the same network, such as `web-default-us-central-1-0.instances.datum.internal`. | | 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..89235ff 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](/nlb/configuration#use-your-own-domain) 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/configuration.mdx b/nlb/configuration.mdx new file mode 100644 index 0000000..13dd6d7 --- /dev/null +++ b/nlb/configuration.mdx @@ -0,0 +1,315 @@ +--- +title: "Configure an NLB" +sidebarTitle: "Configuration" +description: "Set up an NLB's listeners, routes, and address requests, choose its locations, find its generated hostnames, use your own domain, and change listeners on a running NLB." +--- + +An NLB accepts traffic on **listeners**, sends it to backends through **routes**, and gets its public IPv6 addresses and generated hostnames from **address requests**. This page covers each, and how to change them on a running NLB. To create your first NLB, see [Operations](/nlb/operations). + + + NLBs are in early access, and the `networking.datumapis.com/v1alpha` API can change. See [Limitations and roadmap](/nlb/limitations-and-roadmap). + + +## A complete example + +The following manifest publishes a Postgres workload on public TCP port `5432`. It has one NLB with one listener, and one route that sends the listener's traffic to the `postgres` port of a network service named `db`: + +```yaml db-nlb.yaml +apiVersion: networking.datumapis.com/v1alpha +kind: NetworkLoadBalancer +metadata: + name: db-nlb +spec: + networkRef: + name: default # the gVPC network of your Instances + exposure: + addresses: + - name: tcp-5432 # an address request: an IPv6 address and hostname in each location + families: ["IPv6"] + listeners: + - name: tcp-5432 + protocol: TCP # TCP or UDP + port: 5432 # the public port that clients connect to + addressRefs: ["tcp-5432"] +--- +apiVersion: networking.datumapis.com/v1alpha +kind: NetworkLoadBalancerRoute +metadata: + name: db-nlb-tcp-5432 +spec: + parentRefs: + - name: db-nlb + listener: tcp-5432 # the listener that this route serves + backends: + - networkService: + name: db # selects your workload's Instances + port: postgres # the name of a port on the network service, not its number + healthCheck: + protocol: TCP +``` + +The rest of this page covers each part. For a walkthrough that also creates the backend, see [Operations](/nlb/operations). + +## Listeners + +A listener is an entry in the NLB's `spec.listeners`. It accepts one protocol on one public port. + +| Field | Description | +| --- | --- | +| `name` | Required. The name that routes use to attach to this listener. Unique within the NLB. | +| `protocol` | Required. `TCP` or `UDP`. | +| `port` | The public port, from `1` to `65535`. | +| `addressRefs` | Required. The address request whose addresses this listener serves on. In early access, list exactly one, and give every listener its own address request. See [Address requests](#address-requests). | + +An NLB takes up to 16 listeners. The [Cloud Portal](https://cloud.datum.net) names each listener and its address request after its protocol and port, such as `tcp-5432` or `udp-7777`, and the manifests in these docs follow the same pattern. + +The API also has `portRange`, `hostname`, and `tls` fields, and a `TLS` protocol. Early access refuses them. See [Limitations and roadmap](/nlb/limitations-and-roadmap). + +### Address requests + +An address request is an entry in `spec.exposure.addresses`. Datum gives it a public IPv6 address and a generated hostname in each location, and a listener refers to it by name in `addressRefs`. + +| 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. + +### TLS traffic + +A `TCP` listener forwards TLS traffic unchanged. Your workload keeps its own certificate and completes the TLS handshake with the client, and Datum never sees the decrypted traffic. Datum doesn't issue certificates for NLB hostnames, so get a certificate for a domain that you own and point that domain at the NLB. See [Use your own domain](#use-your-own-domain). + +## Routes + +A route is a separate `NetworkLoadBalancerRoute` resource. It attaches to a listener and names the backend, as in the [example](#a-complete-example). + +| Field | Description | +| --- | --- | +| `parentRefs[].name` | Required. The NLB's name. The NLB must be in the same project. | +| `parentRefs[].listener` | The listener's name. Set either `listener` or `port`. | +| `parentRefs[].port` | The listener's port, instead of its name. | +| `backends[].networkService.name` | Required. The network service that selects your Instances. | +| `backends[].networkService.port` | Required. The **name** of a port on the network service, such as `postgres`, not its number. | +| `backends[].healthCheck` | How Datum checks each Instance. Required for a UDP listener. See [Health checks](/nlb/health-checks). | + +Keep the following points in mind: + +- **One backend for each route.** In early access, `backends` takes exactly one entry. To spread traffic across Instances, scale the workload behind the network service instead. +- **The protocols must match.** The network service port's protocol must match the listener's protocol: a `TCP` port for a `TCP` listener, and a `UDP` port for a `UDP` listener. A mismatch reports `ProtocolMismatch`. +- **The network must match.** The network service must select Instances on the NLB's network. Otherwise, the route reports `NetworkMismatch`. +- **Create in any order.** You can create the route before its NLB or network service exists. It reports what it's waiting for, and starts serving when everything it refers to exists. An NLB doesn't get an address until a route with running Instances attaches to its listener. +- **Deleting doesn't check routes.** You can delete an NLB or a network service that a route still uses. The route then reports `ParentNotFound` or `BackendNotFound`, and still counts toward your route quota. See [Delete an NLB](/nlb/operations#delete-an-nlb). + +The Cloud Portal names the route `-`, such as `db-nlb-tcp-5432`. + +### Port mapping + +The listener's `port` is the port clients connect to. The network service port is the port your app listens on. They don't have to be the same. For example, a listener on port `5432` can send traffic to a network service port named `postgres` with the number `15432`. Clients connect to `5432`, and your app sees connections arrive on `15432`. + +### One route for each listener + +A listener serves one route at a time. If two routes attach to the same listener, the older route keeps the listener, even if it's broken, and the newer route reports `Superseded` until the older one is deleted. Each route's `status.parents[].effective` field shows whether it owns the listener. + +A network service port can be the backend of only one route. A second route, on this NLB or another one, that sends traffic to the same network service port reports `BackendClaimConflict`, and its listener doesn't serve. To put the same app behind two listeners or two NLBs, make it listen on a second port, and add that port to the network service under its own name. A port can still be the health check port of other routes. + +## The network + +An NLB serves one [gVPC network](/galactic-vpc/networks/overview), set in `spec.networkRef.name`, usually `default`. You can't change the network after you create the NLB. The network must carry IPv6. Instances' IPv6 addresses are how Datum reaches them. + +## 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 +``` + +For what each field means, see [Addresses in each location](/nlb/observability#addresses-in-each-location). + +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 `.