Skip to content

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

  1. <pluginId> — short stable slug for the portal capability (lowercase, no @ansible/ prefix, no plugin- 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.
  2. Master toggle — ansible.<pluginId>.enabled (boolean). Default false when block absent. Turns the entire capability off per ADR-010 zero-footprint behavior (all host slots, tabs, routes, and backend modules for that capability).
  3. Capability-specific keys — sibling keys under the same block (baseUrl, checkSSL, mockMode, sync schedules, etc.).
  4. Config reader — the capability's *-common package exposes get<Capability>Config(config: Config) reading ansible.<pluginId>. All artifacts for that capability use this reader — never scatter string literals. The Portal Plugin Factory scaffolding template generates it once per capability.
  5. Config schema — declared in the capability's primary config.d.ts. Portal Plugin Factory Review validates the schema exists and matches this namespace.
  6. Frontend enablement — use<Capability>Enabled() reads configApi.getOptionalBoolean('ansible.<pluginId>.enabled') ?? false as 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.
  7. 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.
  8. RHDH install vs NFS vs runtime config — dynamic-plugins.yaml decides whether a package loads. Frontend placement is NFS (./alpha extensions; optional app.extensions / app.routes.bindings). ansible.<pluginId>.* is the runtime capability toggle and settings. Do not put route/tab/sidebar registration under pluginConfig.dynamicPlugins.frontend (RHDH 2.0 Scalprum). Both install listing and the runtime enabled toggle may be required on RHDH; upstream dev app uses runtime config + static imports from packages/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.ts with ansible.<pluginId> schema and get<Capability>Config() reader per capability
  • Acceptance criteria include: config namespace compliance, capability-level enabled toggle, 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.

  • 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 enabled drives zero footprint)
  • ADR-013 (preview plugin enablement defaults)