[pve-devel] [RFC pve-storage/proxmox-widget-toolkit/pve-manager master v2 00/10] GUI Support for Custom Storage Plugins

["Max R. Carrara" <m.carrara@proxmox.com>]

GUI Support for Custom Storage Plugins - v2
===========================================

This is a complete refresh of my previous RFC that aims to be much less
greenfield-y and instead tries to reuse as much existing code as
possible while remaining as forward-compatible as possible.

Normally I would provide a more detailed changelog under each patch, but
since so much has changed since rfc-v1, I'll instead sum up the biggest
changes here:

- The API routes are changed to be a little more flexible—routes
  regarding views etc. are completely omitted. See patches #01 and #08
  for more information.

- The schemas of plugins are returned as part of their metadata. A
  "schema" for a storage plugin in this context is simply a hashmap
  consisting of the plugin's properties' JSON schemas. See patch #02 for
  a complete and detailed explanation.

- Existing UI code concerned with building the fields of ACME DNS
  challenge plugins is factored out, made more generic and also receives
  some additional features so that it can be used in different places.
  See patches #05 and #06 for details.

- Instead of making separate versions of all of the storage-related UI
  components (panels etc.), only one new input panel is added, while the
  remaining necessary functionality is integrated into the existing
  code. See patch #09 for further details.


The Result
----------

Instead of having to provide a separate "view definition", storage
entries for custom storage plugins can now be created and edited in the
UI *without* needing to provide any extra UI / layouting hints.

So, if one now installs something like the SSHFS example plugin
[sshfs-plugin], the resulting UI is about ~80% there in terms of look
and feel compared to the forms of built-in plugins:

- Default values are displayed as grey text inside fields
- Descriptions of properties are provided as little pop-up quips when
  hovering over a field
- "fixed" properties are automatically taken into account and made
  read-only when editing a storage entry
- "sensitive" properties are automatically treated as password fields
- Optional / non-optional properties are handled
- The min- / maxLength of strings and the min- / maximum of numeric
  fields is taken into account in the UI
- The "Backup Retention" tab is automatically masked / unmasked
  depending on whether the storage plugin supports backups or not

This is mostly everything that I managed to squeeze out of the existing
SectionConfig schemas / data.

Additionally, something that's neat is that the `title` key of every
property is now used as its field's label in the UI. That means we can
provide labels for all of our built-in properties while third-party
developers may provide theirs for their own properties. As a quick
example, this is what that would look like for the SSHFS plugin
[sshfs-plugin]:

  sub properties {
      return {
          'remote-path' => {
              description => "Path on the remote filesystem used for SSHFS. Must be absolute.",
              type => 'string',
              format => 'pve-storage-path',
              title => 'Remote Path',
          },
          'sshfs-private-key' => {
              description => "The private key to use for SSHFS.",
              type => 'string',
              title => 'Private Key',
          },
      };
  }


This becomes even more flexible for third-party devs once we switch over
to property isolation—something the code in this RFC should be 100%
forward-compatible with. Then they wouldn't be bound to our provided
labels.

In terms of overall looks, the remaining 20% consist of some polish on
the frontend for the most part, but honestly, that can be done once this
RFC becomes an actual series. I felt that this was in an adequate enough
state to publish for now—please let me know what you think if you give
this RFC a spin, I'd appreciate it!

Previous Versions
-----------------

rfc-v1: https://lore.proxmox.com/pve-devel/20250908180058.530119-1-m.carrara@proxmox.com/

References
----------

[sshfs-plugin]: https://git.proxmox.com/?p=pve-storage-plugin-examples.git;a=tree;f=plugin-sshfs;h=c7543808f7226209650d1b8b6e449392bc1f0d2d;hb=refs/heads/master

Summary of Changes
------------------

pve-storage:

Max R. Carrara (5):
  api: plugins/storage: add initial routes and endpoints
  api: plugins/storage/plugin: include schema in plugin metadata
  api: plugins/storage/plugin: mark sensitive properties in schema
  api: plugins/storage/plugin: factor plugin metadata code into helper
  api: plugins/storage/plugin: add plugins' 'content' to their metadata

 src/PVE/API2/Makefile                  |   1 +
 src/PVE/API2/Plugins/Makefile          |  18 +++
 src/PVE/API2/Plugins/Storage.pm        |  54 ++++++++
 src/PVE/API2/Plugins/Storage/Makefile  |  17 +++
 src/PVE/API2/Plugins/Storage/Plugin.pm | 163 +++++++++++++++++++++++++
 5 files changed, 253 insertions(+)
 create mode 100644 src/PVE/API2/Plugins/Makefile
 create mode 100644 src/PVE/API2/Plugins/Storage.pm
 create mode 100644 src/PVE/API2/Plugins/Storage/Makefile
 create mode 100644 src/PVE/API2/Plugins/Storage/Plugin.pm


proxmox-widget-toolkit:

Max R. Carrara (2):
  utils: introduce helper function getFieldDefFromPropertySchema
  acme: use helper to construct ExtJS fields from property schemas

 src/Utils.js                 | 106 +++++++++++++++++++++++++++++++++++
 src/window/ACMEPluginEdit.js |  42 +++++---------
 2 files changed, 119 insertions(+), 29 deletions(-)


pve-manager:

Max R. Carrara (3):
  api: add API routes 'plugins' and 'plugins/storage'
  ui: storage view: display error when no editor for storage type exists
  ui: storage: add basic UI integration for custom storage plugins

 PVE/API2.pm                        |   6 ++
 PVE/API2/Makefile                  |   1 +
 PVE/API2/Plugins.pm                |  61 +++++++++++++
 www/manager6/Makefile              |   1 +
 www/manager6/dc/StorageView.js     | 132 +++++++++++++++++++++--------
 www/manager6/storage/Base.js       |   1 +
 www/manager6/storage/CustomEdit.js | 110 ++++++++++++++++++++++++
 7 files changed, 278 insertions(+), 34 deletions(-)
 create mode 100644 PVE/API2/Plugins.pm
 create mode 100644 www/manager6/storage/CustomEdit.js

-- 
2.47.3



_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel