## Summary GitLab connects to an add-on over TLS without trusting the certificate's CA. The first case is Orbit: `GitLabCore.spec.orbitRef` sets `global.appConfig.orbit` with the `tls://` endpoint and the JWT Secret, but not the CA. Today the Operator issues no certificate. The administrator creates the `kubernetes.io/tls` Secret for `Orbit.spec.tls.secretName`, then adds its CA to GitLab by hand through `global.certificates.customCAs` in `spec.chart.values`. ADR 37 (`doc/developer/adr/0037-gitlabcore-orbit-reference.md`) lists this as a drawback: "GitLab has to trust the certificate of the Orbit". The field doc of `OrbitTLSSpec` says so too: "The Operator does not configure that trust" (`api/v2alpha1/orbit_types.go`). ## Verify first **Does the Rails Orbit client trust `customCAs` at all?** `customCAs` reaches the system bundle through the chart's `certificates` init container. The Ruby `grpc` gem uses its own bundled roots unless the client passes the system bundle, as the Gitaly client does through `Gitlab::X509::Certificate.ca_certs_bundle`, or `GRPC_DEFAULT_SSL_ROOTS_FILE_PATH` is set. If the Orbit client does neither, no Operator change makes GitLab trust the Orbit, and this needs an upstream fix first. Confirm it before writing the ADR, for example with a manual `customCAs` entry on a running instance. ## Proposal The component reports the CA GitLab must trust in its status, and the GitLabCore reconciler adds it to `global.certificates.customCAs` through the reference it already follows, such as `orbitRef`. - The status field is a shared type, for example a Secret name and key, so that any v2alpha1 resource serving TLS to GitLab can report one. The status stays the contract between the reconcilers, as `status.grpcEndpoint` does, and it works for a certificate the administrator supplies as much as for one the Operator issues. - The component reports the field only when its TLS Secret holds `ca.crt`. - Only Orbit implements it in this issue. No other v2alpha1 kind serves TLS to GitLab today (Siphon is a client), so the ADR sketches how a second component would use it rather than building more than Orbit needs. **Out of scope: an issuer reference on `spec.tls`.** Letting the Operator request the certificate from cert-manager, reusing `IssuerRef` (`api/v2alpha1/gitlabcore_types.go`), is a way to get a certificate, not a way to trust one: cert-manager writes `ca.crt` into the Secret, and the status field above still carries it to GitLabCore. The two compose, so the issuer reference is a separate follow-up. It would make the Operator create cert-manager `Certificate` objects for the first time; today it only sets an annotation on the Gateway. The ADR also says how this relates to the `GitLabSecrets` resource. GitLabSecrets generates a CA, but discards its key, so it cannot issue certificates for components later. ## Design points for the ADR - **Merge user and derived CAs.** `spec.chart.values` win over derived values, and the merge treats lists as scalar values (`pkg/support/values.go`). An administrator who already sets `global.certificates.customCAs`, for example for a corporate CA, would silently drop the derived entry. Proposed: append the derived entries to the user's list, deduplicated by Secret name. This is a deliberate exception to "values win", and the ADR says so. Refusing the combination with a condition, as `OrbitValuesConflict` does for `knowledgeGraph`, would block trust in the most common enterprise setup. - **Always name the key.** A `customCAs` entry without `keys` projects every key of the Secret. For a `kubernetes.io/tls` Secret that mounts `tls.key` into every Rails pod. The derived entry names `ca.crt` alone. - **A Secret without `ca.crt` adds nothing.** A projected key that does not exist blocks the pod mount, as a missing JWT Secret would, so the derived entry must never name a missing key. A publicly trusted certificate, which needs no entry, is the ordinary case. Checking for the key means reading the Secret's data, where ADR 37 reads only the metadata of one Secret. The RBAC exists already, since GitLabSecrets reads Secrets, but the ADR states the change. - **Rollouts.** Adding or removing a CA changes the GitLab values. That rolls the Rails workloads and renames the migrations Job, like the other connection changes ADR 37 lists. - **Rotation reaches no running pod.** Rotating the CA in place changes the Secret's content, not the values, which name the Secret. Nothing rolls, and Rails keeps the old CA until its pods restart, as with the JWT key in ADR 37. With a cert-manager CA Issuer, renewing the leaf keeps the CA, so only a CA rotation is affected. Rolling pods on Secret changes is tracked in item 39 of #2330. ## Acceptance criteria - A GitLabCore that references an Orbit serving TLS trusts the Orbit certificate with no manual `customCAs` entry. - An Orbit whose TLS Secret has no `ca.crt` adds no entry, and GitLab still starts. - User-supplied `customCAs` and the derived CAs are merged as the ADR decides, with a unit test for each case: no user list, a user list, a user list naming the same Secret. - The ADR shows how a second component would use the same mechanism. - A spec in `doc/specs/bridge/` and an ADR under `doc/developer/adr/`. Also updated: - ADR 37: the drawbacks "GitLab has to trust the certificate of the Orbit" and "Nothing proves the connection works", as far as this issue covers them; - the `OrbitTLSSpec` field doc in `api/v2alpha1/orbit_types.go`; - "What if TLS is terminated in front of Orbit?" in `doc/specs/bridge/gitlabcore/configuration.md`. - Unit tests, plus an e2e step in the `knowledgegraph` suite that shows Rails reaching Orbit over TLS. Nothing today shows Rails reaching Orbit at all. - The step names what it observes, for example a `gitlab-rails runner` call through the Orbit client, or a GitLab endpoint that calls Orbit. - The suite issues the Orbit certificate from a cert-manager `selfSigned` Issuer today, where `ca.crt` is the certificate itself. The step uses a CA Issuer backed by a root certificate instead, so that `ca.crt` differs from `tls.crt`, as in a real installation. ## Context Raised in review of !1748 (https://gitlab.com/gitlab-org/cloud-native/gitlab-operator/-/merge_requests/1748#note_3968004544, https://gitlab.com/gitlab-org/cloud-native/gitlab-operator/-/merge_requests/1748#note_3968449998). Related: item 51 of #2330 (verify TLS for Siphon and Orbit connections by default).