docs: Describe the gateway as a direct-return load balancer

README.md

@@ -10,7 +10,7 @@ Modern organizations run workloads everywhere: AWS, Azure, GCP, on-premises, and
 
 ## Our Approach
 
-Galactic provides the SRv6 data plane that makes multi-cloud VPC connectivity work at the kernel level. It runs as a DaemonSet agent on every node, managing SRv6 routes and VRF isolation, and as a CNI plugin that attaches pods to the correct virtual network. On nodes dedicated to the gateway role, a third component loads an edge XDP NAT+LB datapath to handle ingress load balancing at the VPC boundary. VPC and VPCAttachment definitions are managed by a companion operator; Galactic acts on the identifiers that operator assigns.
+Galactic provides the SRv6 data plane that makes multi-cloud VPC connectivity work at the kernel level. It runs as a DaemonSet agent on every node, managing SRv6 routes and VRF isolation, and as a CNI plugin that attaches pods to the correct virtual network. On nodes dedicated to the gateway role, a third component loads an edge XDP DSR (Direct Server Return) load balancer to handle L4 ingress at the VPC boundary. VPC and VPCAttachment definitions are managed by a companion operator; Galactic acts on the identifiers that operator assigns.
 
 Under the hood, Galactic uses Segment Routing over IPv6 (SRv6) for efficient, deterministic routing and Virtual Routing and Forwarding (VRF) for true network isolation at the kernel level. BGP is used to distribute SRv6 routes between agents across nodes and clusters.
 
@@ -43,7 +43,7 @@ Each component can also be applied on its own, e.g. `kubectl apply -k config/gal
 Two components are **not** part of `kubectl apply -k config/` and must be applied separately, each with its own per-node prerequisite:
 
 - **`config/fabric-router/`** — the FRR underlay eBGP DaemonSet `galactic-router` depends on.
-- **`config/galactic-gateway/`** — the edge XDP NAT+LB gateway control plane, a single-container `galactic-gateway` DaemonSet on dedicated `galactic.datumapis.com/node: edge` nodes (`galactic-router` runs there too, but as its own independent DaemonSet via `galactic.datumapis.com/galactic: router` — see `config/galactic-router/` above, not bundled into this pod). `kubectl apply -k config/galactic-gateway/` only installs the shared, cluster-safe ServiceAccount/RBAC; `config/galactic-gateway/base/` itself is a template meant to be instantiated once per gateway node by a further overlay (see `deploy/containerlab/resources/galactic-gateway/` as of commit `abdd665b`, the last before the containerlab lab stopped deploying the gateway, for a worked example) — apply that overlay per node instead of `base/` directly.
+- **`config/galactic-gateway/`** — the edge XDP DSR load-balancer control plane, a single-container `galactic-gateway` DaemonSet on nodes labeled both `galactic.datumapis.com/node: edge` and `galactic.datumapis.com/gateway: enabled` (`galactic-router` runs there too, but as its own independent DaemonSet via `galactic.datumapis.com/galactic: router` — see `config/galactic-router/` above, not bundled into this pod). `kubectl apply -k config/galactic-gateway/` only installs the shared, cluster-safe ServiceAccount/RBAC; `config/galactic-gateway/base/` itself is a template meant to be instantiated once per gateway node by a further overlay (see `deploy/containerlab/resources/galactic-gateway/` as of commit `abdd665b`, the last before the containerlab lab stopped deploying the gateway, for a worked example) — apply that overlay per node instead of `base/` directly.
 
 ```bash
 kubectl apply -k config/fabric-router/

cmd/galactic-gateway/root.go

@@ -34,7 +34,7 @@ import (
 const (
 	appName = "galactic-gateway"
 
-	appDesc = `Galactic edge XDP NAT+LB gateway
+	appDesc = `Galactic edge XDP DSR load balancer
 
  Find more information at: https://www.datum.net/docs`
 )
@@ -248,7 +248,7 @@ func newRootCommand() *cobra.Command {
 		config.DefaultGatewayGRPCHealthPort,
 		"gRPC health check port")
 	cmd.Flags().StringP("gateway-public-interface", "", "",
-		"Public/underlay-facing uplink interface for the edge NAT+LB gateway datapath (required)")
+		"Public/underlay-facing uplink interface for the edge DSR load-balancer datapath (required)")
 	cmd.Flags().StringP("gateway-internal-interfaces", "", "",
 		"Comma-separated compute-facing interfaces whose VIP-sourced return traffic this node "+
 			"forwards before netfilter (optional; empty means this node carries no return traffic)")

config/galactic-gateway/base/daemonset.yaml

@@ -150,14 +150,15 @@ spec:
             periodSeconds: 10
           # This container needs CAP_BPF for the bpf() syscalls themselves
           # (program/map creation) on top of NET_ADMIN for the netlink XDP
-          # attach — the same pair config/galactic-cni/daemonset.yaml's eBPF-loading
-          # container already uses for its own (TC-BPF) program. PERFMON is
-          # additionally required: the verifier only allows pointer+scalar
-          # arithmetic on packet data/data_end (edgenat.c's DNAT/SNAT
-          # header rewrites) when the loading process is perfmon_capable()
-          # — without it the verifier falls back to its unprivileged-BPF
-          # ruleset and rejects the program with "pointer arithmetic ...
-          # prohibited for !root" even though the container runs as root.
+          # attach — the same pair config/galactic-cni/daemonset.yaml's
+          # eBPF-loading container already uses for its own (TC-BPF) program.
+          # PERFMON is additionally required: the verifier only allows
+          # pointer+scalar arithmetic on packet data/data_end (edgedsr.c's
+          # header parsing and its data_end - data byte count) when the
+          # loading process is perfmon_capable(). Without it the verifier
+          # falls back to its unprivileged-BPF ruleset and rejects the program
+          # with "pointer arithmetic ... prohibited for !root" even though the
+          # container runs as root.
           securityContext:
             runAsUser: 0
             capabilities:
@@ -175,7 +176,7 @@ spec:
             limits:
               memory: 256Mi
           volumeMounts:
-            # edgeattach.PinDir pins every edgenat map under
+            # edgeattach.PinDir pins every edge map under
             # /sys/fs/bpf/galactic-edge, same convention config/galactic-cni/
             # daemonset.yaml's bpf-fs mount documents: bpffs must already be
             # mounted at this host path by the node itself (type: Directory,

config/galactic-gateway/kustomization.yaml

@@ -1,4 +1,4 @@
-# The edge XDP NAT+LB gateway control plane. Unlike config/galactic-router/'s
+# The edge XDP DSR load-balancer control plane. Unlike config/galactic-router/'s
 # equivalent kustomization.yaml, this deliberately does NOT include base/:
 # base/daemonset.yaml's galactic-gateway container has no generic default
 # for GALACTIC_GATEWAY_PUBLIC_INTERFACE/_SRV6_ADDRESS (both required —

config/galactic-gateway/rbac.yaml

@@ -1,4 +1,4 @@
-# The edge XDP NAT+LB gateway control plane's own RBAC. This ClusterRole
+# The edge XDP DSR load-balancer control plane's own RBAC. This ClusterRole
 # covers only what NetworkGatewayReconciler/NetworkRuleReconciler
 # (internal/controller/networkgateway_controller.go,
 # internal/controller/networkrule_controller.go) actually touch.

containers/galactic-gateway/Dockerfile

@@ -39,7 +39,7 @@ COPY cmd/ cmd/
 COPY internal/ internal/
 
 # galactic-gateway transitively imports both internal/plumbing/ebpf/edgeprog
-# (the edge NAT+LB XDP program it loads directly) and, via
+# (the edge DSR load-balancer XDP program it loads directly) and, via
 # internal/plumbing/ebpf/edgepreflight, internal/plumbing/ebpf/prog (the
 # SRv6 uSID TC-BPF program) -- neither package's bpf2go output
 # (*_bpfel.go/.o, *_bpfeb.go/.o) is committed to git (see each package's

containers/galactic-nat/Dockerfile

@@ -48,7 +48,7 @@ COPY internal/ internal/
 #                   via internal/plumbing/ebpf/natattach.
 #   - prog       -- the SRv6 uSID TC-BPF program, via
 #                   internal/plumbing/ebpf/attach and .../usidmap.
-#   - edgeprog   -- the edge NAT+LB DSR XDP program, via internal/gateway
+#   - edgeprog   -- the edge DSR load-balancer XDP program, via internal/gateway
 #                   and internal/controller -> .../edgemap. galactic-nat
 #                   never loads it, but shares those packages with
 #                   galactic-gateway, so it links against the bindings.

docs/README.md

@@ -16,7 +16,7 @@ data flow, module reference, known constraints):
 - [agents/ARCHITECTURE-ROUTER.md](agents/ARCHITECTURE-ROUTER.md) — the
   BGP/EVPN control plane (`galactic-router`, embedded GoBGP, GC).
 - [agents/ARCHITECTURE-GATEWAY.md](agents/ARCHITECTURE-GATEWAY.md) — the edge
-  XDP DSR NAT+LB gateway (`galactic-gateway`, `NetworkGateway`/`NetworkRule`).
+  XDP DSR load balancer (`galactic-gateway`, `NetworkGateway`/`NetworkRule`).
 - [agents/ARCHITECTURE.md](agents/ARCHITECTURE.md) — superseded by the three
   documents above; kept only as a redirect for old links.
 - [agents/CONVENTIONS.md](agents/CONVENTIONS.md) — Go naming, error

docs/agents/ARCHITECTURE-CNI.md

@@ -10,7 +10,7 @@ _Last updated: 2026-09-09_
 This document covers the CNI side of Galactic only. See
 [ARCHITECTURE-ROUTER.md](ARCHITECTURE-ROUTER.md) for the BGP/EVPN control
 plane (`galactic-router`) and [ARCHITECTURE-GATEWAY.md](ARCHITECTURE-GATEWAY.md)
-for the edge XDP NAT+LB gateway (`galactic-gateway`). This file, together
+for the edge XDP DSR load balancer (`galactic-gateway`). This file, together
 with those two, supersedes the former monolithic `ARCHITECTURE.md` — see
 [AGENTS.md](../../AGENTS.md) for which document to start from for a given
 task.