[3.3] Complete dynamic plugin management and configurable plugin settings

[KomachiSion]

Motivation

Follow-up of #14049.

#14049 introduced the foundation for unified plugin discovery, plugin state visibility, plugin state APIs, and a console page. The current code already has the basic building blocks:

• PluginManager discovers PluginProvider implementations, tracks loaded/enabled state, persists state/config, and synchronizes state/config changes across the cluster.
• PluginConfigSpec and ConfigItemDefinition let a plugin expose configuration metadata and receive applyConfig(...).
• /v3/admin/core/plugin/* and /v3/console/plugin/* expose list, detail, status, config, and availability operations.
• The plugin spec defines plugin identity, loaded/enabled state, configurable plugins, critical plugins, and cluster-level state/config changes.

However, the 3.2-level capability is still not a complete operational loop for 3.3. In practice, plugin management still has several gaps:

1. The console experience is still mainly about visibility and basic status display. The new console page can list plugins and toggle non-critical/non-exclusive plugins, but it does not yet fetch full plugin config definitions, edit plugin configuration, distinguish editable and read-only config items, or show the effective configuration source.
2. Plugin configuration keys are not yet standardized across plugin types. Some plugin families use domain-specific formats, such as nacos.plugin.visibility.{serviceName}.*, while others use their own historical configuration prefixes. This makes it hard for Nacos to load plugin configuration from files in a uniform way and pass the normalized configuration into plugin implementations.
3. The current config metadata model is too small for safe console editing. ConfigItemDefinition can describe key/name/type/default/required/enum, but it cannot express whether a value is runtime-editable, read-only, sensitive, node-scoped, cluster-scoped, requires restart, or has validation constraints beyond "required".
4. Dynamic enable/disable semantics are not consistently defined per plugin type. Critical and exclusive plugins are handled at the core level, but each domain manager still needs clear rules about whether runtime state changes are supported and how the disabled state affects request handling.

The goal of this issue is to make plugin management usable as an initial 3.3 feature, not only a discovery page.

Desired Capability

1. Define a unified plugin configuration model

Add a documented, stable convention for plugin configuration loaded from Nacos configuration files, for example a normalized plugin-id based format:

nacos.plugin.{pluginType}.{pluginName}.{configKey}=...

The exact format should be decided in the design, but it should satisfy:

• pluginType + pluginName can be mapped to a stable pluginId.
• Nacos can collect all configuration for a plugin during startup and pass it to the plugin implementation through a common mechanism.
• Existing historical configuration keys remain compatible, with a clear migration or alias rule.
• File/default configuration and runtime persisted configuration have a deterministic precedence rule.
• The effective configuration can be exposed through the plugin detail API without leaking sensitive values.

2. Extend plugin config metadata for console-safe editing

Extend ConfigItemDefinition or introduce a compatible v2 metadata model that can describe at least:

• whether the item is editable from the console;
• whether the item is sensitive and should be masked;
• whether the item can be changed at runtime or requires restart;
• whether the item is local-node scoped or cluster scoped;
• validation constraints such as min/max, pattern, enum, or custom validation message;
• current value source, such as file/default/runtime override, if feasible.

The console should use this metadata instead of guessing which fields are safe to edit.

3. Complete runtime plugin switch semantics

For each plugin type, clarify whether the plugin is:

• switchable at runtime;
• critical and cannot be disabled;
• exclusive, where only one implementation can be active;
• chain/broadcast style, where multiple enabled plugins can participate;
• restart-required for certain changes.

Domain managers should consistently use PluginStateCheckerHolder or the corresponding plugin manager state when deciding whether a loaded plugin can participate in request handling.

Cluster-level changes should remain synchronized by default. localOnly should be treated as a diagnostic/emergency option and should be clearly exposed as such.

4. Complete console support

The 3.3 console should provide a complete first-stage plugin management workflow:

• list plugins by type and state;
• show plugin detail, critical/exclusive/configurable status, and node availability;
• enable/disable non-critical runtime-switchable plugins with confirmation and error handling;
• fetch config definitions and current effective config;
• edit only runtime-editable config items;
• mask sensitive values;
• show restart-required or read-only items as non-editable;
• refresh plugin state after update.

5. Update specs and tests

The implementation should update the plugin spec and affected plugin type specs.

Testing should cover:

• startup config loading and normalization;
• compatibility with existing plugin-specific config keys;
• config validation and applyConfig(...) behavior;
• cluster sync for state/config changes;
• non-editable/sensitive/restart-required metadata serialization;
• console API behavior for detail, status, config update, and availability;
• at least one real built-in plugin using the new config definition path.

If any HTTP API contract changes or new endpoints are added, the corresponding OpenAPI integration test scenario matrix and coverage registry should be updated according to the repository API IT rules.

Non-goals

• This issue does not require every existing plugin to become fully runtime-configurable in one step.
• This issue should not remove existing historical plugin configuration keys without a compatibility plan.
• This issue should not make critical runtime dependencies disableable.

Acceptance Criteria

• A spec-backed unified plugin configuration format is available for 3.3.
• Plugin implementations have a common way to receive startup and runtime configuration.
• Console API responses expose enough metadata for safe config editing.
• The new console can complete list, detail, runtime switch, and editable config update flows.
• Sensitive/read-only/restart-required configuration items are handled safely.
• Built-in plugin behavior remains backward compatible with existing deployments.

[KomachiSion]

assign myself first, If anyone want to do this, prefer to assign to volunteer.

[KomachiSion]

I did a first round of design review for this issue. The main direction is to
build unified plugin config management in a compatible way, without replacing
the existing plugin model or breaking current plugin management APIs.

Goals

The proposal is to gradually support:

• effective plugin config view
• config source metadata
• localOnly emergency override
• runtime/restart effect mode
• sensitive value masking
• historical key compatibility and migration hints

Main Design

1. Keep the existing model and extend it compatibly

Continue to use the existing PluginConfigSpec, ConfigItemDefinition and
PluginDetailVO model. Do not introduce SpecV2.

ConfigItemDefinition can be extended with metadata such as:

• aliases
• sensitive
• scope
• effectMode

PluginDetailVO can add configValueMetas to describe the source and
overridden state of each effective config item. Existing fields should be kept
and their meaning should not be changed incompatibly.

2. Normalize plugin config keys

ConfigItemDefinition.key should represent the canonical item key inside the
plugin, for example token.secret.key.

The normalized static config key should be:

nacos.plugin.{pluginType}.{pluginName}.{itemKey}

Historical keys can be declared as aliases. plugin-configs.json and
localOnly memory storage should only store pluginId + itemKey, not full keys
or alias keys.

3. Use a unified source priority

The effective config should be resolved by a common resolver with this priority:

LOCAL_ONLY > RUNTIME_PERSISTED > STATIC > DEFAULT

Where:

• STATIC means values from application.properties, environment variables,
  JVM parameters, Spring parameters, etc.
• RUNTIME_PERSISTED means cluster-level runtime override, currently persisted
  as the final override map in plugin-configs.json.
• LOCAL_ONLY means node-local emergency/debug override.
• DEFAULT means the default value from the config definition.

4. Keep API changes compatible

The first phase should reuse existing detail/config APIs instead of adding a
new GET config or DELETE config API:

• GET /v3/admin/core/plugin/detail
• GET /v3/console/plugin
• PUT /v3/admin/core/plugin/config
• PUT /v3/console/plugin/config

GET detail can return the effective config and add configValueMetas for
source/overridden metadata.

PUT config should keep the current full override map update/replace semantic.
If a caller wants to remove one runtime/localOnly override, it can submit a
complete override map without that key. The existing localOnly parameter is
kept. Key normalization and effectMode checks are server-side logic, not new
API parameters.

5. Use effectMode to control runtime update behavior

Each config item can be marked as:

• RUNTIME: can be updated through the runtime API and applied to the plugin.
• RESTART: shown as read-only at runtime; console should indicate that the
  config file needs to be changed and the server restarted.

Common validation should stay lightweight, such as required/type/enum,
effectMode check and sensitive placeholder protection. Complex validation
should stay in the plugin implementation or adapter apply logic.

6. Reuse the same resolver/applier for startup and runtime updates

Startup initialization, static config refresh, runtime persisted update and
localOnly update should reuse the same resolver/applier flow:

1. Resolve all sources into an effective config map.
2. Generate value metadata.
3. Apply the config according to the trigger scenario and effectMode.

At startup, all fields can be applied. At runtime, only RUNTIME fields should
be applied.

7. Clarify plugin selection and config boundaries

Plugin selection/routing should eventually be managed by the unified plugin
state. Historical selection keys should only be compatibility inputs and
migration hints, with the new unified state taking precedence.

Module-level switches, plugin selection keys and plugin implementation private
configs should be clearly separated. For example, auth module enablement,
system type, identity config and auth:nacos plugin private config should not
be mixed into the same layer.

Suggested PR Split

Considering the current CI queue time, I suggest a small number of larger but
self-contained PRs:

1. Spec and model contract
   Update specs and extend ConfigItemDefinition / PluginDetailVO with
   compatible metadata fields.

2. Read-only effective detail flow
   Add key resolver, config resolver, config sources, masking and basic
   checking, then expose effective config and value metadata through existing
   detail APIs.

3. PUT config update and startup reuse
   Connect the existing PUT config path and startup initialization to the
   unified resolver/applier, including runtime persisted override, localOnly,
   effectMode check and apply failure handling.

4. Plugin-family metadata and migration
   Add metadata adapters for major plugin families, clarify config boundaries,
   fix plugin state/selection behavior, and add migration hints for historical
   aliases.

5. Console UI
   Implement the console UI separately based on config, configDefinitions
   and configValueMetas, including source display, sensitive masking,
   runtime/restart hints and localOnly warnings.

This keeps the first step focused on a compatible unified model and observable
effective config view, then gradually opens runtime-update capability for fields
that are safe to apply dynamically.