## Summary While integrating **iam-data-access** into the Caproni dev rig ([caproni-demo!149](https://gitlab.com/gitlab-com/gl-infra/sandbox/caproni-demo/-/merge_requests/149)) we evaluated how the service should source its PostgreSQL connection. That work turned into a wider change: IAM moves off hand-rolled Viper configuration onto file-only protobuf configuration; wiring the database through Fairway's `infrastructure` contract follows in https://gitlab.com/gitlab-org/gitlab/-/work_items/631841. Part of https://gitlab.com/groups/gitlab-org/-/epics/23921. ## What we are building IAM configures itself today with Viper, a Go configuration library. Viper loads three TOML files — a base file, an environment file, and a secrets file — and layers them, merging paths relative to the working directory. Its `AutomaticEnv` feature lets any config key be overridden by a same-named environment variable. That override is how secrets reach the service today. Runway and the Caproni dev rig ship the whole config as one `CONFIG_TOML` environment variable, full of placeholders like `VAULT_MANAGED` that Vault fills in at deploy time. This makes the config hard to review, hard to validate before deploy, and dependent on environment variables. The replacement is one complete config file per service per environment, with no layering and no `base.toml`. Each file is checked against a protobuf schema with `protovalidate` rules, so a bad config fails at startup with a specific error per field. The format is YAML, not TOML. This is required, not optional: Fairway, the Runway chart library, renders `appConfig` as a YAML tree, and cannot render TOML. The runtime interface is a path, never file content. `CONFIG_DIR` names a directory holding `config.yaml`. `CONFIG_PATH` is a fallback that names a file directly, for deployments with no Helm chart. Secrets stay in their own file. The config's `secrets_file` field points to them: an absolute path to a mounted Secret volume when deployed, or a plain filename such as `secrets.yaml` next to the config file for local development, CI, and GitLab Omnibus. Loaded secret values are wrapped in a redacting type, so a stray log line cannot print one by mistake. Each service has one root protobuf message and its own secrets root. `iam-data-access` and `iam-auth` do not share a schema, so a data-access config cannot even express an OAuth section, and can never fail a rule that has nothing to do with it. None of this depends on Kubernetes, Helm, a ConfigMap, or Fairway. Each runtime just puts a file in a directory: | Runtime | Who supplies the file | | --- | --- | | Runway | Fairway renders a ConfigMap from its `appConfig` values block and injects `CONFIG_DIR` | | Caproni dev rig | the same, from the rig's own values file | | GATE sandbox | a ConfigMap for the config and a Secret for the secrets, with `CONFIG_DIR` set explicitly | | GitLab Omnibus | the package writes both files into one directory and sets `CONFIG_DIR` | | Local development and CI | `CONFIG_DIR` points at a directory committed to the repo | Database connectivity has two interchangeable sources for the same reason: Fairway's `infrastructure.yaml` where available, and an explicit `endpoint` block where it is not. ## Delivery plan The plan has six stages, about 20 merge requests (MRs) in total. This issue covers stage 1 and is done when the switch MR merges: both services and the migrate command read the YAML files when `CONFIG_DIR` or `CONFIG_PATH` is set, and local development and CI run on that path. Stage 2 is one issue per runtime: https://gitlab.com/gitlab-org/gitlab/-/work_items/632289, https://gitlab.com/gitlab-org/gitlab/-/work_items/632290 and https://gitlab.com/gitlab-org/gitlab/-/work_items/632294. Stages 3, 4 and 6 are https://gitlab.com/gitlab-org/gitlab/-/work_items/632296 and https://gitlab.com/gitlab-org/gitlab/-/work_items/632297. Stage 5 is https://gitlab.com/gitlab-org/gitlab/-/work_items/631841. | Stage | Goal | Reversible | Production impact | | --- | --- | --- | --- | | 0 — Prerequisite | Create the Vault secret `iam-secrets` before anything mounts it | Not applicable | None | | 1 — Build (12 MRs) | The new config system exists next to the old one, and loads every environment the same way | Yes, revert | None | | 2 — Migrate the runtimes (4 MRs) | Move each runtime onto `CONFIG_DIR`, cheapest blast radius first | Yes | Staging then production, gated | | 3 — Remove the old path (1 MR) | Delete Viper and the environment-variable contract | No | Removes the fallback | | 4 — Simplify (4 MRs) | Drop the generic config plumbing, now that one code path remains | Yes, internal only | None | | 5 — Adopt `infrastructure` (1 MR) | Database coordinates come from Fairway (https://gitlab.com/gitlab-org/gitlab/-/work_items/631841) | Yes, flip `database.source` back to `endpoint` | The database connection path | | 6 — Close out (2 MRs) | Documentation, upstream follow-ups, delete dead code | Yes | None | Both config paths run side by side through stage 2. With neither `CONFIG_DIR` nor `CONFIG_PATH` set, the service falls back to the old Viper path, so every step up to stage 3 can be undone by reverting the MR that made it. Some points are safe to sit at indefinitely: the end of stage 1, the end of stage 2, and any MR boundary in stages 4 to 6. Stage 3 is a single MR, so there is no unsafe middle. Deployments move in order: the GATE sandbox, then Runway staging and production, then the self-managed Helm chart. The GATE sandbox is the team's shared integration environment, so it goes first. Runway carries the deployments the team operates, so it is where the new path is verified for real before a customer runs it. The self-managed chart follows, so the beta installs can move to the YAML layout before general availability. Each step rehearses the next. Stage 3 is the point of no return. It merges only once all three deployments have run the new path and passed smoke tests, and once the `iam serve all` command, which runs every service in one process, can read its config from the YAML path. Until stage 3 every config change is made in both formats (next section). That window now lasts until 20.0. ### Config changes while both formats exist Developers do not write YAML test fixtures today, and there is no sweep before the cutover. Instead, every change to a config setting is made to both formats in the same MR, and CI checks that the two stay the same. This is the rule AGENTS.md states under "TOML config and proto config move together". It holds until stage 3 removes the TOML path. One config setting consists of these parts while both formats exist: - the field on the Go config struct and its `Validate` rule, in `auth/config` or `dataaccess`; - the field in the protobuf schema under `proto/config/`, with its validation rule; - the key in the TOML files: `configs/base.toml` or `configs/environments/*.toml`, plus the `CONFIG_TOML` block in `.runway/**/values-*.yaml` when staging and production need their own value; - the key in the YAML files under `configs/auth/` and `configs/data-access/`; - when `configs/base.toml` gives the setting a default: the same value, either set in every YAML file or applied in the service's `defaults.go`, since the YAML path has no base file; - the row in `legacyKeyMap` in `configs/proto_toml_parity_test.go`; - from stage 1 MR 5 (data-access) and MR 6 (auth) on: the line in `from_proto.go` that copies the protobuf field onto the Go struct. What CI checks, and from when: | Check | Test | Available | | --- | --- | --- | | Every TOML key, including the keys in the Runway `CONFIG_TOML` blocks, has a field in the protobuf schema | `configs/proto_toml_parity_test.go` | now | | Every committed YAML file passes the schema in strict mode, which rejects keys the schema does not know | `configs/configs_test.go` | now | | Every committed environment loads to the same Go struct through the TOML path and the YAML path, including the database parameters the migrate command uses | the comparison test in `pkg/config/bind` | MR 5 for data-access, MR 6 for auth | The comparison test is the check that catches a value changed on one side only, a key missing from the YAML files, and a missing `from_proto.go` line. Until MR 5 and MR 6 merge, only review catches those three. The staging and production `CONFIG_TOML` blocks and the sandbox files (`iam/L1/sandbox-l1.toml` and `iam/L2/sandbox-l2.toml` in the sandbox-config repository) have no YAML counterpart until their stage 2 cutover. The cutover MR for each environment translates its TOML into YAML once, and the smoke test on that environment is the check. Nobody maintains these files in both formats before then. Tests for a config rule do not add config files. The rule is tested on the Go struct, with a table test on `Validate`, and on the schema in `proto/config/validation_test.go`, which takes the one committed `proto/config/testdata/<service>.yaml` and removes or replaces a single key per case. The TOML files under `pkg/config/testdata` and `configs/testdata/layers` belong to the Viper loader and to the parity test, and stage 3 deletes them together with those. Stage 3 is the only cleanup. Its one MR deletes the Viper loader, the TOML files and their test fixtures, the parity test, the `CONFIG_TOML` handling in `scripts/entrypoint.sh`, and the TOML instructions in the README, `docs/` and `.ai/`. ## Status Status as of 2026-10-14. Stage 1 build is nearly complete. The merged MRs do not change what runs today, because the YAML path activates only when `CONFIG_DIR` or `CONFIG_PATH` is set. | Step | What | State | |---|---|---| | Stage 1, MR 1 | Protobuf schema and one config file per service per environment | Merged as [!449](https://gitlab.com/gitlab-org/auth/iam/-/merge_requests/449) | | Stage 1, parity test | A test that fails CI when a TOML key has no field in the protobuf schema | Merged as [!521](https://gitlab.com/gitlab-org/auth/iam/-/merge_requests/521) | | Stage 1, MR 2 | Config path resolution, the `UsesYAMLConfig()` switch on `CONFIG_DIR` and `CONFIG_PATH`, explicit storage parameters | Merged as [!467](https://gitlab.com/gitlab-org/auth/iam/-/merge_requests/467) | | Stage 1, MR 3 | The loader for the YAML config file and the secrets file | Merged as [!689](https://gitlab.com/gitlab-org/auth/iam/-/merge_requests/689) | | Stage 1, MR 4 | The `base.toml` defaults applied to the YAML config | Merged as [!734](https://gitlab.com/gitlab-org/auth/iam/-/merge_requests/734) | | Stage 1, follow-up to MR 4 | The iam-auth and iam-data-access defaults move out of `pkg/config` into the service packages | Merged as [!763](https://gitlab.com/gitlab-org/auth/iam/-/merge_requests/763) | | Stage 1, MR 5 | Mapping of the YAML config onto the data-access runtime config and the migration database parameters, with a test that loads every committed data-access environment through both the TOML path and the YAML path and compares the results | Merged as [!738](https://gitlab.com/gitlab-org/auth/iam/-/merge_requests/738) | | Stage 1, MR 6 | The same mapping for iam-auth, with the same test for the auth environments | Merged as [!748](https://gitlab.com/gitlab-org/auth/iam/-/merge_requests/748) on 2026-10-12 | | Stage 1, MR 7 | The switch: services and the migrate command read the YAML files when `CONFIG_DIR` or `CONFIG_PATH` is set, and local development and CI run on the YAML path | Three MRs. The data-access half is [!837](https://gitlab.com/gitlab-org/auth/iam/-/merge_requests/837), ready for review since 2026-10-14, carved from the spike's reference branch, draft [!803](https://gitlab.com/gitlab-org/auth/iam/-/merge_requests/803), which does not merge. The development signing key for the YAML secrets file, which the iam-auth half needs, merged as [!842](https://gitlab.com/gitlab-org/auth/iam/-/merge_requests/842) on 2026-10-13. The iam-auth half follows !837. Local development and CI on the YAML path follow both and close this issue | | Stage 2 | Runtime cutovers | https://gitlab.com/gitlab-org/gitlab/-/work_items/632289, https://gitlab.com/gitlab-org/gitlab/-/work_items/632290, https://gitlab.com/gitlab-org/gitlab/-/work_items/632294 | | Stages 3, 4, 6 | Removal of the old path and simplification | https://gitlab.com/gitlab-org/gitlab/-/work_items/632296, https://gitlab.com/gitlab-org/gitlab/-/work_items/632297 | | Conversion command | Converts a self-managed TOML install to the YAML layout | https://gitlab.com/gitlab-org/gitlab/-/work_items/632291 | | Stage 5 | Database coordinates from the Fairway `infrastructure` source | Not started. The mapping is https://gitlab.com/gitlab-org/gitlab/-/work_items/631841; until it lands, the loader returns an error for `database.source: infrastructure` | Decision for MR 7, which config root the migrate command parses in the `iam-auth` image (https://gitlab.com/gitlab-org/gitlab/-/work_items/611098#note_3998467662): the migrate command parses a root of its own, `MigrationConfig` with `MigrationSecrets`, holding only the fields both service roots share, so either service's files parse as it. The roots land in the iam-auth half. The data-access half parses the data-access root until then. The migrate step stays in both images until https://gitlab.com/groups/gitlab-org/-/work_items/22814 is done (https://gitlab.com/gitlab-org/gitlab/-/work_items/611098#note_4002347677); https://gitlab.com/gitlab-org/gitlab/-/work_items/633526 tracks restricting it to the iam-data-access image. Also for MR 7: the loader rejects `CONFIG_TOML` together with `CONFIG_FILE_PATH`, and `CONFIG_DIR` together with `CONFIG_PATH`. The data-access half also rejects `CONFIG_DIR` or `CONFIG_PATH` together with `CONFIG_FILE_PATH` or `SECRETS_FILE_PATH`, and the container entrypoint rejects `CONFIG_TOML` together with `CONFIG_DIR` or `CONFIG_PATH`. A self-managed install that converted to the YAML layout but kept the TOML variables in its Helm values then fails at start with a message naming both, instead of running on the YAML files while the TOML variables are ignored. The original loader MR [!465](https://gitlab.com/gitlab-org/auth/iam/-/merge_requests/465) was 2,244 lines across 22 files, too large to review. It was split into the MRs above, which supersede it. The comparison test grows with the series, so a value that fails to carry over shows up as a test failure. The self-managed beta runs on the TOML format. The release that adds the YAML path keeps reading TOML until 20.0, and https://gitlab.com/gitlab-org/gitlab/-/work_items/632291 converts beta installs to the YAML layout. One correction: an earlier comment on this issue said Fairway's `appConfig` feature shipped in v1.38.1 and that IAM needed a version bump to use it. That was wrong. `appConfig` shipped in Fairway v1.37.0, which IAM already uses through `release-platform@v4.36`. No version bump is needed, and the MR that pinned a newer Fairway version has been closed. ## Background: the Fairway `infrastructure` interface for DB config Today iam-data-access sources its DB connection from its own config (`[platform.database]` TOML + viper `AutomaticEnv` for `PLATFORM_DATABASE_*`). It does **not** read the LabKit `infrastructure` config that the Fairway-generated chart already renders to `/etc/labkit/infrastructure.yaml` and mounts the connection secret for at `/secrets/infrastructure/postgresql`. So the chart's `infrastructure:` block is currently **inert** for IAM. By contrast, **Artifact Registry** (sibling service, same Fairway/Runway + LabKit stack) consumes this interface — its chart wires the DB via `infrastructure.postgresql.secretRef`. **For self-managed (SM), the backing store is vanilla PostgreSQL** (Yugabyte is a .com/Cells concern, not SM). The `infrastructure` interface is exactly the Postgres-shaped, provider-agnostic contract for that: `host`/`port`/`databaseName` from the rendered YAML + credentials from a mounted secret (`format: CNPG | CRUNCHY | ZALANDO | CUSTOM`, with `projection` for `CUSTOM`). Adopting it would: - align IAM with AR and the Runway deployment model; - make the deployed-pod DB wiring **declarative** — removing the interim "bake the CNPG-generated password into config / deploy-then-read" hack used in the Caproni rig (see [caproni-demo!149](https://gitlab.com/gitlab-com/gl-infra/sandbox/caproni-demo/-/merge_requests/149)); **Proposed:** have the iam-data-access config loader read DB connectivity from the LabKit v2 `infrastructure` package (`gitlab.com/gitlab-org/labkit/v2/infrastructure`), so the chart's `infrastructure.postgresql.secretRef` drives the connection. ### Note on Yugabyte support The `infrastructure` interface is **Postgres-protocol-coupled**, not generic: - The Fairway schema (`gitlab-com/gl-infra/platform/runway/fairway`, `gen/infrastructure/v1`) is typed per backend — top-level `postgresql:` / `redis:`; there is **no `yugabyte:` type**. The LabKit loader builds a **pgx** connection. - Yugabyte (YSQL) is PG-wire-compatible, so a YB cluster *can* be consumed through the `postgresql:` block (point `host`/`port` at the YSQL endpoint, `secretRef.format: CUSTOM`) — **but it would be treated as vanilla Postgres**: no first-class Yugabyte awareness, and crucially **no YugabyteDB smart-driver support** (cluster/topology-aware load balancing). The schema's `poolHost`/`poolPort` model PgBouncer, not YB smart-driver routing. - We talked to Yugabyte about this and they said that Smart Drivers would not be useful to us anyway since we connect to the cluster via PSC i.e. a single endpoint, and the Smart Driver requires direct connection to YB cluster nodes. Also, that driver is itself based on `pgx`. - iam-data-access already distinguishes `driver: postgres` vs `driver: yugabyte` in its own config; that distinction (and any YB-specific behavior) is **lost** if the connection comes purely through the LabKit `infrastructure` (Postgres) path. It is important to understand what losing this information would mean; for example, when Yugabyte is used we run a different set of database migrations than for Postgres. ## Scope of this issue 1. Both services and the migrate command read their configuration from the YAML file and the secrets file when `CONFIG_DIR` or `CONFIG_PATH` is set. 2. The database address from the Fairway `infrastructure` contract is https://gitlab.com/gitlab-org/gitlab/-/work_items/631841; the upstream gaps are https://gitlab.com/gitlab-com/gl-infra/platform/runway/fairway/-/work_items/36. IAM keeps `driver` and `ssl_mode` in its own schema either way, since Fairway's contract has no field for either, and `driver` decides which set of database migrations runs. The remaining LabKit v2 work is in https://gitlab.com/groups/gitlab-org/-/epics/23922. ## References - Caproni-demo integration MR: [caproni-demo!149](https://gitlab.com/gitlab-com/gl-infra/sandbox/caproni-demo/-/merge_requests/149) (uses inline `CONFIG_TOML` + deploy-then-read password as the interim, precisely because IAM doesn't read the `infrastructure` block). - Fairway infrastructure schema: `gitlab-com/gl-infra/platform/runway/fairway` -> `gen/infrastructure/v1`. - LabKit loader: `gitlab.com/gitlab-org/labkit/v2/infrastructure` (reads `/etc/labkit/infrastructure.yaml` + `/secrets/infrastructure/*`). - Upstream gaps in the infrastructure contract: [fairway#36](https://gitlab.com/gitlab-com/gl-infra/platform/runway/fairway/-/work_items/36). 🤖 _Drafted by Claude Code._