## Context Parent epic: [Cells: SSH Routing for Git Pull and Push](https://gitlab.com/groups/gitlab-org/-/work_items/13532) This issue was originally scoped around using Cloudflare Service Tokens (Client ID + Client Secret) to authenticate against the Topology Service **REST** endpoint, mirroring the HTTP Router pattern. Following the discussion in [gitlab-org/gitlab-shell#764 (note 3290137478)](https://gitlab.com/gitlab-org/gitlab-shell/-/work_items/764#note_3290137478), the team decided that GitLab-Shell will continue to communicate with the Topology Service over **gRPC** (not REST). Key points from the discussion: - gRPC is preferred for inter-service communication (efficiency, type safety, generated clients). - HTTP Router uses REST only because Cloudflare Workers don't natively support gRPC; that constraint does not apply to GitLab-Shell. - The [Topology Service gRPC endpoint is protected by mTLS](https://gitlab.com/gitlab-org/cells/topology-service/-/blob/main/docs/security.md#grpc-endpoint-security), not by Cloudflare Access. - GitLab-Shell already supports mTLS in its Topology Service client configuration (see [`config.yml.example`](https://gitlab.com/gitlab-org/gitlab-shell/-/blob/ef24979572b0a81bf6f512e860d174f229463825/config.yml.example#L154-165)). The remaining work is therefore an **infrastructure** task: provision the mTLS key pair (client certificate + private key, plus CA if needed) and make it available to the GitLab-Shell deployment so the existing Topology Service client can authenticate. ## Proposal Provide GitLab-Shell with the mTLS key pair required to authenticate against the Topology Service gRPC endpoint: 1. Manage the mTLS client certificate and private key in Vault (issuance, rotation, access policy). 2. Mount the certificate and key into the GitLab-Shell pods (for example, via a Kubernetes Secret referenced from the Helm chart / config-mgmt). 3. Wire the file paths through to GitLab-Shell's Topology Service client configuration (the `ca_file`, `certificate_file`, and `key_file` fields already supported in `config.yml`). 4. Confirm GitLab-Shell can successfully perform a Classify gRPC call against the Topology Service in the target environment. 5. Document the new configuration and how to provision/rotate the certificate. 6. Behavior on self-managed / GDK (where mTLS to a real Topology Service is not used) must remain unaffected. ## Acceptance criteria - [ ] mTLS client certificate and private key for GitLab-Shell → Topology Service are managed in Vault. - [ ] Helm chart / config-mgmt mounts the certificate and key into the GitLab-Shell deployment. - [ ] GitLab-Shell's Topology Service client configuration (`ca_file` / `certificate_file` / `key_file`) is populated from the mounted files. - [ ] GitLab-Shell successfully performs a Classify gRPC call against the Topology Service in the target environment. - [ ] Certificate rotation path is defined and documented. - [ ] Self-managed / GDK behavior is unaffected (no mTLS required when not configured). - [ ] Documentation updated to describe the new configuration. ## Out of scope - Switching the GitLab-Shell ↔ Topology Service protocol from gRPC to REST. - Cloudflare Service Token (`CF-Access-Client-Id` / `CF-Access-Client-Secret`) based authentication. That pattern is used by the HTTP Router for the REST endpoint and is no longer planned for GitLab-Shell. ## Dependencies - Counterpart infrastructure action item from the [SSH Router sync summary](https://gitlab.com/groups/gitlab-org/-/work_items/13532#note_3275451474). - mTLS client implementation already present in GitLab-Shell's Topology Service client.