Introduce $hints parameter to activate_volume() and map_volume(). Signed-off-by: Friedrich Weber <[email protected]> --- ApiChangeLog | 42 ++++++++++++++++++++++++++++++++++++++++++ src/PVE/Storage.pm | 4 ++-- 2 files changed, 44 insertions(+), 2 deletions(-)
diff --git a/ApiChangeLog b/ApiChangeLog index d80bfb3..508f85e 100644 --- a/ApiChangeLog +++ b/ApiChangeLog @@ -6,6 +6,48 @@ without breaking anything unaware of it.) 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: * Introduce `qemu_blockdev_options()` plugin method diff --git a/src/PVE/Storage.pm b/src/PVE/Storage.pm index 1dde2b7..ca0bf0e 100755 --- a/src/PVE/Storage.pm +++ b/src/PVE/Storage.pm @@ -41,11 +41,11 @@ use PVE::Storage::BTRFSPlugin; use PVE::Storage::ESXiPlugin; # 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. # This is like having 'current=APIVER' and age='APIAGE' in libtool, # 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']; -- 2.47.3 _______________________________________________ pve-devel mailing list [email protected] https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel
