public inbox for pve-devel@lists.proxmox.com
 help / color / mirror / Atom feed
* [pve-devel] [RFC pve-storage/proxmox-widget-toolkit/pve-manager master v2 00/10] GUI Support for Custom Storage Plugins
@ 2025-11-21 16:58 Max R. Carrara
  2025-11-21 16:58 ` [pve-devel] [RFC pve-storage master v2 1/10] api: plugins/storage: add initial routes and endpoints Max R. Carrara
                   ` (9 more replies)
  0 siblings, 10 replies; 11+ messages in thread
From: Max R. Carrara @ 2025-11-21 16:58 UTC (permalink / raw)
  To: pve-devel

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

^ permalink raw reply	[flat|nested] 11+ messages in thread

end of thread, other threads:[~2025-11-21 17:00 UTC | newest]

Thread overview: 11+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2025-11-21 16:58 [pve-devel] [RFC pve-storage/proxmox-widget-toolkit/pve-manager master v2 00/10] GUI Support for Custom Storage Plugins Max R. Carrara
2025-11-21 16:58 ` [pve-devel] [RFC pve-storage master v2 1/10] api: plugins/storage: add initial routes and endpoints Max R. Carrara
2025-11-21 16:58 ` [pve-devel] [RFC pve-storage master v2 2/10] api: plugins/storage/plugin: include schema in plugin metadata Max R. Carrara
2025-11-21 16:58 ` [pve-devel] [RFC pve-storage master v2 3/10] api: plugins/storage/plugin: mark sensitive properties in schema Max R. Carrara
2025-11-21 16:58 ` [pve-devel] [RFC pve-storage master v2 4/10] api: plugins/storage/plugin: factor plugin metadata code into helper Max R. Carrara
2025-11-21 16:58 ` [pve-devel] [RFC pve-storage master v2 5/10] api: plugins/storage/plugin: add plugins' 'content' to their metadata Max R. Carrara
2025-11-21 16:58 ` [pve-devel] [RFC proxmox-widget-toolkit master v2 6/10] utils: introduce helper function getFieldDefFromPropertySchema Max R. Carrara
2025-11-21 16:58 ` [pve-devel] [RFC proxmox-widget-toolkit master v2 7/10] acme: use helper to construct ExtJS fields from property schemas Max R. Carrara
2025-11-21 16:58 ` [pve-devel] [RFC pve-manager master v2 08/10] api: add API routes 'plugins' and 'plugins/storage' Max R. Carrara
2025-11-21 16:58 ` [pve-devel] [RFC pve-manager master v2 09/10] ui: storage view: display error when no editor for storage type exists Max R. Carrara
2025-11-21 16:58 ` [pve-devel] [RFC pve-manager master v2 10/10] ui: storage: add basic UI integration for custom storage plugins Max R. Carrara

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox
Service provided by Proxmox Server Solutions GmbH | Privacy | Legal