Review of global-server-load-balancing/README.md on branch gslb-design,
cross-checked against issue #833 and the working context doc.
The context doc (section 8) records an architectural position: "Both PoP selection and origin selection consult capacity, per the GCLB model." The design doc says anycast selects the PoP and GSLB selects the origin. But it never addresses what happens when the PoP itself is the wrong tier — if a client lands at Frankfurt via anycast but Frankfurt's origins are full, the assembler sends traffic to an origin in another PoP over the backbone. That is fine, but the doc never discusses the cost of that backbone hop or whether the assembler should bias against cross-PoP origins relative to local ones. Envoy's priority levels can express this, but the doc does not say it will. This is the gap between "anycast picks the PoP" and "the assembler picks the origin" — the implicit assumption is that cross-PoP is always acceptable, but that has latency and bandwidth cost implications worth stating.
2. ORCA is described as both the origin-to-Envoy channel and as something the assembler consumes, but the data flow has a missing link
The fast-path section says "ORCA from origins into Envoy, LRS from Envoy to the
assembler." ORCA reports arrive at the local Envoy as response trailers or
out-of-band streams. LRS aggregates Envoy's observed load stats back to the
control plane. But the doc never explains how origin-reported ORCA metrics (like
application_utilization or named_metrics["queue_depth"]) reach the
assembler. LRS reports Envoy's own observations (request count, error count,
latency per locality). If the assembler needs the origin's self-reported
capacity, something has to relay those ORCA values upstream — either Envoy
forwards them in LRS (it does not by default), or the assembler subscribes to
ORCA directly from origins. The doc implies the first but does not confirm it.
The context doc flags this: "neither hyperscaler does rich capacity-aware global routing for arbitrary L4. Scoping v1 to HTTP-ish is the normal call." The design doc never says whether this covers HTTP only, or also TCP/UDP passthrough. This matters because ORCA is HTTP-native (response trailers or gRPC streams), and health checking semantics differ for L4. The graduation criteria say "single origin type" at alpha but never name the protocol. Worth one sentence.
The doc describes draining as an operator action (the PoP incident story, the datumctl interface) but never says what happens to existing connections when an origin is drained or removed from EDS. Envoy supports graceful connection draining, but the assembler's EDS push cadence and the drain timing interact — a fast EDS push that removes an endpoint will reset in-flight connections unless drain duration is coordinated. Issue #833 explicitly calls out "drain or reduce an origin's share of traffic without deleting it," which implies graceful behavior, but the design does not describe it.
Troubleshooting says "Eligibility flapping — mitigated by damping in the assembler." The assembler is where the flap would occur, but the doc never describes the damping mechanism. This is the difference between "we know we need it" and "here is how it works." An UNRESOLVED marker would be appropriate if the mechanism is not decided.
There is an UNRESOLVED for SLOs, which is fine. But the doc could state an order of magnitude — "seconds, not minutes" — without overcommitting. Right now a reader cannot tell whether a 5-second stale reading is a problem or a 5-minute one.
The PoP incident story drains entirely; the rollout story derates to a percentage. Neither covers "keep this degraded location in rotation but cap it at N% of traffic." That is a distinct operator control — a ceiling rather than a target.
Issue #833 requires "see where traffic is arriving from and which origin each client population is being sent to." The design's Interfaces section covers per-origin status (receiving/not, why not) but not the reverse: which clients are going where. That is an observability gap the issue explicitly asks for.
The doc says fail-open, which is correct, but the context doc notes a subtlety: "a partitioned PoP then keeps feeding a saturated origin." The doc does not address this case — a PoP that cannot see the assembler sends traffic based on stale state, which may include an origin that has since saturated. The staleness metric helps detect it, but the doc does not say what the remediation is beyond "alert."
That project is still in SIG-Network incubation. Worth a note that it is a reference for the pattern rather than a dependency.
The old design (gslb-jamie-tartt.md) is deleted. The roadmap and
total-load-balancing annotations are correctly marked as stale-until-revised. No
dangling references to the old doc.