<!-- NOTICE: This Issue tracker is for the GitLab Operator, not the GitLab Rails application. Support: Please do not raise support issues for GitLab.com on this tracker. See https://about.gitlab.com/support/ --> ## Summary The GitLab chart relies on a pre-install/pre-upgrade hook to generate its secrets, and that job requires custom RBAC permissions to work with Secrets. This creates a problem for Operator, which deliberately has no permissions to create RBAC resources. Instead, Operator sets up shared secrets using a service account that's created in the system namespace at install time. While this approach avoids creating RBAC at runtime, it restricts our Operator to managing GitLab instances only within the system namespace (unless a user manually creates and configures an additional service account for shared secrets). ## Proposal To cut down on hook usage in the GitLab chart and enable Operator to work cluster-wide out of the box, I'm proposing a non-Job-based approach to secret generation in GitLab chart: Rather than relying on a hook (and its custom RBAC), the GitLab chart can generate Secrets at template time instead. To prevent Secrets from changing on every upgrade, we can make use of the lookup function. Advantages of this approach: 1. Custom RBAC is no longer needed. 1. Hooks are no longer needed. 1. Using the chart within Operator becomes simpler. 1. Backwards-compatible: 1. We can `lookup` Secrets generated by shared-secrets, making this a seamless migration. 2. Shared secrets can remain our default until we declare the new approach stable. Disadvantages of this approach: 1. Like hooks, the lookup function doesn't work in helm template-based workflows — since we're moving away from hooks anyway, this isn't a new limitation. Users impacted by this can continue to generate secrets by hand. --- ## Implementation and rollout plan <!-- Added 2026-09-16 from the review discussion on charts/gitlab!5277 (https://gitlab.com/gitlab-org/charts/gitlab/-/merge_requests/5277#note_3840957566). The sequencing below is open to revision; the safety property in "Guiding constraint" is not. --> The Proposal above is the end state. This section is how it lands, and why the order is safe. ### Guiding constraint **No existing install may regenerate, lose, or change the shape of a generated secret.** Losing `db_key_base` makes every encrypted column unreadable, so every phase is gated on the `job` backend producing an identical set of `(Secret name, key name)` pairs and identical value shapes (charset, length, encoding, `jsonArray` wrap) until we deliberately change them. Create-once semantics (`generate_secret_if_needed`) and the `rails-secrets` fill-missing-leaves merge are part of that contract. The manifest is an internal chart template. Iterating on it is only safe because of the guards in the next section — not because it is new. ### Guards that make in-place iteration safe | Guard | State | |---|---| | Spec asserting the shell and `GitLabSecrets` projections yield the same secret/key pairs | In [!5277](https://gitlab.com/gitlab-org/charts/gitlab/-/merge_requests/5277) (`spec/configuration/shared_secrets_spec.rb`) | | Spec asserting the certificate entry is requested by exactly one backend at a time, and omitted when cert-manager, a supplied `secretName`, or disabled TLS applies | In [!5277](https://gitlab.com/gitlab-org/charts/gitlab/-/merge_requests/5277) | | Each recipe (charset, length, encoding, `jsonArray` wrap) is one declarative line in `_manifest.tpl`, so a change to what a secret contains shows up as a reviewed diff. Create-once semantics keep the values an installed release already has. | In [!5277](https://gitlab.com/gitlab-org/charts/gitlab/-/merge_requests/5277). A snapshot of the rendered script ([!5360](https://gitlab.com/gitlab-org/charts/gitlab/-/merge_requests/5360)) was dropped because it parses the shell that Phase 5 retires. | | `provider: controller` documented as internal/unsupported; `gitlabsecrets.yaml` renders only under it, so the default path is untouched | In [!5277](https://gitlab.com/gitlab-org/charts/gitlab/-/merge_requests/5277) (`doc/charts/shared-secrets.md`) | | `apps.gitlab.com/v2alpha1` carries no compatibility promise while the provider is unsupported | Phases 1–3 | The existing specs pin *which* Secrets and keys exist, under either backend, across the flag matrix. They do not pin *what is inside* them against the pre-manifest baseline: `manifest validation` asserts a random generator declares a charset, not that the charset is unchanged. Equivalence of value shapes currently rests on a one-off comparison across thirteen feature-flag combinations made during review of [!5277](https://gitlab.com/gitlab-org/charts/gitlab/-/merge_requests/5277). [!5360](https://gitlab.com/gitlab-org/charts/gitlab/-/merge_requests/5360) would have made that a standing check. It was closed because its fixtures parse the shell script that Phase 5 replaces. On the controller side, the Operator's generator tests will pin each recipe ([gitlab-operator#2249](https://gitlab.com/gitlab-org/cloud-native/gitlab-operator/-/work_items/2249)). ### Phases 1. **Implementation-agnostic manifest, shell projection only** — [charts/gitlab!5277](https://gitlab.com/gitlab-org/charts/gitlab/-/merge_requests/5277). Declarations move to `templates/shared-secrets/_manifest.tpl` with two projections: `_manifest_shell.tpl` for the existing hook Job, and `gitlabsecrets.yaml` behind the unsupported `provider: controller`. No behaviour change: the rendered script was compared against the previous output across thirteen feature-flag combinations. The manifest's 28 entries are 1:1 with the 28 secrets the previous script generated, and the shell projection is driven entirely by the manifest, with no hardcoded secrets left in it. Coverage is complete. The self-signed certificate authority is modelled as `spec.certificates`, a sibling of `spec.secrets`, because one authority produces three related Secrets (`tlsSecret`, `caSecret`, `chainSecret`) rather than three keys in one Secret. Under `provider: job` those three still come from `templates/shared-secrets/self-signed-cert-job.yml` running `cfssl-self-sign`; under `provider: controller` the same values render into the CR, and a spec asserts exactly one backend requests them. The contract is specified in `doc/development/secrets_controller.md`. 2. **Grow the manifest under the shell projection.** Newly introduced secrets are declared in the manifest rather than hand-written into shell. **Additions only:** no changes to existing entries' names, keys, or value shapes. This is the phase that buys the short feedback loop — a schema gap shows up while the controller is still being designed, not after. A change to an existing entry shows up in review of `_manifest.tpl`. 3. **One shared generation implementation** — [charts/gitlab#6658](https://gitlab.com/gitlab-org/charts/gitlab/-/work_items/6658). The `GitLabSecrets` CRD and controller start in the Operator repo ([gitlab-operator#2249](https://gitlab.com/gitlab-org/cloud-native/gitlab-operator/-/work_items/2249)), iterating on the CRD as needed. Once the controller is fully implemented, evaluate extracting its generation code into a shared library: one implementation consumed by both backends, and a baseline for all consumers of these Secrets including Theseus. FIPS is non-negotiable (FIPS-validated crypto module, approved DRBG, published FIPS build). Corresponds to steps 2–3 of [Clemens' sequencing](https://gitlab.com/gitlab-org/charts/gitlab/-/merge_requests/5277#note_3840957566). Step 1, a dedicated repo, waits for that evaluation. 4. **Distribute the controller, then experimental chart support.** `provider: controller` becomes real and documented, still opt-in and experimental. Phase 1 is the prerequisite: the chart cannot render a CR for a controller without an implementation-agnostic manifest to render it from. 5. **Ship the binary in CNG and swap the Job's shell script for it.** The manifest is mounted as a ConfigMap and the Job invokes the binary instead of generated shell (see [!5277 discussion](https://gitlab.com/gitlab-org/charts/gitlab/-/merge_requests/5277#note_3709078900)). This is the first phase that changes the default path, so it carries the equivalence proof and an upgrade test from a pre-manifest release. 6. **Retire the shell projection** once the binary is the default on all supported upgrade paths. Phases 1–2 and 3 are independent and run in parallel; 4 depends on both. ### Open decisions - **Where the generation repo, CRD, and binary live** — decided 2026-09-30: the CRD and controller start in the Operator repo. A shared library, in a dedicated generation repo (proposed in review) or CNG, is evaluated once the controller is fully implemented, together with how the binary is versioned against the chart's manifest schema. - **Certificate renewal.** The self-signed cert Job never renews, so a controller that renews on expiry would be new behaviour. `fill-missing` means an existing certificate is not reissued. Decide renewal deliberately rather than inheriting it. - **Byte-level parity with `cfssl-self-sign`** for the three certificate Secrets, so the controller path is substitutable for the Job path. - **Fail-fast on a missing CRD**: `.Capabilities.APIVersions.Has "apps.gitlab.com/v2alpha1"` is unavailable under the Operator's Helm engine, which renders without cluster API access, so the check needs another mechanism. - **Manifest schema versioning** as a contract between chart and binary, starting from `doc/development/secrets_controller.md`.