yesBad/pve-storage
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

plugin api: bump api version and age

Browse Source 
Introduce $hints parameter to activate_volume() and map_volume().

Signed-off-by: Friedrich Weber <f.weber@proxmox.com>
Link: https://lore.proxmox.com/20251031103709.60233-3-f.weber@proxmox.com
This commit is contained in:
Friedrich Weber
2025-10-31 11:36:09 +01:00
committed by Thomas Lamprecht
parent e9573e1db5
commit 8818ff0d1d
2 changed files with 44 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

42
ApiChangeLog
View File

@ -6,6 +6,48 @@ without breaking anything unaware of it.)
Future changes should be documented in here. Future changes should be documented in here.
## Version 13:
* Add new parameter $hints to the `activate_volume()` and `map_volume()` plugin methods
Old signature of `activate_volume()`:
sub($plugin, $storeid, $scfg, $volname, $snapname, $cache)
New signature of `activate_volume()`:
sub($plugin, $storeid, $scfg, $volname, $snapname, $cache, $hints)
Old signature of `map_volume()`:
sub($plugin, $storeid, $scfg, $volname, $snapname)
New signature of `map_volume()`:
sub($plugin, $storeid, $scfg, $volname, $snapname, $hints)
Hints are a mechanism that allows the upper layers to optionally pass down well-defined
information to the storage plugins on volume activation/mapping. The storage plugin can make
adjustments to its volume activation/mapping based on the hints (we call this "applying" the
hint).
If the new parameter $hints is defined, it is a hash reference that adheres to the schema
`PVE::Storage::Plugin::$hints_format` (verified by caller). The supported hints are specified in
`PVE::Storage::Plugin::$hints_properties` and may be extended in the future. It is not guaranteed
that the volume is inactive when `activate_volume()` or `map_volume()` are called, and it is not
guaranteed that hints are passed on every storage activation. Hints may be passed at additional
storage activation call sites in the future without an API version bump.
It can happen a volume is already active but applying the hint would require unmapping the volume
and mapping it again with the hint applied. To cover such cases, the Boolean hint
'plugin-may-deactivate-volume' denotes whether unmapping the volume is currently safe. Only if
this hint is true, the plugin may deactivate the volume and map it again with the hint applied.
Hints may be added in the future without an API version bump. Plugins may call
`PVE::Storage::Plugin::is_hint_supported()` to check whether a specific hint is supported.
Plugins that do not require hints can safely ignore the additional parameter.
## Version 12: ## Version 12:
* Introduce `qemu_blockdev_options()` plugin method * Introduce `qemu_blockdev_options()` plugin method

4
src/PVE/Storage.pm
View File

@ -41,11 +41,11 @@ use PVE::Storage::BTRFSPlugin;
use PVE::Storage::ESXiPlugin; use PVE::Storage::ESXiPlugin;
# Storage API version. Increment it on changes in storage API interface. # Storage API version. Increment it on changes in storage API interface.
use constant APIVER => 12; use constant APIVER => 13;
# Age is the number of versions we're backward compatible with. # Age is the number of versions we're backward compatible with.
# This is like having 'current=APIVER' and age='APIAGE' in libtool, # This is like having 'current=APIVER' and age='APIAGE' in libtool,
# see https://www.gnu.org/software/libtool/manual/html_node/Libtool-versioning.html # see https://www.gnu.org/software/libtool/manual/html_node/Libtool-versioning.html
use constant APIAGE => 3; use constant APIAGE => 4;
our $KNOWN_EXPORT_FORMATS = ['raw+size', 'tar+size', 'qcow2+size', 'vmdk+size', 'zfs', 'btrfs']; our $KNOWN_EXPORT_FORMATS = ['raw+size', 'tar+size', 'qcow2+size', 'vmdk+size', 'zfs', 'btrfs'];