docs(adr): add ADR 025 for the Orbit Gateway

What does this MR do and why?

Proposes ADR 025: the Orbit Gateway, an Orbit-owned Envoy proxy in front of the Orbit web servers in every deployment. In this first stage it forwards every request unchanged. It gives Orbit its own routing point, so canary pools, cache affinity, and direct client access no longer need monolith changes, and it balances each query across web servers instead of each connection. Authentication and redaction stay in GitLab.

Relates to #1277, #1278, #1498. Prerequisite: #1505.

Review requested from @michaelangeloio and @dgruzd, since this builds on ADR 022.

Testing

mise run lint:docs passes locally (Vale and link checks).

Performance Analysis

Docs only. The proposed design adds one network hop per query; the ADR commits to measuring it against the ADR 022 latency numbers before cutover.

  • This merge request does not introduce any performance regression. If a performance regression is expected, explain why.
Agent context: long-form analysis, file-by-file walkthroughs, profiler output, alternatives considered

Scope after review. The first version routed requests on token claims to canary pools. Review split it: this ADR only adds the Gateway and forwards every request. Canary pools get their own ADR (draft not yet opened). Moving authentication and redaction out of Rails is #1498.

Decisions from review:

  • Name: Orbit Gateway, part of the Orbit Helm chart for GitLab.com, Self-Managed, and Dedicated. A chart minor release makes it optional; the next major release requires a proxy in front of the web servers: the chart's Envoy by default, or the administrator's own proxy if it meets the requirements. Specific chart versions are left out because they go stale.
  • TLS can end at the Gateway, so the web server no longer handles TLS; dropping TLS on the hop to the web server needs a security review.
  • Envoy's default request header limit (60 KiB) is below the 64 KiB requirement, so the chart sets it explicitly.
  • Proxy: a plain, namespace-scoped Envoy deployment. GKE Gateway runs only on Google Cloud and cannot route on token claims; the Envoy Gateway controller needs cluster-wide resources, which already blocked concurrent e2e runs (!1356 (merged)).
  • Request path: Rails, PSC, internal load balancer, Gateway pods, headless Service, web server pods. The load balancer stays because a PSC service attachment needs a forwarding rule. The Gateway balances per gRPC stream.
  • GitLab.com cutover: move the PSC service attachment to the Gateway's load balancer; the hostname and the Rails setting do not change.
  • Requirements: two-way streaming, 64 KiB header lists, two or more replicas with a PodDisruptionBudget, and a drain longer than the 120 second maximum query time.
  • max_connection_age is turned off where the Gateway runs and removed once the chart requires a proxy.

Prerequisites found during review: the web server stops at once on SIGTERM and ends running queries (#1505); the connection age setting cannot be turned off today.

Related issues: #1277, #1278, #1275, #1498, #954 (closed), #389 (closed), #182 (closed), #971 (closed), #511 (closed), #985 (closed), #1505.

AI-assisted

Edited by Victor Eberechi

Merge request reports

Loading
Loading