ADR-011: Portal Plugin Configuration Namespace¶
Audience: common — see ADR index.
Status: Accepted
Date: 2026-07-01
Deciders: Portal team
Scope: Backstage plugins created using the Portal Plugin Factory framework — runtime app-config keys for portal capabilities delivered by factory Backstage plugins.
Context¶
The Portal Plugin Factory framework enables product teams to contribute Backstage plugins in ansible-backstage-plugins. Those artifacts implement portal capabilities — cohesive user-facing features (for example content-quality signals on Git Repositories) that may span a frontend plugin, *-common contracts, and an optional backend module.
Runtime configuration is keyed by capability, not by individual plugin artifact. Each capability needs settings such as feature toggles, service URLs, TLS options, and dev-only flags. Without a namespace convention, contributing teams invent ad-hoc config paths — some use top-level keys (quality.enabled), some nest under ansible.* (ansible.feedback.enabled, ansible.devspaces.baseUrl), and some copy RHDH 2.0 Scalprum keys (pluginConfig.dynamicPlugins.frontend).
The Portal Plugin Factory Review acceptance criteria require namespace compliance. A single convention lets the portal admin UI (ADR-003), the config schema validation, and the scaffolding template all rely on a predictable config shape.
ADR-010 requires a master enabled toggle with zero-footprint semantics for each portal capability — not a separate toggle per Backstage plugin package. Disabling ansible.<pluginId>.enabled must remove every surface and backend route that capability contributes. That toggle must live at a predictable path so enabled hooks, config readers, and the admin settings UI all follow one pattern.
RHDH 2.1 install and NFS frontend wiring are separate from runtime config. dynamic-plugins.yaml controls which packages load. Plugins declare NFS extensions from ./alpha; operators override with app.extensions. Runtime config and deployment wiring must not be conflated.
Alternatives Considered¶
| Alternative | Why rejected |
|---|---|
Top-level plugin slug (quality.enabled, compliance.enabled) |
No shared prefix; collides with Backstage core keys; admin UI cannot enumerate plugin config |
Manifest package name as key (ansible.plugin-backstage-quality.enabled) |
Verbose; duplicates RHDH manifest keys; poor admin UX; not intuitive for contributing teams |
| Per-plugin arbitrary paths | Each team invents its own shape; Plugin Factory cannot teach one pattern; scaffolding template cannot generate config |
Decision¶
All portal capability runtime configuration lives under ansible.<pluginId>.*. <pluginId> names the portal capability registered at Propose phase — the combined feature users and operators enable — even when multiple Backstage plugin artifacts implement it. This applies to factory Backstage plugin capabilities and base RHAAP plugin capabilities. It does not replace RHDH install entries in dynamic-plugins.yaml or NFS extension configuration under app.* (ADR-010 rule 4).
Namespace rules¶
<pluginId>— short stable slug for the portal capability (lowercase, no@ansible/prefix, noplugin-prefix). Registered during Portal Plugin Factory Phase 1 (Propose). One capability, one config block — regardless of how many frontend/backend artifacts implement it. Examples:quality,feedback,devspaces,compliance,workflows.- Master toggle —
ansible.<pluginId>.enabled(boolean). Defaultfalsewhen block absent. Turns the entire capability off per ADR-010 zero-footprint behavior (all host slots, tabs, routes, and backend modules for that capability). - Capability-specific keys — sibling keys under the same block (
baseUrl,checkSSL,mockMode, sync schedules, etc.). - Config reader — the capability's
*-commonpackage exposesget<Capability>Config(config: Config)readingansible.<pluginId>. All artifacts for that capability use this reader — never scatter string literals. The Portal Plugin Factory scaffolding template generates it once per capability. - Config schema — declared in the capability's primary
config.d.ts. Portal Plugin Factory Review validates the schema exists and matches this namespace. - Frontend enablement —
use<Capability>Enabled()readsconfigApi.getOptionalBoolean('ansible.<pluginId>.enabled') ?? falseas a rendering guard. This hook alone does not disable a registered NFS page, tab, or route. Capability activation must also follow the NFS enforcement contract below. - Legacy migration — existing top-level plugin slug keys may be read as fallback during transition with a deprecation comment pointing to this ADR. New plugins must use
ansible.<pluginId>.*from day one. - RHDH install vs NFS vs runtime config —
dynamic-plugins.yamldecides whether a package loads. Frontend placement is NFS (./alphaextensions; optionalapp.extensions/app.routes.bindings).ansible.<pluginId>.*is the runtime capability toggle and settings. Do not put route/tab/sidebar registration underpluginConfig.dynamicPlugins.frontend(RHDH 2.0 Scalprum). Both install listing and the runtimeenabledtoggle may be required on RHDH; upstream dev app uses runtime config + static imports frompackages/app.
NFS enforcement contract¶
The capability toggle is a target requirement across the capability's artifacts, not an automatic property of Backstage's config API. A contributor must inventory its NFS extensions, backend routes, scheduled tasks, and startup side effects, and document how each becomes inactive when the capability is disabled or its block is absent.
For NFS, the host composition must map the capability toggle to extension enablement before the affected extensions become active. Disabled pages must not remain mounted as blank routes, and disabled tabs or host slots must not remain registered merely because their React component returns null. Backend artifacts must skip capability routes, scheduled work, and other capability-local registrations when disabled; hiding frontend UI does not disable backend access.
This ADR does not claim that a generic config-to-NFS-extension mapping is already implemented. Until that mapping exists for a capability, its deployment must explicitly disable every affected extension through app.extensions, in addition to setting the runtime toggle, and document the extension IDs. Treat missing enforcement as a host integration gap; do not advertise one-toggle zero footprint based only on a rendering hook. Extension overrides do not replace backend authorization or backend enablement checks.
Verification must inspect the effective app tree and directly request disabled routes/endpoints, as well as checking visible UI and console errors. The capability's enabled boolean must be frontend-visible in its config schema; secrets must remain backend-only.
Standard key reference¶
| Key | Required | Purpose |
|---|---|---|
enabled |
Yes | Master capability toggle (ADR-010 zero footprint) |
baseUrl |
When plugin calls external service | Service endpoint |
checkSSL |
Optional | TLS verification (default true in prod) |
mockMode |
Optional, dev only | Fixture data without external service |
Example (multiple plugins)¶
ansible:
quality:
enabled: true
baseUrl: http://localhost:8080
checkSSL: false
compliance:
enabled: true
baseUrl: https://compliance.example.com
feedback:
enabled: true
Plugin Factory integration¶
- Scaffolding template generates
config.d.tswithansible.<pluginId>schema andget<Capability>Config()reader per capability - Acceptance criteria include: config namespace compliance, capability-level
enabledtoggle, zero-footprint verification across all artifacts for that capability - Admin UI (ADR-003) can enumerate capability config by scanning
ansible.*keys
Verification¶
| Test | Expected |
|---|---|
ansible.<pluginId>.enabled: false + restart |
ADR-010 zero footprint for that capability (all artifacts) |
| Block absent | Config reader returns enabled: false defaults |
| Admin sets key in DB (ADR-001) | Same path; GUI/API use ansible.<pluginId>.* |
| New capability via scaffolding template | Generated code uses ansible.<pluginId>.* |
Consequences¶
Positive: One pattern for all contributing teams. Scaffolding template, acceptance criteria, and admin UI all rely on predictable paths. Plugin Factory can validate namespace compliance automatically.
Negative: Legacy top-level keys need a migration period. Contributing teams must register the capability pluginId during proposal phase.
Related¶
- Portal Plugin Factory framework
- ADR-001 (storage/precedence), ADR-002 (infra vs app boundary)
- ADR-003 (portal admin UI)
- ADR-005 (deployment / dynamic plugins)
- ADR-010 (composability — capability-level
enableddrives zero footprint) - ADR-013 (preview plugin enablement defaults)