Status: for review, 2026-09-03. Author: Timo Furrer. Tracking work item: [gitlab-agent#1082](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/work_items/1082). Scope: what is missing to run GitLab Relay (formerly KAS) in production on Theseus, what Relay would change to get there, and what a prototype effort found. The events platform and Workspaces modules were not analyzed. ## Terms - Theseus: GitLab's platform program for building, releasing and running modular components. - Fairway: the Theseus tool that generates a Helm chart from a Fairway manifest (`manifest/v1`, kept in the service's own repository). - Runway v2: GitLab's internal deployment platform, running Fairway charts on GKE. A Runway v2 manifest (`manifest/v2`, read by runwayctl) is a second, separate file that declares the managed services and the load balancers. - caproni: the local Kubernetes (k3s) rig that deploys the same charts on a workstation. - LabKit: GitLab's Go library for the platform conventions (logging, probes, infrastructure contract parsing). Relay does not use it. - Release Framework: the Theseus path by which a component is released and reaches GitLab.com and customers; onboarding runs through `common-template-copier`. - semantic-release: the tool that derives release tags from conventional commit messages; the Runway v2 pipeline requires it. - autocore: Relay's durable workflow engine on PostgreSQL and Redis. - AutoFlow: the workflow product built on autocore. Rails is its only client today, over gRPC. ADR 0011 ([design-doc!28](https://gitlab.com/gitlab-org/architecture/autoflow/design-doc/-/merge_requests/28)) proposes a new shape for the AutoFlow APIs, including an API surface that can be exposed directly to customers. - GLAZ: the policy engine AutoFlow's `policy` module links into the `kas` binary through cgo. - OAK: Omnibus-Adjacent Kubernetes, the bridge that lets an Omnibus install proxy to a component running in a customer-provided cluster. ## Summary GitLab Relay is a modular monolith. It contains the server side of the GitLab agent for Kubernetes (agentk connections, agent configuration, the Kubernetes API proxy, managed resources, Flux notifications), the Job Router for GitLab Runner, Workspaces, an events platform, and AutoFlow. It ships today in CNG, in the Omnibus package and on GitLab.com. AutoFlow and autocore are new and have not been in production yet. They bring PostgreSQL and a cgo-linked policy engine (GLAZ) into Relay, and they triggered this Theseus discussion. Deploying only AutoFlow on Theseus, with Relay staying as it is in CNG and Omnibus, is the more natural fit ([section 4](#4-deploying-only-autoflow-on-theseus)). Similar gaps remain there: a default installation including non-Kubernetes installs, multiple PostgreSQL databases with two roles, the Rails coupling, and agent routing across deployments. A prototype effort produced a Fairway-generated chart with a `templates/custom` overlay, an extension of the `gitlab.infrastructure.v1` contract for autocore's databases, and an OAK component for Omnibus. It ran Relay end to end on the caproni rig: Rails to Relay gRPC, an agentk connection over WebSocket, and an AutoFlow flow across two workflow databases. Nothing has run on Runway yet. ### What is missing Requirements Relay or AutoFlow keep, which Theseus does not offer or scopes out (Resolution `Theseus`, and the `Both` items whose Theseus half is the substance). - Relay is a default Omnibus component, and the Vision puts Self-Managed Foundation out of Theseus scope, reaching Omnibus users only through OAK; no Theseus artifact can replace that ([G-01](#g-01-relay-ships-in-omnibus-without-kubernetes)). The same applies to AutoFlow: the internal draft "Workflow and Runner Primitives" describes "three related GitLab platform primitives: a workflow engine, an environment service, and a runnable function format" and its `VirtualAnchor.platform` field gives `"gitlab.com"` and `"self-managed"` as example values ([Google Doc, GitLab-internal](https://docs.google.com/document/d/1aziup6y5lI9iesihE_ohnFY7pXO2iGBbV14PQIoSgE4/edit?tab=t.0#heading=h.jd3yjjc6npeo)); Timo's reading is that a platform primitive ships in every default GitLab installation, non-Kubernetes installs included. - Relay depends synchronously on Rails, so its only Theseus target today is the binding the platform calls legacy ([G-03](#g-03-runway-is-the-legacy-binding-and-relay-is-cell-bound)). - One port and one protocol per workload against Relay's five listeners ([G-05](#g-05-five-listeners-and-two-protocols-against-one-port-and-one-protocol)). The only workaround is Fairway's `templates/custom` escape hatch, which costs the regenerate-cleanly property and chart publication in CI ([G-21](#g-21-chart-publication-and-regenerate-check-not-in-ci)). - The Cloudflare-fronted Runway edge against hours-long agent streams; no workaround beyond disabling Cloudflare per service ([G-06](#g-06-websocket-and-long-lived-grpc-streams-at-the-runway-edge)). - One CloudSQL instance and one IAM identity per workload against autocore's N+1 databases with two roles, which cannot collapse into one database ([G-07](#g-07-one-cloudsql-instance-and-one-iam-identity-per-workload)); the contract extension that describes them is prototyped on both sides ([G-08](#g-08-the-infrastructure-contract-cannot-describe-autocore-databases)). - OAK's model does not fit Relay; the prototype works around it in Omnibus, not in Theseus ([G-04](#g-04-oak-does-not-cover-what-relay-needs)). - Fairway has no Job primitive, no pod IP or NetworkPolicy fields, and a fixed grace period and probe shape; Fairway invites these upstream ([G-09](#g-09-migrations-need-a-job-primitive), [G-10](#g-10-private-api-needs-pod-ips-and-a-networkpolicy), [G-11](#g-11-pod-lifecycle-grace-period-probes-and-scaling)). - A Relay that does not terminate agents still routes to them through the fleet's Redis and private API; the network path from Runway to the fleet is unmodeled ([G-13](#g-13-cross-deployment-agent-routing)). - No path exists for a Fairway chart into self-managed Kubernetes installs ([G-15](#g-15-self-managed-kubernetes-delivery-has-no-path-for-a-fairway-chart)). - No documented path from a Runway pod to Gitaly, which agent_configuration, configuration_project and managed_resources need ([G-23](#g-23-gitaly-reachability-from-a-theseus-workload)). ### What would change Work Relay is open to if Theseus is the target (Resolution `Relay`); these are not missing platform features. - Per-component releases with semantic-release tags instead of releasing with the monolith; the gap is that the pipeline requirement exists and Relay's repository does not meet it yet ([G-02](#g-02-relay-releases-with-the-monolith); the onboarding tooling is [G-20](#g-20-release-framework-onboarding-conflicts-with-relay-build-and-commit-rules), whose cgo half is a platform gap). - A second Rails endpoint for AutoFlow RPCs, or the API layer ADR 0011 proposes ([G-14](#g-14-one-rails-endpoint-and-an-unpaved-rails-contract)). - A gRPC health service on the API listener ([G-12](#g-12-no-grpc-health-service-on-the-api-listener)); migrations stay in the startup path until Theseus sets a standard ([G-16](#g-16-startup-migrations-and-the-theseus-migration-standard)). - Adopting the configuration contract for Redis and the `GITLAB_TRACING` convention for tracing ([G-17](#g-17-relay-reads-redis-from-its-config-file-not-from-the-contract), [G-19](#g-19-tracing-does-not-accept-gitlab_tracing)). - Owning chart publication in CI and the image build with GLAZ ([G-21](#g-21-chart-publication-and-regenerate-check-not-in-ci), [G-22](#g-22-relay-image-with-the-glaz-cgo-build)). ## 1. Relay today ### 1.1 Build and distribution - Production `kas` is a plain `go build` ([`make kas`](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/Makefile#L397-L409)). The Bazel image targets are pure Go and the macro states that production images come from CNG ([cmd.bzl](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/cmd/cmd.bzl#L17-L20)). Relay's CI builds and pushes agentk images only ([`.gitlab-ci.yml`](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/.gitlab/.gitlab-ci.yml#L535-L547)). - GLAZ is a new distribution point that came with AutoFlow. `kas` is now a cgo build that statically links `libglaz_ffi.a`, fetched from GLAZ's package registry and pinned in [MODULE.bazel](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/MODULE.bazel#L178-L188) ([Makefile](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/Makefile#L97-L112), [fetch script](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/build/fetch_glaz_ffi.sh#L88-L98)). Both CNG and Omnibus fetch the archive themselves and assert the ABI version in the binary. Without the `glaz` build tag the `policy` module is a stand-in that refuses to load ([stub](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/module/autoflow/server/policy_engine_stub.go#L1-L13)). - CNG builds the `gitlab-kas` image with `build-essential` and the GLAZ archive, on `distroless/cc-debian13:nonroot` ([Dockerfile](https://gitlab.com/gitlab-org/build/CNG/-/blob/68670fe399688fd17b857aa7161b34f0de5177e6/gitlab-kas/Dockerfile#L24-L51)). The `kas` subchart renders a ClusterIP Service for 8150, 8151, 8153 and 8154 ([service.yaml](https://gitlab.com/gitlab-org/charts/gitlab/-/blob/34e426c262dd714a7f92a06dc41d868d526aec77/charts/gitlab/charts/kas/templates/service.yaml#L27-L43)), minReplicas 2 and a CPU HPA ([values.yaml](https://gitlab.com/gitlab-org/charts/gitlab/-/blob/34e426c262dd714a7f92a06dc41d868d526aec77/charts/gitlab/charts/kas/values.yaml#L104-L106)) and `terminationGracePeriodSeconds: 300` ([values.yaml](https://gitlab.com/gitlab-org/charts/gitlab/-/blob/34e426c262dd714a7f92a06dc41d868d526aec77/charts/gitlab/charts/kas/values.yaml#L181)). - Omnibus builds `/opt/gitlab/embedded/bin/gitlab-kas` ([software definition](https://gitlab.com/gitlab-org/omnibus-gitlab/-/blob/7f1ce34b91be18046c91769322666b839ba6fa87/config/software/gitlab-kas.rb#L65-L70)) and runs it as a runit service. `gitlab_kas` is in the `DEFAULT_GROUP` service group, so a standard Linux package install runs Relay without any Kubernetes ([services.rb](https://gitlab.com/gitlab-org/omnibus-gitlab/-/blob/7f1ce34b91be18046c91769322666b839ba6fa87/files/gitlab-cookbooks/package/libraries/config/services.rb#L38)). - GitLab.com deploys the CNG image through the kubernetes-workloads helmfile: an internal GCP LoadBalancer Service, 12 to 30 replicas scaled by KEDA on memory ([gprd values](https://gitlab.com/gitlab-com/gl-infra/k8s-workloads/gitlab-com/-/blob/1c013b19f1532fd31c3665924dbe98a3ac949f77/releases/gitlab/values/gprd.yaml.gotmpl#L622-L648)). It sets `terminationGracePeriodSeconds: 7260` and a NetworkPolicy that opens Relay to Relay on 8155 ([common values](https://gitlab.com/gitlab-com/gl-infra/k8s-workloads/gitlab-com/-/blob/1c013b19f1532fd31c3665924dbe98a3ac949f77/releases/gitlab/values/values.yaml.gotmpl#L1495-L1623)). Public `kas.gitlab.com` is fronted by HAProxy and GCLB outside that repository. - No distribution channel configures AutoFlow today: the chart has no `autoflow` key, the Omnibus template has no `autoflow` section, and the GitLab.com values set none. ### 1.2 Listeners | Port | Listener | Protocol | Clients | Exposure | Off switch | |---|---|---|---|---|---| | 8150 | `agent.listen` | gRPC, optional gRPC over WebSocket, optional TLS | agentk, agentw, GitLab Runner, runner controllers | public | none; defaulted unconditionally ([defaulting.go](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/cmd/kas/defaulting.go#L78-L79)) | | 8151 | `observability.listen` | HTTP: metrics, pprof, liveness, readiness | Prometheus, kubelet | cluster-internal only (unauthenticated pprof) | none; module unconditional | | 8153 | `api.listen` | gRPC | Rails | cluster-internal | none; `api` is required in the schema ([kascfg.proto](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/pkg/kascfg/kascfg.proto#L781-L791)) | | 8154 | `agent.kubernetes_api.listen` | HTTP/1.1 (HTTP/2 with TLS) | kubectl, helm, web frontend, CI jobs | public | none; module unconditional | | 8155 | `private_api.listen` | gRPC | other Relay replicas | replica to replica, not load-balanced | none; `private_api` is required in the schema | | 8160 | `workspaces.listen` | HTTP | - | HTTPRoute rule in the chart; not analyzed, out of scope | `workspaces.enabled` | Relay serves the readiness verdict twice: as HTTP on 8151 and as `grpc.health.v1.Health/Check` on 8150 ([agent_server.go](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/cmd/kas/agent_server.go#L188)). No other listener registers a gRPC health service. Each replica derives its own private API URL from `OWN_PRIVATE_API_URL`, else `OWN_PRIVATE_API_CIDR`, else its interface IPs ([private_api_server_url.go](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/cmd/kas/private_api_server_url.go#L17-L21)). Peers are found through Redis (`<prefix>:tunnel_tracker2`, [agent_server.go](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/cmd/kas/agent_server.go#L75)), not DNS, so replicas must reach each other directly on 8155. ### 1.3 Modules - 21 server modules live in three hard-coded Go slices ([command.go](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/cmd/kas/command.go#L416-L445), [second layer](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/cmd/kas/command.go#L461-L470), [third layer](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/cmd/kas/command.go#L479-L489)). There is no module list in kascfg and no feature flag gates a module. - Fifteen have no switch: agent_configuration, agent_registrar, agent_tracker, agent2kas_tunnel, configuration_project, managed_resources, flux, gitlab_access, job_router, kas2agentk_tunnel, kubernetes_api, notifications, observability, runner_controller, server_info. - Two are disabled only by setting their reporting period to zero: event_tracker, usage_metrics. - Four have a switch: google_profiler and workspaces (booleans), events_platform and autoflow (presence of their config section, [autoflow factory](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/module/autoflow/server/factory.go#L43-L47)). - kubernetes_api reads `agent.kubernetes_api.websocket_token_secret_file` at construction and fails startup when the file is unset or unreadable ([factory.go](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/module/kubernetes_api/server/factory.go#L109)). - Three module-level facts matter for AutoFlow. It serves its RPCs on the API listener ([factory.go](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/module/autoflow/server/factory.go#L139)). It registers module APIs for agentk-hosted remote modules on the agent listener and the private API ([factory.go](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/module/autoflow/server/factory.go#L144-L151)). It reaches clusters through the agent connection pool ([factory.go](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/module/autoflow/server/factory.go#L195-L199)). ### 1.4 External dependencies | Dependency | Who needs it | Notes | |---|---|---| | Redis (single server or Sentinel, no cluster mode) | the process, before any module | required in the schema ([kascfg.proto](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/pkg/kascfg/kascfg.proto#L776-L779)); agent and tunnel registries, rate limiter, pub/sub, AutoFlow module registry, autocore coordination | | PostgreSQL | autoflow only | one central plus N workflow databases ([R-14](#r-14-autoflow-database-topology)) | | Gitaly | agent_configuration, configuration_project, managed_resources | no address in config; Rails hands `GitalyInfo{address, token}` per request and Relay dials Gitaly directly | | Rails REST internal API | most modules, via `gitlab.address` | HS256 JWT `iss=gitlab-kas, aud=gitlab` from the shared secret; one process-wide limiter, 50 rps, burst 250 ([defaulting.go](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/cmd/kas/defaulting.go#L21-L22)) | | Rails to Relay gRPC on 8153 | seven services: ServerInfo, AgentTracker, ConfigurationProject, Notifications, Provisioner, EventsPlatform, AutoFlow | HS256 JWT `aud=gitlab-kas`, issuer not validated ([api_server.go](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/cmd/kas/api_server.go#L49)); plaintext by default | | GLAZ | AutoFlow's `policy` module, at build time | [1.1](#11-build-and-distribution) | | Object storage | nobody | | ### 1.5 Rails contract and version coupling Rails has one shared 32-byte secret (`gitlab_kas.secret_file`) for both directions; Relay reads it under two config keys that every distribution points at the same file. Rails settings: `enabled`, `secret_file`, `external_url`, `internal_url` (default `grpc://localhost:8153`), `client_timeout_seconds`, and `external_k8s_proxy_url` without a default ([1_settings.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/9d3d8861b4130f488c991c93e247c6ce4601819b/config/initializers/1_settings.rb#L621-L627)). The chart never emits `external_k8s_proxy_url`, so Rails derives it from `external_url` through a path its own comment calls legacy ([kas.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/9d3d8861b4130f488c991c93e247c6ce4601819b/lib/gitlab/kas.rb#L75-L83)). Every gRPC stub is built from the single `internal_url` ([client.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/9d3d8861b4130f488c991c93e247c6ce4601819b/lib/gitlab/kas/client.rb#L468-L471), [endpoint](https://gitlab.com/gitlab-org/gitlab/-/blob/9d3d8861b4130f488c991c93e247c6ce4601819b/lib/gitlab/kas/client.rb#L487-L489)). `GITLAB_KAS_VERSION` in the Rails repository pins Relay: a commit SHA on master, bumped by release-tools ([update_component_service.rb](https://gitlab.com/gitlab-org/release-tools/-/blob/8ac256225a709ee06ef5fa2562d0134133b9fce4/lib/release_tools/services/update_component_service.rb#L67-L96)), and the GitLab release tag on stable branches. Monthly releases write the GitLab version into Relay's `VERSION` and tag it ([kas_release.rb](https://gitlab.com/gitlab-org/release-tools/-/blob/8ac256225a709ee06ef5fa2562d0134133b9fce4/lib/release_tools/public_release/kas_release.rb#L38-L58)); CNG, Omnibus and the chart copy the pin. The `gitlab-kas-grpc` gem is pinned in the Gemfile ([Gemfile](https://gitlab.com/gitlab-org/gitlab/-/blob/9d3d8861b4130f488c991c93e247c6ce4601819b/Gemfile#L685)) and bumped by hand. ### 1.6 Requirements Relay has of a platform #### R-01 Build with cgo and GLAZ A cgo-capable build for amd64 and arm64 with access to the GLAZ archive; a runtime base with libgcc_s (distroless cc, not static); a non-root user. #### R-02 One config file and file based secrets One YAML file passed by `--configuration-file`; every secret is a file with the right base64 length; nothing is read from the environment except `OWN_PRIVATE_API_*`, `GITLAB_TOKEN` and the debug switch `KAS_DEBUG_DELAYED_SHUTDOWN` ([command.go](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/cmd/kas/command.go#L131)); rotation means restart. #### R-03 Public ingress to 8150 Long-lived HTTP/2 gRPC streams and WebSocket upgrades, no request timeout or at least 2h, buffering off, gRPC health check support. #### R-04 Public ingress to 8154 HTTP/1.1 streaming, timeouts of at least 2h, cookie forwarding, a separate route that is not forced to h2c. #### R-05 Rails to Relay gRPC on 8153 Cluster-internal reachability from Rails with the shared secret; plaintext unless `grpcs://` is configured. #### R-06 Replica to replica on 8155 Direct pod-to-pod reachability, not load-balanced; each replica must learn its own routable address. #### R-07 Internal only 8151 Reachable for scraping and probes, never public. #### R-08 Redis A single server or a Sentinel group ([kascfg.proto](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/pkg/kascfg/kascfg.proto#L434-L442)); a readiness contributor. #### R-09 Egress To the Rails internal API, to every Gitaly node at addresses handed per request (Relay is trusted with the Gitaly token), and to OTLP, Sentry and Google APIs. #### R-10 Lifecycle Termination grace longer than the drain (chart 300s, GitLab.com 7260s, autocore about 95s: 90s drain plus 5s release, [db_manager.go](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/autocore/db_manager.go#L26-L38)); HTTP probes on 8151; PDB; anti-affinity; rolling update maxUnavailable 0; memory-based scaling on GitLab.com. #### R-11 Observability Prometheus pull on 8151; an OTLP/HTTP tracing endpoint configured in the config file ([command.go](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/cmd/kas/command.go#L813-L899)), no `OTEL_*` env; JSON logs on stderr without `correlation_id`. #### R-12 Rails settings and gem `gitlab_kas.enabled`, `internal_url`, `external_url`, `external_k8s_proxy_url` and a `secret_file` byte-identical to Relay's; a compatible `gitlab-kas-grpc` gem. #### R-13 Release flow `GITLAB_KAS_VERSION` pins Relay; release-tools tags Relay with the monthly GitLab release; CNG, Omnibus and the chart build from that pin. #### R-14 AutoFlow database topology One central database plus at least one workflow database; every replica opens pools against every registered workflow database ([db_manager.go](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/autocore/db_manager.go#L361-L395)). Collapsing into one database is not an option. #### R-15 AutoFlow database roles and endpoints Per database a `runtime` and a `migration` connection, both required ([connection.proto](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/tool/pgtool/connection.proto#L87-L101)). The migration connection must reach PostgreSQL directly: goose holds a session advisory lock ([pgtool.go](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/tool/pgtool/pgtool.go#L66-L71)) and the partition sweep holds a session lock across statements ([partition_manager.go](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/autocore/partition_manager.go#L215-L240)). A pooled runtime connection needs protocol-level prepared statements. #### R-16 AutoFlow database credentials Password or client-certificate authentication, or none when a proxy authenticates on Relay's behalf, as the Cloud SQL Auth Proxy does with IAM; Relay has no IAM client of its own, and user, password and TLS are optional per connection ([connection.proto](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/tool/pgtool/connection.proto#L12-L15)). Connection files are themselves mounted secrets, one central file and one directory with a file per workflow database ([kascfg.proto](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/pkg/kascfg/kascfg.proto#L687-L704)). #### R-17 AutoFlow migrations The central migration runs at startup, retries forever and gates readiness ([engine.go](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/autocore/engine.go#L202-L235)); workflow migrations run in each worker. A pre-deploy step may run `kas autocorectl central migrate up --apply` and `db add --if-not-exists` ([db_add.go](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/cmd/autocorectl/central/db_add.go#L48)) from the same image. #### R-18 Ships in Omnibus and CNG Relay keeps shipping as a `DEFAULT_GROUP` Omnibus service and as the `kas` subchart of the GitLab chart. AutoFlow inherits the same requirement. The internal draft "Workflow and Runner Primitives" describes "three related GitLab platform primitives: a workflow engine, an environment service, and a runnable function format" and its `VirtualAnchor.platform` field gives `"gitlab.com"` and `"self-managed"` as example values ([Google Doc, GitLab-internal](https://docs.google.com/document/d/1aziup6y5lI9iesihE_ohnFY7pXO2iGBbV14PQIoSgE4/edit?tab=t.0#heading=h.jd3yjjc6npeo)). Timo's reading is that a platform primitive ships in every default GitLab installation, non-Kubernetes installs included. ## 2. What Theseus offers I researched the Theseus offer myself and I am not a Theseus expert; I may have misread a document or missed a newer one. Corrections from the Theseus teams are explicitly encouraged. ### 2.1 Deployment model with Fairway - One Fairway manifest, one chart, one Deployment, one Service, one container port, one protocol (`grpc` or `http`) ([manifest.proto](https://gitlab.com/gitlab-com/gl-infra/platform/runway/fairway/-/blob/7fd847e8320ecfdaabb25960b06bb32df28d27e1/proto/manifest/v1/manifest.proto#L53-L60), [service.yaml](https://gitlab.com/gitlab-com/gl-infra/platform/runway/fairway/-/blob/7fd847e8320ecfdaabb25960b06bb32df28d27e1/internal/chartsrc/templates/service.yaml#L10-L20)). A second workload is a second manifest and a second chart ([service owner guide](https://gitlab.com/gitlab-com/gl-infra/platform/runway/fairway/-/blob/7fd847e8320ecfdaabb25960b06bb32df28d27e1/docs/service_owner_guide.md#L740-L754)). Extra ports exist only through `spec.metrics`, which lands on a cluster-internal Service named `metrics` ([service_metrics.yaml](https://gitlab.com/gitlab-com/gl-infra/platform/runway/fairway/-/blob/7fd847e8320ecfdaabb25960b06bb32df28d27e1/internal/chartsrc/templates/service_metrics.yaml#L1-L21)). - Fairway emits no Job, Helm hook, NetworkPolicy, StatefulSet, PVC, PodMonitor or KEDA object. Init containers carry no `command`, `env` or `volumeMounts` ([values.proto](https://gitlab.com/gitlab-com/gl-infra/platform/runway/fairway/-/blob/7fd847e8320ecfdaabb25960b06bb32df28d27e1/proto/values/v1/values.proto#L495-L541)). The HPA is always on and CPU-only ([hpa](https://gitlab.com/gitlab-com/gl-infra/platform/runway/fairway/-/blob/7fd847e8320ecfdaabb25960b06bb32df28d27e1/internal/chartsrc/templates/horizontal_pod_autoscaler.yaml#L9-L17)), the PDB always on. Pod settings are fixed: `runAsUser: 100`, `terminationGracePeriodSeconds: 60`, no `preStop` ([deployment.yaml](https://gitlab.com/gitlab-com/gl-infra/platform/runway/fairway/-/blob/7fd847e8320ecfdaabb25960b06bb32df28d27e1/internal/chartsrc/templates/deployment.yaml#L43-L64)). - Fairway frames missing resource kinds as patterns to add, not as decisions ([guide](https://gitlab.com/gitlab-com/gl-infra/platform/runway/fairway/-/blob/7fd847e8320ecfdaabb25960b06bb32df28d27e1/docs/service_owner_guide.md#L756-L765), [issue 17](https://gitlab.com/gitlab-com/gl-infra/platform/runway/fairway/-/issues/17)). "Fairway aims to cover the deployment patterns GitLab has standardized on, but it will not cover every pattern on day one - especially for teams doing genuinely new work." And: "Once your extension stabilizes into a pattern the broader platform benefits from, propose it upstream as a first-class Fairway field so you can drop the local overlay." - The overlay: "This is an escape hatch, not the paved road" ([guide](https://gitlab.com/gitlab-com/gl-infra/platform/runway/fairway/-/blob/7fd847e8320ecfdaabb25960b06bb32df28d27e1/docs/service_owner_guide.md#L762)). "Anything in the `chart/templates/custom` directory is yours. Edit it freely; Fairway will never touch it." ([guide](https://gitlab.com/gitlab-com/gl-infra/platform/runway/fairway/-/blob/7fd847e8320ecfdaabb25960b06bb32df28d27e1/docs/service_owner_guide.md#L835)). Values go under the free-form `custom` key ([values.proto](https://gitlab.com/gitlab-com/gl-infra/platform/runway/fairway/-/blob/7fd847e8320ecfdaabb25960b06bb32df28d27e1/proto/values/v1/values.proto#L136)). - Publication: the paved CI job regenerates the chart from the manifest and pushes it as an OCI artifact on every tag ([helm-chart.yml](https://gitlab.com/gitlab-com/gl-infra/platform/runway/fairway/-/blob/7fd847e8320ecfdaabb25960b06bb32df28d27e1/templates/helm-chart.yml#L119-L181)). "That job alone discards your overlay templates" ([guide](https://gitlab.com/gitlab-com/gl-infra/platform/runway/fairway/-/blob/7fd847e8320ecfdaabb25960b06bb32df28d27e1/docs/service_owner_guide.md#L895-L904)). An overlay user owns publication with a hand-written `helm package` and `helm push` job. ### 2.2 Runtime with Runway v2 - Runway v2 on GKE is the target and v1 is deprecated except for EKS ([migrating-to-v2](https://gitlab.com/gitlab-com/gl-infra/platform/runway/docs/-/blob/8f790e38740f800499ad9c0aeaf40f20cdf030c6/src/content/docs/runtimes/kubernetes/migrating-to-v2.mdx#L10-L20)). The clusters run Kubernetes 1.32 with Gateway API and Workload Identity, and network policy enforcement off ([gke.tf](https://gitlab.com/gitlab-com/gl-infra/platform/runway/provisioner/-/blob/219714b496814195c25d81b61637b5906b1e93ed/modules/runtimes/gcp_gke/gke.tf#L10-L59)). - The platform's own bindings page lists "GitLab.com Legacy | The existing Runway deployment infrastructure" next to Enterprise, Cells and Dedicated, and Self-Managed ([platform-bindings.md](https://gitlab.com/gitlab-org/theseus/theseus/-/blob/27fb24990a951e52ab020e9e742169a191b9b648/docs/explanation/platform-bindings.md#L32)). - runwayctl reads the Runway v2 manifest and injects at deploy time: labels, the workload service account, `GITLAB_CONTINUOUS_PROFILING` and `GITLAB_TRACING` if unset, the `httpRoute` block, the Redis `secretRef`, and with a CloudSQL instance the cloud-sql-proxy sidecar plus `infrastructure.postgresql` ([gke_values.go](https://gitlab.com/gitlab-com/gl-infra/platform/runway/runwayctl/-/blob/ef4af1577ca1b9046e3abd08a3c72ae60e6d8efc/internal/deployment/gke_values.go#L70-L91)). - The deployment pipeline requires semantic-release: "The semantic-release component is required because Fairway's release jobs depend on the `semantic_release` job to create the release tag" ([release-platform.md](https://gitlab.com/gitlab-com/gl-infra/common-ci-tasks/-/blob/09b6ca5180f84939f05ca91d478fa0f511af90d1/release-platform.md#L179-L181)). Release Framework onboarding mandates `common-template-copier` scaffolding ([onboarding](https://gitlab.com/gitlab-org/theseus/theseus/-/blob/27fb24990a951e52ab020e9e742169a191b9b648/docs/how-to/onboard-to-release-framework.md#L198-L199)), whose release config uses the `conventionalcommits` preset ([.releaserc.json.jinja](https://gitlab.com/gitlab-com/gl-infra/common-template-copier/-/blob/a6a713ebbd8c83bad5160cb5df66a3f706b79694/.releaserc.json.jinja#L13)). ### 2.3 Data stores - CloudSQL: the Runway v2 manifest has one optional `cloudsql_instance` with `instance_connection_name` and `database_name` ([manifest.proto](https://gitlab.com/gitlab-com/gl-infra/platform/runway/runwayctl/-/blob/ef4af1577ca1b9046e3abd08a3c72ae60e6d8efc/proto/manifest/v2/manifest.proto#L99-L160)). Connection is IAM through a `cloud-sql-proxy` sidecar with `--auto-iam-authn`; no Secret is mounted ([gke_values.go](https://gitlab.com/gitlab-com/gl-infra/platform/runway/runwayctl/-/blob/ef4af1577ca1b9046e3abd08a3c72ae60e6d8efc/internal/deployment/gke_values.go#L356-L419)). An SRE sets the `postgres` password and the owner creates users, databases and schemas by hand in Cloud SQL Studio ([cloudsql.mdx](https://gitlab.com/gitlab-com/gl-infra/platform/runway/docs/-/blob/8f790e38740f800499ad9c0aeaf40f20cdf030c6/src/content/docs/runtimes/kubernetes/managed-services/cloudsql.mdx#L51-L60)); the GKE Terraform creates no databases or users ([cloudsql_managed.tf](https://gitlab.com/gitlab-com/gl-infra/platform/runway/provisioner/-/blob/219714b496814195c25d81b61637b5906b1e93ed/modules/runtimes/gcp_gke/cloudsql_managed.tf#L364-L390)). - The `gitlab.infrastructure.v1.Config` contract holds exactly one optional PostgreSQL, one Redis and one ObjectStore ([infrastructure.proto](https://gitlab.com/gitlab-org/protos/-/blob/d24612b2016a4fff84182a21a8163a71d9d1bd9d/proto/infrastructure/gitlab/infrastructure/v1/infrastructure.proto#L9-L16)). - Memorystore: one Redis per service; runwayctl honors the first entry and warns on more ([gke_values.go](https://gitlab.com/gitlab-com/gl-infra/platform/runway/runwayctl/-/blob/ef4af1577ca1b9046e3abd08a3c72ae60e6d8efc/internal/deployment/gke_values.go#L238-L248), [memorystore.mdx](https://gitlab.com/gitlab-com/gl-infra/platform/runway/docs/-/blob/8f790e38740f800499ad9c0aeaf40f20cdf030c6/src/content/docs/runtimes/kubernetes/managed-services/memorystore.mdx#L115-L119)). - Secrets: Vault, synced by External Secrets Operator, consumed as env (`secretEnvFrom`) or as files (`secretVolumes`, mode 0400, absolute path) ([secrets-management.mdx](https://gitlab.com/gitlab-com/gl-infra/platform/runway/docs/-/blob/8f790e38740f800499ad9c0aeaf40f20cdf030c6/src/content/docs/runtimes/kubernetes/secrets-management.mdx#L11-L21), [values.proto](https://gitlab.com/gitlab-com/gl-infra/platform/runway/fairway/-/blob/7fd847e8320ecfdaabb25960b06bb32df28d27e1/proto/values/v1/values.proto#L432-L441)). Vault access "can take around two weeks" ([modify-values-and-secrets.md](https://gitlab.com/gitlab-org/theseus/theseus/-/blob/27fb24990a951e52ab020e9e742169a191b9b648/docs/how-to/modify-values-and-secrets.md#L90-L105)). ### 2.4 Networking - Gateway API only; runwayctl overwrites `values.httpRoute` wholesale with one rule and one backendRef, no hostnames, matches or timeouts ([gke_values.go](https://gitlab.com/gitlab-com/gl-infra/platform/runway/runwayctl/-/blob/ef4af1577ca1b9046e3abd08a3c72ae60e6d8efc/internal/deployment/gke_values.go#L191-L210), [http_route.yaml](https://gitlab.com/gitlab-com/gl-infra/platform/runway/fairway/-/blob/7fd847e8320ecfdaabb25960b06bb32df28d27e1/internal/chartsrc/templates/http_route.yaml#L15-L25)). The public hostname is `<id>.svc.gitlab.net` behind Cloudflare; TLS terminates at Cloudflare and is re-established to the load balancer with mTLS ([custom-hostnames.mdx](https://gitlab.com/gitlab-com/gl-infra/platform/runway/docs/-/blob/8f790e38740f800499ad9c0aeaf40f20cdf030c6/src/content/docs/runtimes/kubernetes/custom-hostnames.mdx#L10-L48), [protecting-origin.mdx](https://gitlab.com/gitlab-com/gl-infra/platform/runway/docs/-/blob/8f790e38740f800499ad9c0aeaf40f20cdf030c6/src/content/docs/runtimes/kubernetes/protecting-origin.mdx#L8-L43)). - gRPC is first-class at the edge, with two notes ([grpc-support.mdx](https://gitlab.com/gitlab-com/gl-infra/platform/runway/docs/-/blob/8f790e38740f800499ad9c0aeaf40f20cdf030c6/src/content/docs/runtimes/kubernetes/grpc-support.mdx#L179-L186)). The Cloudflare gRPC zone setting "cannot be enabled through the Runway provisioner". There are "known issues with Cloudflare and gRPC services ... such as dropped messages or long-lived streaming connections being prematurely terminated", so "you may need to disable Cloudflare for your service". - WebSocket appears in no GKE runtime document. Whether an HTTPRoute passes an HTTP/1.1 Upgrade to an h2c-hinted backend is `UNVERIFIED`. - Pod IPs are routable and NetworkPolicy enforcement is off cluster-wide ([gke.tf](https://gitlab.com/gitlab-com/gl-infra/platform/runway/provisioner/-/blob/219714b496814195c25d81b61637b5906b1e93ed/modules/runtimes/gcp_gke/gke.tf#L52)). `values.environment` is a plain string map with no `fieldRef` ([values.proto](https://gitlab.com/gitlab-com/gl-infra/platform/runway/fairway/-/blob/7fd847e8320ecfdaabb25960b06bb32df28d27e1/proto/values/v1/values.proto#L16-L18)); Runway v1 injected `K8S_POD_IP` ([runway-base](https://gitlab.com/gitlab-com/gl-infra/platform/runway/runwayctl/-/blob/ef4af1577ca1b9046e3abd08a3c72ae60e6d8efc/charts/runway-base/templates/_deployment.yaml#L139-L142)), v2 does not. - Internal reachability: the Runway v2 manifest has an `internal_load_balancer` switch ([manifest.proto](https://gitlab.com/gitlab-com/gl-infra/platform/runway/runwayctl/-/blob/ef4af1577ca1b9046e3abd08a3c72ae60e6d8efc/proto/manifest/v2/manifest.proto#L80-L93)), and VPC peering lets the monolith reach internal Runway workloads ([byo-gcp-folder.mdx](https://gitlab.com/gitlab-com/gl-infra/platform/runway/docs/-/blob/8f790e38740f800499ad9c0aeaf40f20cdf030c6/src/content/docs/guides/byo-gcp-folder.mdx#L135)). The Kubernetes runtime documents name no hostname for that internal path; the Cloud Run runtime names `<service-id>.internal.runway.gitlab.net` ([onboarding.mdx](https://gitlab.com/gitlab-com/gl-infra/platform/runway/docs/-/blob/8f790e38740f800499ad9c0aeaf40f20cdf030c6/src/content/docs/runtimes/cloud-run/onboarding.mdx#L427-L431)). How a caller addresses an internal-only GKE workload is `UNVERIFIED`. ### 2.5 Configuration contract - `appConfig.data` renders to `/etc/<name>/config.yaml` with `CONFIG_DIR` set, and a change rolls the pods ([how-to](https://gitlab.com/gitlab-org/theseus/theseus/-/blob/27fb24990a951e52ab020e9e742169a191b9b648/docs/how-to/pass-application-configuration-via-fairway.md#L62-L69)). Infrastructure wiring is a separate channel: `/etc/labkit/infrastructure.yaml` plus credentials under `/secrets/infrastructure/<dep>/` ([config_map_deps.yaml](https://gitlab.com/gitlab-com/gl-infra/platform/runway/fairway/-/blob/7fd847e8320ecfdaabb25960b06bb32df28d27e1/internal/chartsrc/templates/config_map_deps.yaml#L11-L19), [labkit](https://gitlab.com/gitlab-org/labkit/-/blob/4be0b0ab95b7a504fd11adfe76350db45c28990d/v2/infrastructure/config.go#L16-L22)). appConfig is not for secrets ([how-to](https://gitlab.com/gitlab-org/theseus/theseus/-/blob/27fb24990a951e52ab020e9e742169a191b9b648/docs/how-to/pass-application-configuration-via-fairway.md#L15-L22)). - LabKit is not mandatory. A service can read its config file, parse the contract itself, serve probes and metrics, log JSON, and understand `GITLAB_TRACING`. ### 2.6 Observability - Logs: JSON on stdout or stderr is the whole contract ([how-to](https://gitlab.com/gitlab-org/theseus/theseus/-/blob/27fb24990a951e52ab020e9e742169a191b9b648/docs/how-to/get-structured-logging-on-runway.md#L42-L52)). Metrics: `spec.metrics: [{port, path}]` plus a ServiceMonitor switch in `.runway/values.yaml` ([how-to](https://gitlab.com/gitlab-org/theseus/theseus/-/blob/27fb24990a951e52ab020e9e742169a191b9b648/docs/how-to/get-prometheus-metrics-on-runway.md#L53-L83)). Tracing: `GITLAB_TRACING=otlp://agent-otelcol-collector.monitoring.svc.cluster.local:4318?service_name=<id>` in LabKit URL syntax, no `OTEL_EXPORTER_OTLP_*` ([gke_values.go](https://gitlab.com/gitlab-com/gl-infra/platform/runway/runwayctl/-/blob/ef4af1577ca1b9046e3abd08a3c72ae60e6d8efc/internal/deployment/gke_values.go#L175-L189)). - With `protocol: grpc` all three probes render as gRPC health checks on `probe_port`, and configured paths are ignored ([deployment.yaml](https://gitlab.com/gitlab-com/gl-infra/platform/runway/fairway/-/blob/7fd847e8320ecfdaabb25960b06bb32df28d27e1/internal/chartsrc/templates/deployment.yaml#L181-L228)). runwayctl's GKE `HealthCheckPolicy` does the same ([health_check_policy.tpl](https://gitlab.com/gitlab-com/gl-infra/platform/runway/runwayctl/-/blob/ef4af1577ca1b9046e3abd08a3c72ae60e6d8efc/internal/deployment/templates/gke/health_check_policy.tpl#L15-L24)). ### 2.7 Local development with caproni - caproni provisions a local k3s cluster and deploys the same chart as production ([README](https://gitlab.com/gitlab-org/caproni/-/blob/4c1dbdad9444b0820ab130cf3c4ca04395e5f9bc/README.md#L3-L6)). gitlab-caproni is the maintained monolith rig and runs no Relay today ([values](https://gitlab.com/gitlab-org/gitlab-caproni/-/blob/770c377b10dcd0f4b0abd00366ba5f6fcc1da223/values/gitlab.yaml#L54-L55)). ### 2.8 Self-managed - Vision 4.4: "Self-Managed Foundation is out of Theseus scope. SMF continues on its own track per the Self-Managed Segmentation blueprint." and "SMF receives feature work from component teams in the form of Omnibus packages, not Theseus artifacts." ([Vision](https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/theseus_platform_vision/)). - Vision 6.2: "in order to run any SMA components, including all Theseus components, the customer will need to be running Kubernetes. In the case of Omnibus instances, OAK (Omnibus-Adjacent Kubernetes) will be used to provide a bridge between VM services and Kubernetes services." (SMA: Self-Managed Advanced.) - Vision 7.2 flags the split: "This approach needs to be re-confirmed with the new leadership team, as some concerns have been raised." Vision 7.3: "Self-Managed releases will continue to be bundled meta-packages by design ... independent per-component deploys are direction for GitLab.com, not present reality, and never the goal for Self-Managed". - The Self-Managed binding is "Effectively a no-op - Helm or Helmfile only; customers bring their own databases, Redis/Valkey, and similar services", status "To be built" (Vision 2.7). - OAK today: beta since GitLab 19.0, opt-in, one component (OpenBao) ([customer docs](https://docs.gitlab.com/administration/secrets_manager/linux_package_integration/)). Its design doc keeps the exit open: "We retain the option to retire OAK from Beta before it ever reaches GA" ([OAK design doc](https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/omnibus_adjacent_kubernetes/), section "Transition from Beta to GA"). The shipped cookbook has attributes only for OpenBao ([attributes](https://gitlab.com/gitlab-org/omnibus-gitlab/-/blob/7f1ce34b91be18046c91769322666b839ba6fa87/files/gitlab-cookbooks/oak/attributes/default.rb#L1-L27), [enable.rb](https://gitlab.com/gitlab-org/omnibus-gitlab/-/blob/7f1ce34b91be18046c91769322666b839ba6fa87/files/gitlab-cookbooks/oak/recipes/enable.rb#L64)). Omnibus renders an NGINX server block and a Helm values file; the operator runs `helm` and copies secrets by hand ([openbao values](https://gitlab.com/gitlab-org/omnibus-gitlab/-/blob/7f1ce34b91be18046c91769322666b839ba6fa87/files/gitlab-cookbooks/oak/templates/default/openbao-helm-values.yaml.erb#L28-L33), [integration guide](https://gitlab.com/gitlab-org/omnibus-gitlab/-/blob/7f1ce34b91be18046c91769322666b839ba6fa87/doc/development/oak_component_integration.md#L24-L29)). Component databases come from `postgresql['component_databases']` with one password-bearing `user` and an optional passwordless `owner` ([managed_database_objects.rb](https://gitlab.com/gitlab-org/omnibus-gitlab/-/blob/7f1ce34b91be18046c91769322666b839ba6fa87/files/gitlab-cookbooks/postgresql/resources/managed_database_objects.rb#L23-L79)). - Crete: "Project Crete is a prototype, designed with production use as the eventual target" ([README](https://gitlab.com/gitlab-org/crete/-/blob/409d1acf4bbcb45560836e351f6d28d76a66d48d/README.md#L7-L14)); it installs the umbrella chart through the Operator and disables the `kas` subchart ([bundle](https://gitlab.com/gitlab-org/crete/-/blob/409d1acf4bbcb45560836e351f6d28d76a66d48d/bundle/30-gitlab/30-gitlab.yaml#L38-L39)). - GitLab Operator: wraps the umbrella chart ([kas.go](https://gitlab.com/gitlab-org/cloud-native/gitlab-operator/-/blob/055bae11a5e4beb450450728bf594edc957b6aec/controllers/kas.go#L11-L25)); ADR 0026 designs one shared CRD for Fairway charts, but "None of the three reach an installation. The Helm chart does not carry them" ([ADR 0026](https://gitlab.com/gitlab-org/cloud-native/gitlab-operator/-/blob/055bae11a5e4beb450450728bf594edc957b6aec/doc/developer/adr/0026-design-of-v2alpha1-custom-resources.md#L48-L69)). ### 2.9 Vision boundaries that matter for a default GitLab component - "Theseus's scope runs from the developer's laptop to a deployed, operable artifact ... Fleet management of GitLab's SaaS is not part of Theseus." ([vision.md](https://gitlab.com/gitlab-org/theseus/theseus/-/blob/27fb24990a951e52ab020e9e742169a191b9b648/docs/explanation/vision.md#L105-L122)). - "Enterprise-binding services must have no synchronous dependency on the GitLab application, or on other modular components running in Cells." A service that calls the GitLab API on the hot path is disqualified from that binding ([platform-bindings.md](https://gitlab.com/gitlab-org/theseus/theseus/-/blob/27fb24990a951e52ab020e9e742169a191b9b648/docs/explanation/platform-bindings.md#L55-L63)). The Cells and Dedicated binding is partial (Vision 2.7). - The 2023 Runway v1 blueprint lists "Hosting the GitLab monolith" as out of scope ([blueprint](https://gitlab.com/gitlab-com/gl-infra/platform/runway/docs/-/blob/8f790e38740f800499ad9c0aeaf40f20cdf030c6/src/content/docs/runtimes/cloud-run/reference/blueprints/runway-platform.md#L27)); no Runway document describes a workload calling the Rails internal API. - Relay is absent from the Theseus, Runway and Fairway documents except as something Runway consumes ([gitlab_kas module](https://gitlab.com/gitlab-com/gl-infra/platform/runway/provisioner/-/blob/219714b496814195c25d81b61637b5906b1e93ed/modules/gitlab_kas/main.tf#L1-L43)). No source places a job router or an events platform in Theseus scope. ## 3. Gaps and limitations Classes: Vision (conflicts with the Theseus vision or scope), Design (conflicts with a Theseus design decision), Implementation (not built yet, no conflict). Resolution: `Theseus` (the platform must offer it or widen its scope, and Relay or AutoFlow keeps the requirement), `Relay` (Relay would change and is open to it), `Both` (each side moves). Prototypes are draft merge requests. Every requirement R-01 to R-18 is affected by at least one gap. ### Gap index | ID | Gap | Class | Resolution | Affects | Prototype | |---|---|---|---|---|---| | [G-01](#g-01-relay-ships-in-omnibus-without-kubernetes) | Relay ships in Omnibus without Kubernetes | Vision | Theseus | [R-18](#r-18-ships-in-omnibus-and-cng) | [omnibus-gitlab!9742](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/9742), [gitlab-agent!4319](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/merge_requests/4319) | | [G-02](#g-02-relay-releases-with-the-monolith) | Relay releases with the monolith | Vision | Relay | [R-12](#r-12-rails-settings-and-gem), [R-13](#r-13-release-flow) | none | | [G-03](#g-03-runway-is-the-legacy-binding-and-relay-is-cell-bound) | Runway is the legacy binding and Relay is Cell bound | Vision | Theseus | [R-05](#r-05-rails-to-relay-grpc-on-8153), [R-09](#r-09-egress) | none | | [G-04](#g-04-oak-does-not-cover-what-relay-needs) | OAK does not cover what Relay needs | Design | Theseus | [R-03](#r-03-public-ingress-to-8150), [R-05](#r-05-rails-to-relay-grpc-on-8153), [R-09](#r-09-egress), [R-15](#r-15-autoflow-database-roles-and-endpoints) | [omnibus-gitlab!9742](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/9742) | | [G-05](#g-05-five-listeners-and-two-protocols-against-one-port-and-one-protocol) | Five listeners and two protocols against one port and one protocol | Design | Theseus | [R-03](#r-03-public-ingress-to-8150), [R-04](#r-04-public-ingress-to-8154), [R-05](#r-05-rails-to-relay-grpc-on-8153), [R-06](#r-06-replica-to-replica-on-8155), [R-07](#r-07-internal-only-8151) | [gitlab-agent!4315](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/merge_requests/4315), [gitlab-agent!4318](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/merge_requests/4318) | | [G-06](#g-06-websocket-and-long-lived-grpc-streams-at-the-runway-edge) | WebSocket and long lived gRPC streams at the Runway edge | Design | Theseus | [R-03](#r-03-public-ingress-to-8150), [R-04](#r-04-public-ingress-to-8154) | none | | [G-07](#g-07-one-cloudsql-instance-and-one-iam-identity-per-workload) | One CloudSQL instance and one IAM identity per workload | Design | Theseus | [R-14](#r-14-autoflow-database-topology), [R-15](#r-15-autoflow-database-roles-and-endpoints), [R-16](#r-16-autoflow-database-credentials) | none | | [G-08](#g-08-the-infrastructure-contract-cannot-describe-autocore-databases) | The infrastructure contract cannot describe autocore databases | Implementation | Both | [R-14](#r-14-autoflow-database-topology), [R-15](#r-15-autoflow-database-roles-and-endpoints), [R-16](#r-16-autoflow-database-credentials) | [protos!38](https://gitlab.com/gitlab-org/protos/-/merge_requests/38), [fairway!217](https://gitlab.com/gitlab-com/gl-infra/platform/runway/fairway/-/merge_requests/217), [labkit!666](https://gitlab.com/gitlab-org/labkit/-/merge_requests/666), [runwayctl!1958](https://gitlab.com/gitlab-com/gl-infra/platform/runway/runwayctl/-/merge_requests/1958), [gitlab-agent!4317](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/merge_requests/4317) | | [G-09](#g-09-migrations-need-a-job-primitive) | Migrations need a Job primitive | Implementation | Theseus | [R-17](#r-17-autoflow-migrations) | [gitlab-agent!4315](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/merge_requests/4315), [gitlab-agent!4318](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/merge_requests/4318) | | [G-10](#g-10-private-api-needs-pod-ips-and-a-networkpolicy) | Private API needs pod IPs and a NetworkPolicy | Implementation | Theseus | [R-06](#r-06-replica-to-replica-on-8155) | none | | [G-11](#g-11-pod-lifecycle-grace-period-probes-and-scaling) | Pod lifecycle grace period probes and scaling | Implementation | Theseus | [R-10](#r-10-lifecycle) | [gitlab-agent!4315](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/merge_requests/4315) | | [G-12](#g-12-no-grpc-health-service-on-the-api-listener) | No gRPC health service on the API listener | Implementation | Relay | [R-05](#r-05-rails-to-relay-grpc-on-8153), [R-10](#r-10-lifecycle) | none | | [G-13](#g-13-cross-deployment-agent-routing) | Cross deployment agent routing | Implementation | Both | [R-06](#r-06-replica-to-replica-on-8155), [R-08](#r-08-redis) | none | | [G-14](#g-14-one-rails-endpoint-and-an-unpaved-rails-contract) | One Rails endpoint and an unpaved Rails contract | Implementation | Relay | [R-05](#r-05-rails-to-relay-grpc-on-8153), [R-09](#r-09-egress), [R-12](#r-12-rails-settings-and-gem) | none | | [G-15](#g-15-self-managed-kubernetes-delivery-has-no-path-for-a-fairway-chart) | Self managed Kubernetes delivery has no path for a Fairway chart | Implementation | Theseus | [R-18](#r-18-ships-in-omnibus-and-cng) | none | | [G-16](#g-16-startup-migrations-and-the-theseus-migration-standard) | Startup migrations and the Theseus migration standard | Design | Both | [R-17](#r-17-autoflow-migrations) | none | | [G-17](#g-17-relay-reads-redis-from-its-config-file-not-from-the-contract) | Relay reads Redis from its config file not from the contract | Implementation | Relay | [R-08](#r-08-redis) | none | | [G-18](#g-18-the-shared-rails-secret-has-no-owner-on-theseus) | The shared Rails secret has no owner on Theseus | Implementation | Both | [R-02](#r-02-one-config-file-and-file-based-secrets), [R-05](#r-05-rails-to-relay-grpc-on-8153), [R-12](#r-12-rails-settings-and-gem) | [gitlab-caproni!108](https://gitlab.com/gitlab-org/gitlab-caproni/-/merge_requests/108) | | [G-19](#g-19-tracing-does-not-accept-gitlab_tracing) | Tracing does not accept GITLAB_TRACING | Implementation | Relay | [R-11](#r-11-observability) | none | | [G-20](#g-20-release-framework-onboarding-conflicts-with-relay-build-and-commit-rules) | Release Framework onboarding conflicts with Relay build and commit rules | Implementation | Both | [R-01](#r-01-build-with-cgo-and-glaz), [R-13](#r-13-release-flow) | none | | [G-21](#g-21-chart-publication-and-regenerate-check-not-in-ci) | Chart publication and regenerate check not in CI | Implementation | Relay | [R-13](#r-13-release-flow) | none | | [G-22](#g-22-relay-image-with-the-glaz-cgo-build) | Relay image with the GLAZ cgo build | Implementation | Relay | [R-01](#r-01-build-with-cgo-and-glaz) | [gitlab-agent!4313](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/merge_requests/4313) | | [G-23](#g-23-gitaly-reachability-from-a-theseus-workload) | Gitaly reachability from a Theseus workload | Implementation | Theseus | [R-09](#r-09-egress) | none | ### G-01 Relay ships in Omnibus without Kubernetes Relay is a `DEFAULT_GROUP` Omnibus service. The Vision declares SMF out of scope and routes any Theseus component to Omnibus users through OAK. OAK needs a customer-provided Kubernetes cluster, is beta and opt-in, ships one component, and may be retired before GA. A Theseus-packaged Relay therefore cannot replace the Omnibus service; it can only exist next to it. AutoFlow carries the same requirement as a GitLab platform primitive ([R-18](#r-18-ships-in-omnibus-and-cng)). - Affects: [R-18](#r-18-ships-in-omnibus-and-cng). Class: Vision. Resolution: Theseus. - Prototype: [omnibus-gitlab!9742](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/9742) (OAK Relay component: [relay.rb](https://gitlab.com/gitlab-org/omnibus-gitlab/-/blob/ea062e01c573baa52e973ec5e8f992ed5dab8ce5/files/gitlab-cookbooks/oak/libraries/relay.rb#L356), [nginx vhost](https://gitlab.com/gitlab-org/omnibus-gitlab/-/blob/ea062e01c573baa52e973ec5e8f992ed5dab8ce5/files/gitlab-cookbooks/oak/templates/default/nginx-gitlab-relay.conf.erb#L1), [Helm values](https://gitlab.com/gitlab-org/omnibus-gitlab/-/blob/ea062e01c573baa52e973ec5e8f992ed5dab8ce5/files/gitlab-cookbooks/oak/templates/default/relay-helm-values.yaml.erb#L1)) and [gitlab-agent!4319](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/merge_requests/4319) ([doc/oak.md](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/d0fc20408e10f49e61e932b30dffb3d2c4cdf354/doc/oak.md#L1)). - Status: the OAK BATS run passed 30 of 30 locally against a nightly image with the branch cookbooks, 24 of them in the Relay file ([nginx-relay.bats](https://gitlab.com/gitlab-org/omnibus-gitlab/-/blob/ea062e01c573baa52e973ec5e8f992ed5dab8ce5/oak-tests/nginx-relay.bats#L88)). Both listeners pointed at a harness mock, not a real Relay. The OAK CI job is manual and `allow_failure`. ### G-02 Relay releases with the monolith Relay's version is pinned by `GITLAB_KAS_VERSION` and tagged by release-tools with the monthly GitLab release; the `gitlab-kas-grpc` gem is bumped by hand. Relay is open to per-component releases; the Vision calls them "direction for GitLab.com, not present reality". The gap is that the Runway v2 pipeline already requires the `semantic_release` job to create the release tag, and the scaffolded release config uses the `conventionalcommits` preset. Relay's repository meets neither today; its contribution rules say "Do not use conventional commits" ([AGENTS.md](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/AGENTS.md#L125)). A fork of the pipeline or an own release job can meet the requirement until Relay adopts it. An independent release would also need a gem compatibility range, a Rails-facing proto compatibility policy, and changes to release-tools. The `proto-breaking` job covers durable payloads and config protos, not the Rails-facing RPC protos ([buf.breaking.yaml](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/buf.breaking.yaml#L16-L25)). - Affects: [R-12](#r-12-rails-settings-and-gem), [R-13](#r-13-release-flow). Class: Vision. Resolution: Relay. Prototype: none. - Status: verified in release-tools, the Rails repository and common-ci-tasks. ### G-03 Runway is the legacy binding and Relay is Cell bound Relay depends synchronously on Rails on the agent hot path. Agent authentication and Kubernetes API proxy authorization call the Rails internal API, with results cached for minutes (agent info 5 min, errors 1 min, [defaulting.go](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/cmd/kas/defaulting.go#L27-L28); proxy caches, [factory.go](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/module/kubernetes_api/server/factory.go#L163-L183)). AutoFlow's `StartWorkflow` makes no Rails call; the built-in modules do, from inside running flows, through the GitLab client the factory hands them ([factory.go](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/module/autoflow/server/factory.go#L104-L108)). That alone disqualifies Relay from the Enterprise binding. The Cells and Dedicated binding is partial. The only Theseus target available today is Runway v2, which the platform's own bindings page lists as "GitLab.com Legacy | The existing Runway deployment infrastructure" ([platform-bindings.md](https://gitlab.com/gitlab-org/theseus/theseus/-/blob/27fb24990a951e52ab020e9e742169a191b9b648/docs/explanation/platform-bindings.md#L32)). No platform document describes a Runway workload calling the Rails internal API or sharing a secret with Rails. - Affects: [R-05](#r-05-rails-to-relay-grpc-on-8153), [R-09](#r-09-egress). Class: Vision. Resolution: Theseus. Prototype: none. - Status: verified in code and in the Theseus and Runway documents. ### G-04 OAK does not cover what Relay needs Omnibus does not run `helm install` or distribute secrets, and it models inbound traffic as an NGINX reverse proxy only. Four consequences for Relay: - The vhost template emits `http2 on;` only under TLS ([template](https://gitlab.com/gitlab-org/omnibus-gitlab/-/blob/7f1ce34b91be18046c91769322666b839ba6fa87/files/gitlab-cookbooks/gitlab-kas/templates/default/nginx-gitlab-kas.conf.erb#L44-L47)), so cleartext gRPC through `grpc_pass` needs a new template pattern. - Single-node Gitaly is a Unix socket a pod cannot dial ([gitaly.rb](https://gitlab.com/gitlab-org/omnibus-gitlab/-/blob/7f1ce34b91be18046c91769322666b839ba6fa87/files/gitlab-cookbooks/gitaly/libraries/gitaly.rb#L51-L64)). - `component_databases` cannot express autocore's two roles: the owner has no password and the user has no DML grants. - PostgreSQL and Redis exposure on the pod network lives on an unmerged branch. - Affects: [R-03](#r-03-public-ingress-to-8150), [R-05](#r-05-rails-to-relay-grpc-on-8153), [R-09](#r-09-egress), [R-15](#r-15-autoflow-database-roles-and-endpoints). Class: Design. Resolution: Theseus. - Prototype: [omnibus-gitlab!9742](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/9742) uses a dedicated `relay.<domain>` vhost and one role for both connections ([relay.rb](https://gitlab.com/gitlab-org/omnibus-gitlab/-/blob/ea062e01c573baa52e973ec5e8f992ed5dab8ce5/files/gitlab-cookbooks/oak/libraries/relay.rb#L356)). - Status: verified in omnibus-gitlab code. ### G-05 Five listeners and two protocols against one port and one protocol Relay needs 8150 (gRPC and WebSocket, public), 8154 (HTTP/1.1, public), and 8153, 8155 and 8151 internally. Fairway renders one Service port with one `appProtocol`, and runwayctl overwrites the only HTTPRoute. The overlay adds Services for 8150, 8153 and 8154, a second HTTPRoute for `/k8s-proxy/`, and text patches to Fairway-owned templates ([service-agent.yaml](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/dea9112df9a9adb237c56ffa96d1c8cbd920b7a9/chart/templates/custom/service-agent.yaml#L1), [chart-gen.sh](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/dea9112df9a9adb237c56ffa96d1c8cbd920b7a9/scripts/chart-gen.sh#L84-L85)). On Runway a second route gets no `HealthCheckPolicy` and no `GCPBackendPolicy`, because both target the Fairway Service by name ([backend_policy.tpl](https://gitlab.com/gitlab-com/gl-infra/platform/runway/runwayctl/-/blob/ef4af1577ca1b9046e3abd08a3c72ae60e6d8efc/internal/deployment/templates/gke/backend_policy.tpl#L22-L25), [health_check_policy.tpl](https://gitlab.com/gitlab-com/gl-infra/platform/runway/runwayctl/-/blob/ef4af1577ca1b9046e3abd08a3c72ae60e6d8efc/internal/deployment/templates/gke/health_check_policy.tpl#L25-L28)). One manifest, one chart, one Deployment is the design decision; the missing per-port protocol is the part Fairway invites upstream. - Affects: [R-03](#r-03-public-ingress-to-8150), [R-04](#r-04-public-ingress-to-8154), [R-05](#r-05-rails-to-relay-grpc-on-8153), [R-06](#r-06-replica-to-replica-on-8155), [R-07](#r-07-internal-only-8151). Class: Design. Resolution: Theseus. - Prototype: [gitlab-agent!4315](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/merge_requests/4315) (manifest, chart, overlay), [gitlab-agent!4318](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/merge_requests/4318) (contract-driven chart). - Status: verified on caproni (13 objects rendered with default values, six smoke stages pass); not deployed on Runway. ### G-06 WebSocket and long lived gRPC streams at the Runway edge Agents hold bidirectional gRPC streams or WebSocket connections for hours. The Runway docs list Cloudflare's known issues with long-lived gRPC streams, and the platform's documented per-service opt-out is to disable Cloudflare. The Cloudflare gRPC setting cannot be enabled through the provisioner. WebSocket is not a documented concept on the GKE runtime. The rendered HTTPRoute has no timeouts, and the GKE backend default timeout the agent path would inherit is `UNVERIFIED` (inferred as 30s, never measured). - Affects: [R-03](#r-03-public-ingress-to-8150), [R-04](#r-04-public-ingress-to-8154). Class: Design. Resolution: Theseus. Prototype: none. - Status: `UNVERIFIED` on Runway. Verified only on caproni, where Traefik's Ingress provider ignores `appProtocol` and completes the HTTP/1.1 upgrade (101). ### G-07 One CloudSQL instance and one IAM identity per workload autocore needs a central database plus at least one workflow database, each with a DML `runtime` connection and a table-owning `migration` connection that reaches PostgreSQL directly. Collapsing into one database is not an option. Runway v2 offers one `cloudsql_instance` with one `database_name`, one IAM identity through the proxy with no password, and hand-created users. The IAM-only identity and the hand-created users are Runway's design choice; the singular instance and the missing role model are implementation work under [G-08](#g-08-the-infrastructure-contract-cannot-describe-autocore-databases). - Affects: [R-14](#r-14-autoflow-database-topology), [R-15](#r-15-autoflow-database-roles-and-endpoints), [R-16](#r-16-autoflow-database-credentials). Class: Design. Resolution: Theseus. Prototype: none. - Status: verified in runwayctl and the provisioner; CloudSQL never exercised. ### G-08 The infrastructure contract cannot describe autocore databases `gitlab.infrastructure.v1.Config` holds one PostgreSQL with no identifier, no roles, no `sslmode` and no TLS. The singular `cloudsql_instance` is a regression from Runway v1's array, and the provisioner already allows several instances per workload ([validate-inventory.rb](https://gitlab.com/gitlab-com/gl-infra/platform/runway/provisioner/-/blob/219714b496814195c25d81b61637b5906b1e93ed/scripts/inventory/validate-inventory.rb#L147-L173)). The extension adds `postgresql_databases` with identifiers, a role model (`MIGRATION`), `ssl_mode` and TLS. Fairway mounts per identifier and per role. LabKit gains database and role accessors. runwayctl gains `cloudsql_databases` with one proxy sidecar and a listener per distinct instance. Relay gains a contract reader (`autoflow.infrastructure_contract`, [kascfg.proto](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/6bf18b7e4a698fcf27f3a517b19e60514e423ab6/pkg/kascfg/kascfg.proto#L705), [contract.go](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/6bf18b7e4a698fcf27f3a517b19e60514e423ab6/internal/tool/pgtool/contract.go#L1)). Three things it does not solve. autocore has no IAM client of its own; behind the Cloud SQL Auth Proxy it connects without a password. Runway has no second IAM database user per workload (the GKE schema has no `additional_users`). The two-role split has never been exercised anywhere: the rig uses one owner role, the loadtest one user. - Affects: [R-14](#r-14-autoflow-database-topology), [R-15](#r-15-autoflow-database-roles-and-endpoints), [R-16](#r-16-autoflow-database-credentials). Class: Implementation. Resolution: Both. - Prototype: [protos!38](https://gitlab.com/gitlab-org/protos/-/merge_requests/38), [fairway!217](https://gitlab.com/gitlab-com/gl-infra/platform/runway/fairway/-/merge_requests/217), [labkit!666](https://gitlab.com/gitlab-org/labkit/-/merge_requests/666), [runwayctl!1958](https://gitlab.com/gitlab-com/gl-infra/platform/runway/runwayctl/-/merge_requests/1958), [gitlab-agent!4317](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/merge_requests/4317). - Status: verified on caproni against CloudNativePG (seven smoke stages, both workflow databases reachable); CloudSQL `UNVERIFIED`. ### G-09 Migrations need a Job primitive Fairway emits no Job and no Helm hook, and init containers cannot run a command or mount a secret. The overlay adds a pre-install and pre-upgrade migrate Job and a post-install and post-upgrade `db add --if-not-exists` Job ([job-migrate.yaml](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/dea9112df9a9adb237c56ffa96d1c8cbd920b7a9/chart/templates/custom/job-migrate.yaml#L16), [job-db-add.yaml](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/dea9112df9a9adb237c56ffa96d1c8cbd920b7a9/chart/templates/custom/job-db-add.yaml#L12)). [gitlab-agent!4315](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/merge_requests/4315) mounts the connection-file Secrets ([`--central-connection-file`](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/dea9112df9a9adb237c56ffa96d1c8cbd920b7a9/chart/templates/custom/job-migrate.yaml#L42)); [gitlab-agent!4318](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/merge_requests/4318) mounts the contract ([`--config`](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/20a0ebceabaa4e5caaadcf112720cd8458305337/chart/templates/custom/job-migrate.yaml#L43)). On a cold cluster the migrate Job failed four times before the database operator had created `autoflow_central`; `backoffLimit` let it retry until the database existed. Helm deletes a succeeded hook Job within seconds, so its logs vanish. Fairway invites this pattern upstream. - Affects: [R-17](#r-17-autoflow-migrations). Class: Implementation. Resolution: Theseus. - Prototype: [gitlab-agent!4315](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/merge_requests/4315), [gitlab-agent!4318](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/merge_requests/4318). - Status: verified on caproni, including a no-op re-run on upgrade. The race is specific to CloudNativePG; the CloudSQL behavior is `UNVERIFIED`. ### G-10 Private API needs pod IPs and a NetworkPolicy Replicas find each other through Redis by their own private API URL, so each pod must learn a routable address and reach peers directly on 8155. Fairway has no `fieldRef` (Runway v1 injected `K8S_POD_IP`, v2 does not), so Relay must fall back to `OWN_PRIVATE_API_CIDR` or interface enumeration. NetworkPolicy enforcement is off in Runway clusters, so nothing in-cluster blocks 8155. The prototype chart does not add a NetworkPolicy for 8155. Fairway invites both fields upstream. - Affects: [R-06](#r-06-replica-to-replica-on-8155). Class: Implementation. Resolution: Theseus. Prototype: none. - Status: cross-replica routing over 8155 was not exercised on any rig; `UNVERIFIED` on Runway. ### G-11 Pod lifecycle grace period probes and scaling Fairway fixes `terminationGracePeriodSeconds: 60` with no `preStop`; Relay's drain needs far longer ([R-10](#r-10-lifecycle)). With `protocol: grpc` every probe is a gRPC check on `probe_port`; Relay's `Health/Check` on 8150 returns the readiness verdict ([agent_server.go](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/cmd/kas/agent_server.go#L307-L327)), so a tight liveness probe kills a draining pod. The HPA is always on and CPU-only while GitLab.com scales Relay on memory through KEDA. Fairway invites these fields upstream. - Affects: [R-10](#r-10-lifecycle). Class: Implementation. Resolution: Theseus. - Prototype: [gitlab-agent!4315](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/merge_requests/4315) patches the grace period through `custom.terminationGracePeriodSeconds` ([chart-gen.sh](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/dea9112df9a9adb237c56ffa96d1c8cbd920b7a9/scripts/chart-gen.sh#L84-L85)). - Status: patch validated on caproni; KEDA and memory scaling not attempted. ### G-12 No gRPC health service on the API listener Only the agent server registers `grpc_health_v1` ([agent_server.go](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/cmd/kas/agent_server.go#L188)); the API and private API servers register none. A Fairway workload with `protocol: grpc` and `probe_port: 8153` is the natural shape for an AutoFlow-only Relay. It cannot become ready and fails runwayctl's `HealthCheckPolicy` until Relay adds a health server to the API listener. - Affects: [R-05](#r-05-rails-to-relay-grpc-on-8153), [R-10](#r-10-lifecycle). Class: Implementation. Resolution: Relay. Prototype: none. - Status: verified in code. ### G-13 Cross deployment agent routing Any flow that uses the `kubernetes` or `gitlab-function` built-ins or an agentk-hosted remote module reaches agents through `config.AgentConnPool` ([factory.go](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/module/autoflow/server/factory.go#L195-L199)). The pool resolves the owning replica through the Redis tunnel registry ([aggregating_querier.go](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/module/agent2kas_tunnel/router/aggregating_querier.go#L167)) and dials that replica's private API URL ([command.go](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/cmd/kas/command.go#L287-L300)). A Relay that does not terminate agent connections therefore needs the same Redis as the agent-hosting fleet. It also needs outbound reachability to that fleet's 8155 with the same `private_api` secret, and compatible tunnel protocol versions, which independent releases turn into a cross-version compatibility commitment Relay would have to make. On GitLab.com the Relay NetworkPolicy models 8155 traffic only between Relay pods in the `gitlab` and `gitlab-cny` namespaces ([values.yaml.gotmpl](https://gitlab.com/gitlab-com/gl-infra/k8s-workloads/gitlab-com/-/blob/1c013b19f1532fd31c3665924dbe98a3ac949f77/releases/gitlab/values/values.yaml.gotmpl#L1603-L1622)); a Runway pod is not among the modeled peers. - Affects: [R-06](#r-06-replica-to-replica-on-8155), [R-08](#r-08-redis). Class: Implementation. Resolution: Both. Prototype: none. - Status: verified in code; the network paths from Runway to `gitlab-production` on 8155 and to the fleet's Redis are `UNVERIFIED`. ### G-14 One Rails endpoint and an unpaved Rails contract Rails builds all seven stubs from one `internal_url` ([1.5](#15-rails-contract-and-version-coupling)); it cannot send AutoFlow RPCs to a different Relay than agent RPCs. Runway documents no pattern for a workload calling the Rails internal API. For the reverse direction it documents only VPC peering plus an internal load balancer; the Kubernetes runtime names no hostname for an internal-only workload, while the Cloud Run runtime names `<service-id>.internal.runway.gitlab.net`. `gitlab.address` must reach Workhorse or an internal gateway ([default config](https://gitlab.com/gitlab-org/charts/gitlab/-/blob/34e426c262dd714a7f92a06dc41d868d526aec77/charts/gitlab/charts/kas/templates/_default-config.yaml#L18-L21)). The chart never emits `external_k8s_proxy_url`, so a Relay on another hostname breaks Rails' derivation. ADR 0011 ([design-doc!28](https://gitlab.com/gitlab-org/architecture/autoflow/design-doc/-/merge_requests/28)) proposes a new shape for the AutoFlow APIs, including an API surface exposed directly to customers; if adopted, it changes the shape of this coupling. - Affects: [R-05](#r-05-rails-to-relay-grpc-on-8153), [R-09](#r-09-egress), [R-12](#r-12-rails-settings-and-gem). Class: Implementation. Resolution: Relay. - Prototype: none; the caproni rig wires Rails through `dynamic_overrides` ([gitlab-caproni!108](https://gitlab.com/gitlab-org/gitlab-caproni/-/merge_requests/108)). - Status: Rails behavior verified in code; Rails to Relay over the internal Service verified on caproni. ### G-15 Self managed Kubernetes delivery has no path for a Fairway chart The Operator has no extra-chart mechanism and the Fairway CRD of ADR 0026 is unbuilt. Crete disables the `kas` subchart and consumes no Fairway chart. The Self-Managed binding is "To be built". The Release Platform program's Helm chart, Operator and Omnibus integration epics, labeled `ReleasePlatform` under [epic 49](https://gitlab.com/groups/gitlab-com/gl-infra/software-delivery/-/epics/49), are open with start dates from August 2026 to November 2026 ([epic 72](https://gitlab.com/groups/gitlab-com/gl-infra/software-delivery/-/epics/72), [epic 73](https://gitlab.com/groups/gitlab-com/gl-infra/software-delivery/-/epics/73), [epic 74](https://gitlab.com/groups/gitlab-com/gl-infra/software-delivery/-/epics/74)). - Affects: [R-18](#r-18-ships-in-omnibus-and-cng). Class: Implementation. Resolution: Theseus. Prototype: none. - Status: verified in the Operator, Crete and Theseus repositories and against the epics' state on 2026-09-03. ### G-16 Startup migrations and the Theseus migration standard Relay runs the central migration at startup and reports unready until it succeeds; workflow migrations run inside each worker when it starts, serialized across replicas by goose's session advisory lock. This is by design: a Relay whose schema is not current is not ready. Theseus has not standardized migrations yet ([team#922](https://gitlab.com/gitlab-com/gl-infra/platform/runway/team/-/work_items/922), [theseus&1](https://gitlab.com/groups/gitlab-org/theseus/-/epics/1)); its reference service migrates in-process before readiness the same way ([go-service-template!53](https://gitlab.com/gitlab-org/quality/go-service-template/-/merge_requests/53)), while the platform's stated preference is an init container ([fairway#49](https://gitlab.com/gitlab-com/gl-infra/platform/runway/fairway/-/work_items/49)). Two things remain. Fairway's probe shape is fixed ([G-11](#g-11-pod-lifecycle-grace-period-probes-and-scaling)), so a migration that outruns the startup probe window is killed and never completes. There is no CLI for workflow-schema migrations for the day the standard requires an out-of-process step. - Affects: [R-17](#r-17-autoflow-migrations). Class: Design. Resolution: Both. Prototype: none. - Status: verified in code. ### G-17 Relay reads Redis from its config file not from the contract kascfg `redis.server` matches one Memorystore endpoint and `redis.sentinel` matches GitLab.com's Sentinel Redis, so the store itself fits. Runway delivers the address in `values.infrastructure` and a Vault-synced `secretRef`, while Relay reads it only from its config file; the rig mounts the password through `secretVolumes`. Relay is open to reading Redis from the contract. When flows touch agents the address must be the agent-hosting fleet's Redis, not a Runway Memorystore ([G-13](#g-13-cross-deployment-agent-routing)). - Affects: [R-08](#r-08-redis). Class: Implementation. Resolution: Relay. Prototype: none. - Status: verified on caproni with Valkey; reachability from Runway to the fleet's Redis is `UNVERIFIED`. ### G-18 The shared Rails secret has no owner on Theseus All Relay secrets are files, and `secretVolumes` mounts a Vault-synced Secret with mode 0400, so the API, private API, websocket token, Redis and OTLP secrets fit. `GITLAB_TOKEN` for the `gitlab-function` module fits through `secretEnvFrom`. Not covered: the Rails shared secret must be byte-identical on both sides. Today the chart's shared-secrets Job ([_generate_secrets.sh.tpl](https://gitlab.com/gitlab-org/charts/gitlab/-/blob/34e426c262dd714a7f92a06dc41d868d526aec77/templates/shared-secrets/_generate_secrets.sh.tpl#L113-L122)) or Rails at boot mints it. A Theseus Relay needs one owner and a delivery path into Vault and into the GitLab.com Rails deployment, and Vault access takes about two weeks. The Sentry DSN is an inline config value that would land in appConfig, which the platform says is not for secrets. - Affects: [R-02](#r-02-one-config-file-and-file-based-secrets), [R-05](#r-05-rails-to-relay-grpc-on-8153), [R-12](#r-12-rails-settings-and-gem). Class: Implementation. Resolution: Both. - Prototype: [gitlab-caproni!108](https://gitlab.com/gitlab-org/gitlab-caproni/-/merge_requests/108) mints the secret in a local chart for both namespaces. - Status: file-based delivery verified on caproni; the Vault path is untested. ### G-19 Tracing does not accept GITLAB_TRACING Relay does not use LabKit. Metrics fit: `spec.metrics: [{port: 8151, path: /metrics}]` plus the ServiceMonitor switch. Logs fit: JSON on stderr; `correlation_id` is a LabKit convention, not a gate. Tracing does not fit: Runway injects `GITLAB_TRACING` in LabKit URL syntax and sets no `OTEL_*` variable, while Relay configures tracing only through `observability.tracing.otlp_endpoint` in the config file. Relay is open to parsing `GITLAB_TRACING` or setting the endpoint per environment in appConfig. Dashboards come from the `runway-k8s-archetype` catalog ([observability.md](https://gitlab.com/gitlab-com/gl-infra/platform/runway/docs/-/blob/8f790e38740f800499ad9c0aeaf40f20cdf030c6/src/content/docs/reference/observability.md#L161-L165)), not from Relay's own. - Affects: [R-11](#r-11-observability). Class: Implementation. Resolution: Relay. Prototype: none. - Status: probes verified on caproni (pod ready in 5 to 10s); scraping into Mimir and tracing into the Theseus collector `UNVERIFIED`. ### G-20 Release Framework onboarding conflicts with Relay build and commit rules Onboarding mandates `common-template-copier`, whose update migrations rewrite `.gitlab-ci.yml` in place ([copier.yml](https://gitlab.com/gitlab-com/gl-infra/common-template-copier/-/blob/a6a713ebbd8c83bad5160cb5df66a3f706b79694/copier.yml#L151-L440)). It also mandates semantic-release ([G-02](#g-02-relay-releases-with-the-monolith)). common-ci-tasks has no Bazel support and its goreleaser template sets `CGO_ENABLED=0` ([goreleaser.md](https://gitlab.com/gitlab-com/gl-infra/common-ci-tasks/-/blob/09b6ca5180f84939f05ca91d478fa0f511af90d1/goreleaser.md#L20)); Lab Bench hardcodes it too ([mod.rs](https://gitlab.com/gitlab-org/lab-bench/bench/-/blob/3ac04e39b4168503eed67ff3f7a2b4f9a1e4f0f6/cli/src/build/mod.rs#L214-L221)). Importing an existing project is documented as fragile ([onboarding](https://gitlab.com/gitlab-org/theseus/theseus/-/blob/27fb24990a951e52ab020e9e742169a191b9b648/docs/how-to/onboard-to-release-framework.md#L266-L279)). Relay would adopt the commit convention; the cgo build needs tooling support. - Affects: [R-01](#r-01-build-with-cgo-and-glaz), [R-13](#r-13-release-flow). Class: Implementation. Resolution: Both. Prototype: none. - Status: not attempted. ### G-21 Chart publication and regenerate check not in CI Fairway's paved job regenerates from the manifest and discards the patches applied by `chart-gen.sh`. runwayctl's deployment trigger has a non-optional `needs` on Fairway's push job ([kubernetes-v2-service.yml](https://gitlab.com/gitlab-com/gl-infra/platform/runway/runwayctl/-/blob/ef4af1577ca1b9046e3abd08a3c72ae60e6d8efc/templates/kubernetes-v2-service.yml#L122-L128)), so the job cannot be skipped. No CI job runs [chart-regen-check.sh](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/dea9112df9a9adb237c56ffa96d1c8cbd920b7a9/scripts/chart-regen-check.sh#L1-L3), so a `VERSION` bump or a hand edit leaves `chart/` stale unnoticed. The contract-driven chart pins an unmerged Fairway branch commit ([chart-gen.sh](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/20a0ebceabaa4e5caaadcf112720cd8458305337/scripts/chart-gen.sh#L26)); the base chart pins the v3.1.0 commit ([chart-gen.sh](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/dea9112df9a9adb237c56ffa96d1c8cbd920b7a9/scripts/chart-gen.sh#L19-L23)). Relay owns its publication job. - Affects: [R-13](#r-13-release-flow). Class: Implementation. Resolution: Relay. Prototype: none. - Status: verified locally with Fairway built from source; whether a committed `templates/custom` survives the paved job is an inference, `UNVERIFIED` in a pipeline. ### G-22 Relay image with the GLAZ cgo build Relay's own CI builds no `kas` image; CNG does. Theseus tooling assumes `CGO_ENABLED=0` (common-ci-tasks goreleaser, Lab Bench). `fetch_glaz_ffi.sh` derives the archive triple from `uname`, so cross builds link the wrong archive. The prototype builds natively per platform with `POLICY_ENGINE=1` on distroless cc ([relay.Dockerfile](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/9fbe33dec6d06ed7cb6b9cf72451904d2263bce4/build/relay.Dockerfile#L45-L49)). No CI job publishes that image; Relay would add one. - Affects: [R-01](#r-01-build-with-cgo-and-glaz). Class: Implementation. Resolution: Relay. - Prototype: [gitlab-agent!4313](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/merge_requests/4313); [gitlab-caproni!108](https://gitlab.com/gitlab-org/gitlab-caproni/-/merge_requests/108) builds it locally. - Status: the image runs on caproni at 23 to 28 MiB RSS. ### G-23 Gitaly reachability from a Theseus workload agent_configuration, configuration_project and managed_resources dial every Gitaly node at addresses Rails returns per request, holding the Gitaly token. The Runway documents cover only the monolith reaching Runway workloads over VPC peering, not a Runway pod reaching Gitaly. On single-node Omnibus, Gitaly is a Unix socket. - Affects: [R-09](#r-09-egress). Class: Implementation. Resolution: Theseus. Prototype: none. - Status: `UNVERIFIED`; the rig's agentk connection did not exercise a Gitaly fetch. ## 4. Deploying only AutoFlow on Theseus The concrete target is GitLab.com: Relay stays as it is in CNG and Omnibus, and a second Relay process that runs only the autoflow module moves to Theseus. The product requirement that AutoFlow ships as a default component everywhere persists, self-managed and non-Kubernetes installs included ([R-18](#r-18-ships-in-omnibus-and-cng)). The internal "Workflow and Runner Primitives" draft names AutoFlow one of "three related GitLab platform primitives" ([Google Doc, GitLab-internal](https://docs.google.com/document/d/1aziup6y5lI9iesihE_ohnFY7pXO2iGBbV14PQIoSgE4/edit?tab=t.0#heading=h.jd3yjjc6npeo)). The scenario therefore covers GitLab.com only and leaves the self-managed path to the Omnibus and CNG Relay or to an OAK path. Later candidates for the same treatment are the events platform and the Job Router. ### 4.1 What modular deployment means on the platform side - A second Fairway manifest and a second Runway v2 manifest in the Relay repository, producing their own chart and their own Runway service. The Fairway manifest declares `protocol: grpc` on 8153 and `spec.metrics` on 8151; the Runway v2 manifest declares the CloudSQL instances and the load balancers. - Its own Runway service id and namespace. Rails needs the internal path: `internal_load_balancer` over the existing VPC peering. No public route, so no `<id>.svc.gitlab.net` behind Cloudflare. The hostname Rails would use for that internal path on the Kubernetes runtime is not documented and is `UNVERIFIED` ([G-14](#g-14-one-rails-endpoint-and-an-unpaved-rails-contract)). - Its own CloudSQL instance or instances for the central and workflow databases, through the extended contract ([G-08](#g-08-the-infrastructure-contract-cannot-describe-autocore-databases)). - Not its own Memorystore: the fleet's Sentinel Redis, because agent routing and the remote-module registry live there ([G-13](#g-13-cross-deployment-agent-routing), [G-17](#g-17-relay-reads-redis-from-its-config-file-not-from-the-contract)). Reachability from Runway to that Redis is `UNVERIFIED`, as for 8155. - Its own release cadence through the Runway v2 pipeline (semantic-release tags), while the AutoFlow proto stays within the `gitlab-kas-grpc` gem's compatibility range ([G-02](#g-02-relay-releases-with-the-monolith)). - The `relay` image of [G-22](#g-22-relay-image-with-the-glaz-cgo-build), not a second build, with an appConfig that enables only autoflow once module selection exists ([4.3](#43-relay-changes)). - Rails pointing AutoFlow RPCs at it, and the shared secret delivered to it ([4.4](#44-rails-change), [G-18](#g-18-the-shared-rails-secret-has-no-owner-on-theseus)). ### 4.2 What an AutoFlow only Relay needs today | Item | Needed | Why | |---|---|---| | API listener 8153 | yes | `AutoFlow` (StartWorkflow, GetWorkflow, CancelWorkflow, SendToWorkflowChannel) is served there ([rpc.proto](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/module/autoflow/rpc/rpc.proto#L241-L270)) | | Observability listener 8151 | yes | the only HTTP probe endpoint; the AutoFlow readiness contributor is registered there ([factory.go](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/module/autoflow/server/factory.go#L73)) | | Private API listener 8155 | pulled in today | the factory calls `RegisterAgentAPI` for `ModuleTunnelAPI` ([factory.go](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/module/autoflow/server/factory.go#L150)), which registers on the private API server; the listener is mandatory in the schema | | Agent listener 8150 | pulled in today | the factory registers `ModuleAPI` and `ModuleTunnelAPI` for agentk-hosted remote modules there; `agent.listen` is defaulted unconditionally | | Kubernetes API proxy 8154 | no, but bound anyway | kubernetes_api is unconditional ([command.go](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/cmd/kas/command.go#L484)); AutoFlow reaches clusters through the agent connection pool, not the proxy | | Agent connection pool and private API client | yes | the `kubernetes` and `gitlab-function` built-ins and remote modules route to agents through it ([G-13](#g-13-cross-deployment-agent-routing)) | | `gitlab.address`, `gitlab.authentication_secret_file` | yes | schema-mandatory; the built-in `gitlab` module uses the client | | `api.listen` and `private_api.listen` secret files | yes | schema-mandatory | | `agent.kubernetes_api.websocket_token_secret_file` | yes, today | kubernetes_api starts unconditionally and its factory requires the file | | Redis | yes | schema-mandatory; autocore task notifications ([redis_notifier.go](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/autocore/redis_notifier.go#L34-L60)), readiness hash, remote-module registry ([factory.go](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/module/autoflow/server/factory.go#L82-L87)), tunnel registry | | PostgreSQL | yes | central connection file plus one per workflow database; the pool is lazy and migrations retry, so a down database means unready, not exit | | Gitaly | no | no reference in the autoflow, flowcore or autocore packages; Rails passes the flow source inline as `workflow_definition` ([rpc.proto](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/module/autoflow/rpc/rpc.proto#L36-L39), [start_service.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/9d3d8861b4130f488c991c93e247c6ce4601819b/ee/app/services/cd/rollouts/start_service.rb#L41-L46)) | | Rails REST, Relay-authenticated | one endpoint | `GET /api/v4/internal/autoflow/module_info` for remote-module tokens ([get_agent_info.go](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/gitlab/api/get_agent_info.go#L18)), which has no Rails route | | Rails REST, flow-authenticated | arbitrary | the built-in `gitlab` module calls whatever a flow asks for, without Relay's JWT ([call_api.go](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/module/autoflow/builtin_modules/gitlab/call_api.go#L26-L30)) | | Rails gRPC served | `AutoFlow` | Rails' client has `start_workflow` and `send_to_workflow_channel` ([client.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/9d3d8861b4130f488c991c93e247c6ce4601819b/lib/gitlab/kas/client.rb#L334)); CD rollouts call `start_workflow` | | GLAZ | optional | without it the `policy` built-in refuses to load ([all.go](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/module/autoflow/builtin_modules/all.go#L80-L86)) | | Events platform | optional | without it the `event` built-in refuses to load ([all.go](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/module/autoflow/builtin_modules/all.go#L65-L73)) | The AutoFlow factory requires nothing else, but every other module and the process-level agent tracker GC, gateway querier, Gitaly pool, usage tracker and event tracker start anyway ([command.go](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/cmd/kas/command.go#L402-L407)). An AutoFlow-only process binds 8150, 8151, 8153, 8154 and 8155 today. ### 4.3 Relay changes 1. A selection input in kascfg: a field on `ConfigurationFile` ([kascfg.proto](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/pkg/kascfg/kascfg.proto#L761-L800)), for example a module list. Nothing exists today. 2. One ordered registry filtered by `modserver.Factory.Name()` replacing the three literals ([1.3](#13-modules)). `factoriesLayer.constructModules` already skips a factory returning `(nil, nil)` ([layers.go](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/cmd/kas/layers.go#L64-L78)). 3. Shared plumbing behind the same selection: agent tracker ([command.go](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/cmd/kas/command.go#L232)), gateway querier ([command.go](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/cmd/kas/command.go#L287)), Gitaly pool ([command.go](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/cmd/kas/command.go#L320)), usage and event trackers ([command.go](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/cmd/kas/command.go#L333-L336)), the agent server ([command.go](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/cmd/kas/command.go#L272)), the proxy listener ([factory.go](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/module/kubernetes_api/server/factory.go#L64)). 4. Optional listeners: drop the `required` rule on `api` and `private_api`, stop defaulting `agent.listen`, give the observability and proxy listeners a switch; `workspaces.enabled` is the precedent ([factory.go](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/module/workspaces/server/factory.go#L28)). 5. Decouple `RegisterAgentAPI` ([command.go](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/cmd/kas/command.go#L374)) from module construction: AutoFlow calls it only for remote modules. Making remote modules opt-in lets an AutoFlow-only Relay drop the private API listener and the agent listener; the private API client stays ([G-13](#g-13-cross-deployment-agent-routing)). 6. Module prerequisites: kubernetes_api's secret read disappears with step 2; event_tracker and usage_metrics become selectable instead of period-zero. 7. Defaulting follows selection ([defaulting.go](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/fdeb9dcc8f87782d4516f88c907495a40f8b47e5/internal/cmd/kas/defaulting.go#L60-L71)), so a disabled module's listener no longer appears configured. 8. A gRPC health service on the API listener ([G-12](#g-12-no-grpc-health-service-on-the-api-listener)). ### 4.4 Rails change Rails must be able to send `AutoFlow` RPCs to a second Relay. Today there is one `internal_url` and one stub cache keyed by service symbol ([1.5](#15-rails-contract-and-version-coupling), [kas.rb](https://gitlab.com/gitlab-org/gitlab/-/blob/9d3d8861b4130f488c991c93e247c6ce4601819b/lib/gitlab/kas.rb#L95-L97)). Either a per-service URL setting or a second client for AutoFlow; the shared secret must then be delivered to that Relay as well ([G-18](#g-18-the-shared-rails-secret-has-no-owner-on-theseus)). ADR 0011 ([design-doc!28](https://gitlab.com/gitlab-org/architecture/autoflow/design-doc/-/merge_requests/28)) proposes a new shape for the AutoFlow APIs, including an API surface exposed directly to customers. If adopted, it changes what Rails must be able to reach and how. ### 4.5 Effect on the gaps Verdicts are graded for the GitLab.com deployment, with AutoFlow still a default component of self-managed installs. Gone: the gap does not apply to this deployment. Reduced: part of it remains. Stays: unchanged or larger. "Step N" refers to the numbered Relay changes in [4.3](#43-relay-changes). | Gap | Verdict | Why | |---|---|---| | [G-01](#g-01-relay-ships-in-omnibus-without-kubernetes) | Stays | AutoFlow itself must ship in Omnibus and CNG as a default; the Theseus deployment covers GitLab.com only | | [G-02](#g-02-relay-releases-with-the-monolith) | Reduced | the AutoFlow Relay releases on its own tags, but the Runway pipeline still requires semantic-release in the Relay repository or a fork of the pipeline | | [G-03](#g-03-runway-is-the-legacy-binding-and-relay-is-cell-bound) | Stays | the AutoFlow Relay still depends synchronously on Rails and still lands on the legacy binding | | [G-04](#g-04-oak-does-not-cover-what-relay-needs) | Stays | an OAK path for AutoFlow on Omnibus meets the same NGINX and database-role limits, minus the Gitaly socket and the agent ingress | | [G-05](#g-05-five-listeners-and-two-protocols-against-one-port-and-one-protocol) | Reduced | one gRPC port plus the metrics port fits Fairway once steps 4 and 5 land; the probe question is [G-12](#g-12-no-grpc-health-service-on-the-api-listener) | | [G-06](#g-06-websocket-and-long-lived-grpc-streams-at-the-runway-edge) | Gone | the workload has no public route and the Rails path is internal, so no long-lived stream crosses the Runway edge | | [G-07](#g-07-one-cloudsql-instance-and-one-iam-identity-per-workload) | Stays | autocore's databases and roles are the whole workload | | [G-08](#g-08-the-infrastructure-contract-cannot-describe-autocore-databases) | Stays | same reason | | [G-09](#g-09-migrations-need-a-job-primitive) | Stays | the Jobs are AutoFlow's | | [G-10](#g-10-private-api-needs-pod-ips-and-a-networkpolicy) | Reduced | the inbound listener goes once step 5 lands; outbound 8155 to the fleet stays ([G-13](#g-13-cross-deployment-agent-routing)) | | [G-11](#g-11-pod-lifecycle-grace-period-probes-and-scaling) | Reduced | autocore's 95s drain still exceeds the fixed 60s; the 2h connection age no longer matters | | [G-12](#g-12-no-grpc-health-service-on-the-api-listener) | Stays | it is the probe of exactly this shape | | [G-13](#g-13-cross-deployment-agent-routing) | Stays | this gap exists only in this scenario | | [G-14](#g-14-one-rails-endpoint-and-an-unpaved-rails-contract) | Stays | the Rails change is the prerequisite of this scenario | | [G-15](#g-15-self-managed-kubernetes-delivery-has-no-path-for-a-fairway-chart) | Stays | AutoFlow on self-managed Kubernetes still needs a chart path; the CNG Relay carries it until one exists | | [G-16](#g-16-startup-migrations-and-the-theseus-migration-standard) | Reduced | the cross-module readiness coupling disappears because AutoFlow is the only module; the open standard remains | | [G-17](#g-17-relay-reads-redis-from-its-config-file-not-from-the-contract) | Stays | unchanged, and the address must be the fleet's Redis | | [G-18](#g-18-the-shared-rails-secret-has-no-owner-on-theseus) | Reduced | no websocket token; the shared Rails secret and the private API secret still need delivery | | [G-19](#g-19-tracing-does-not-accept-gitlab_tracing) | Stays | unchanged | | [G-20](#g-20-release-framework-onboarding-conflicts-with-relay-build-and-commit-rules) | Stays | a Runway v2 deployment needs the pipeline or a fork of it | | [G-21](#g-21-chart-publication-and-regenerate-check-not-in-ci) | Reduced | the overlay shrinks to the Jobs and the grace patch but still exists | | [G-22](#g-22-relay-image-with-the-glaz-cgo-build) | Stays | GLAZ is used only by AutoFlow's `policy` module, so this image needs it most | | [G-23](#g-23-gitaly-reachability-from-a-theseus-workload) | Gone | AutoFlow never touches Gitaly | ## 5. Sources - Tracking work item: [gitlab-agent#1082](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/work_items/1082). AutoFlow API direction: [design-doc!28](https://gitlab.com/gitlab-org/architecture/autoflow/design-doc/-/merge_requests/28) (ADR 0011: Workflow and Execution APIs). AutoFlow as a platform primitive: "Workflow and Runner Primitives (draft)", May 2026 ([Google Doc, GitLab-internal](https://docs.google.com/document/d/1aziup6y5lI9iesihE_ohnFY7pXO2iGBbV14PQIoSgE4/edit?tab=t.0#heading=h.jd3yjjc6npeo)). - Merge requests of the prototype effort, all drafts: [gitlab-agent!4313](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/merge_requests/4313) (image), [gitlab-agent!4315](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/merge_requests/4315) (Fairway manifest, chart, overlay), [gitlab-agent!4317](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/merge_requests/4317) (contract reader), [gitlab-agent!4318](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/merge_requests/4318) (contract-driven chart), [gitlab-agent!4319](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/merge_requests/4319) (OAK operator guide), [gitlab-caproni!108](https://gitlab.com/gitlab-org/gitlab-caproni/-/merge_requests/108) (rig fragment), [protos!38](https://gitlab.com/gitlab-org/protos/-/merge_requests/38), [fairway!217](https://gitlab.com/gitlab-com/gl-infra/platform/runway/fairway/-/merge_requests/217), [labkit!666](https://gitlab.com/gitlab-org/labkit/-/merge_requests/666), [runwayctl!1958](https://gitlab.com/gitlab-com/gl-infra/platform/runway/runwayctl/-/merge_requests/1958) (contract extension), [omnibus-gitlab!9742](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/9742) (OAK Relay component). `kas autocorectl central db add --if-not-exists` is merged in Relay master. - Code links are pinned: Relay master `fdeb9dcc8`; prototype branches at their heads on 2026-09-03; omnibus-gitlab master `7f1ce34b9`; Rails `9d3d8861`; Theseus repositories at their default-branch heads on 2026-09-03. - Theseus Platform Vision: [handbook design document](https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/theseus_platform_vision/); OAK: [handbook design document](https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/omnibus_adjacent_kubernetes/); Theseus docs: [gitlab-org/theseus/theseus](https://gitlab.com/gitlab-org/theseus/theseus); Runway docs: [gitlab-com/gl-infra/platform/runway/docs](https://gitlab.com/gitlab-com/gl-infra/platform/runway/docs).