Skip to content

ADR-002: Configuration Boundary Rule

Audience: host — see ADR index.

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

Context

The portal runs on RHEL VM, OpenShift, and future managed services — each with different config tooling (TUI, Helm, operator). A boundary rule is needed to classify settings as infrastructure (deployment tooling) vs application (portal GUI/API). Some settings (e.g., base URL) genuinely differ in ownership by surface.

Alternatives Considered

Boundary rule

Alternative Source Why rejected
Restart boundary (requires restart = infra) GitLab Portal requires restart for all changes — every setting would be "infra"
Audience boundary (platform eng vs app admin) Puppet Same admin wears both hats on VM; no clear role separation in small teams
Frequency boundary (rarely changed = infra) FortiGate Subjective — no empirical data; differs by org
Single flat classification, no exceptions — Ignores that port/TLS/base URL have different owners per surface

Base URL classification

Alternative Source Why rejected
Purely infrastructure on all surfaces — Breaks VM wizard — admin can't fix wrong auto-detected IP; OAuth callback fails
Purely application on all surfaces — Redundant on OCP where Route overrides it; managed service sets it from platform metadata

Decision

1. Domain boundary rule. "If a setting cannot have the same owner on every deployment surface, it is infrastructure." Infrastructure is pre-boot, file/Helm/operator only, and is not Day 2 web-GUI editable. Application config is post-boot, DB-backed, GUI + API editable. The setup wizard may confirm or correct a documented surface-dependent exception (rule 2); that is not Day 2 settings-page editing.

Classification Scope Storage UI
Infrastructure Pre-boot, deployment-specific Files, Helm, operator CR TUI/CLI only
Application Post-boot, deployment-agnostic DB (portal_config) Web GUI + CLI + API

2. Surface-dependent exceptions. Base URL (backend.baseUrl) is the concrete exception:

  • OpenShift: auto-derived from Route (clusterRouterBase), admin confirms/corrects in wizard Step 2
  • VM: auto-detected from host IP, admin confirms/corrects in wizard Step 2
  • Managed: determined by platform metadata, admin confirms in wizard Step 2

Settings inventory

The inventories below classify every setting. backend.baseUrl stays in the infrastructure Networking row (deployment-owned) and is the rule-2 exception: wizard Step 2 may confirm or correct it. It is not a Day 2 application setting. Row totals for application settings (30 in UI today, ~69 YAML-only, ~99 combined) are the sum of the domain counts; the earlier “~84” figure was a stale roll-up and is not used here. Summary:

Infrastructure (~31 settings) — deployment tooling only

Domain Count Examples
Database 7 backend.database.connection.host, .port, .user, .password, .ssl
Networking / TLS 6 app.baseUrl, backend.baseUrl (wizard confirm/correct only), backend.listen.port, TLS certs, clusterRouterBase
Container runtime / images 5 Container image, plugin loading mode, global.imageRegistry, Dev Tools sidecar
Auth bootstrap 3 BACKEND_SECRET, PORTAL_ADMIN_PASSWORD_HASH, auth.environment
Backstage core 5 backend.reading.allow, catalog.stitchingStrategy, catalog.orphanStrategy, permission.enabled
Environment / telemetry 2 _environment._production, SEGMENT_WRITE_KEY
Backup (RHEL only) 3 Backup enabled, schedule, retention

Application (~99 settings) — portal GUI/API + DB

Domain In UI today In YAML only Total Examples
AAP connection 5 — 5 aap.controller_url, .admin_token, .oauth_client_id, .check_ssl
AAP sync — 8 8 Orgs, org/user/team schedule, job template enabled/labels/survey
Registries 7 — 7 registries.pah_enabled, .pah_url, .pah_token, certified/validated/galaxy toggles
PAH collection sync — 4 4 Per-repo name, schedule frequency, timeout
SCM connection (x2) 18 — 18 scm.<provider>.provider_url, .token, .target_orgs, .branches, .max_depth
SCM content discovery — ~42 ~42 Per-source name/host, per-org branches/tags/crawlDepth/schedule
Portal features — 4 4 ansible.portal.onboarding.enabled, ansible.feedback.enabled
Admin state — 2 2 setupComplete, localAdminEnabled
RBAC — 3 3 permission.rbac.admin.users, .superUsers, .pluginsWithPermission
Ancillary services — 6 6 ansible.devSpaces.baseUrl, ansible.automationHub.baseUrl, ansible.creatorService.*
Totals 30 ~69 ~99

Full inventory: research doc 003 (research not published in this repository). Classification rules: research doc 001 (research not published in this repository).

flowchart TD
    A["Setting under review"] --> B{Same owner on every surface?}
    B -->|YES| C["APP config — DB-backed, GUI editable"]
    B -->|NO| D["INFRA config — file/Helm/operator only"]
    D --> E{Varies by surface?}
    E -->|YES| F["Surface-dependent exception — e.g. base URL"]
    E -->|NO| G["Pure infrastructure"]

Consequences

Positive:

  • Every contested setting resolved by one rule; works across all surfaces
  • Simplifies TUI to infrastructure-only settings

Negative:

  • Surface-dependent exceptions (port, TLS, base URL) require deployment detection logic
  • Exceptions must be clearly documented
  • Research: 001 (research not published in this repository), 003 (research not published in this repository), 005 (research not published in this repository), 006 (research not published in this repository), 007 (research not published in this repository)
  • ADR-001 (config storage), ADR-003 (wizard Step 2 uses base URL)