Skip to content

ADR-001: Configuration Storage and Precedence

Audience: host — see ADR index.

Status: Proposed Date: 2026-04-09 Deciders: Portal team

Context

The portal needs persistence for ~99 application settings across RHEL VM, OpenShift, and managed services (see ADR-002 inventory). Settings include scalars and complex nested structures. The system must define storage, nested-data handling, and precedence when file and DB both define the same key.

Alternatives Considered

Storage layer

Alternative Source Why rejected
Environment variables only — Flat strings only — no encryption, no nested structures, no arrays/objects
File-based writes to app-config.<environment>.yaml — Read-only filesystem on OCP; no locking; container restarts lose changes
Platform-native stores (ConfigMaps, Podman secrets) — Two code paths; RBAC escalation for ConfigMap writes; no transactions
External config server (Consul, Spring Cloud Config) — Extra dependency; Backstage can't hot-reload regardless; over-engineered

Nested data format

Alternative Source Why rejected
Flat dot-separated keys (repos.0.name) — Row explosion for arrays; partial writes corrupt state; hard to reconstruct
Separate JSON table — Two code paths in configTreeBuilder; same table can hold both formats

Precedence model

Alternative Source Why rejected
File wins for all keys (AWX model) AWX Unnecessary per-key checks when no file values exist (common case)
DB wins unconditionally (Puppet model) Puppet Violates admin expectation that explicit file values stick; 0/10 competitors use this
Layered conf files (Splunk 7-layer) Splunk Over-engineered for two sources; Backstage doesn't support arbitrary layers
GUI editable, reverts on restart (Jenkins) Jenkins Worst UX — changes silently disappear; universally cited as Jenkins' biggest admin pain point

Decision

1. DatabaseConfigSource as persistence layer. portal_config PostgreSQL table, injected into rootConfig at startup. Secrets encrypted with AES-256-GCM using BACKEND_SECRET. Schema via Knex migrations.

2. JSON blobs for nested config. Complex settings (PAH repos, Git sources) stored as JSON blobs per category in the same table. Simple settings remain flat key-value rows. configTreeBuilder detects and parses JSON values during assembly.

3. Non-overlapping domains with file-wins override. GUI-managed settings live in the DB. app-config.<environment>.yaml (e.g., app-config.production.yaml) covers settings the GUI does not manage. If an admin explicitly sets a GUI-managed key in the file, the file value wins and the GUI shows it read-only with a source indicator (file | database | default).

flowchart TD
    FILE["app-config.environment.yaml"] --> MERGE["ConfigSource Merger"]
    DB["portal_config DB — flat keys + JSON blobs"] --> MERGE

    MERGE --> CHECK{GUI-managed key in file?}
    CHECK -->|YES| RO["Use file value, mark read-only in GUI"]
    CHECK -->|NO| ED["Use DB value, mark editable"]
    MERGE --> FO["File-only keys: use file value directly"]

    RO --> ROOT["rootConfig — each key tagged source = file | database | default"]
    ED --> ROOT
    FO --> ROOT

    ROOT --> GUI["GUI: read-only badge on file-controlled keys"]
    ROOT --> CLI["CLI / API: source field in response"]

Consequences

Positive:

  • Single DB table across all surfaces with AES-256-GCM encryption at rest
  • JSON blobs preserve nested structure with atomic updates
  • Non-overlapping domains eliminate precedence conflicts in normal operation; file override provides GitOps safety net

Negative:

  • Bootstrap chicken-and-egg (solved via bootstrapConnection)
  • Secret rotation requires re-encryption
  • GUI must render read-only state for file-overridden keys
  • Research: 001 (research not published in this repository), 002 (research not published in this repository), 003 (research not published in this repository), 004 (research not published in this repository), 006 (research not published in this repository), 007 (research not published in this repository), 008 (research not published in this repository)
  • ADR-005 — proposed backend ownership for DatabaseConfigSource, configTreeBuilder, and the config API; these responsibilities do not belong to the existing frontend package