pve-storage/ApiChangeLog

# API Versioning ChangeLog

Our API versioning contains an `APIVER` and an `APIAGE`.
The `APIAGE` is the number of versions we're backward compatible with. (iow.  things got added
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.

* Introduce `on_update_hook_full()` plugin method

  The original `on_update_hook()` plugin method was limited, because only the updated properties and
  values would be passed in. The new `on_update_hook_full()` plugin method also receives the current
  storage configuration and the list of which properties are to be deleted. This allows detecting
  and reacting to all changes and knowing how values changed. See also bug #6669 [0] for the initial
  motiviation. If a plugin implements `on_update_hook_full()`, that method will be called rather
  than the `on_update_hook()` method.

  [0]: https://bugzilla.proxmox.com/show_bug.cgi?id=6669

## Version 12:

* Introduce `qemu_blockdev_options()` plugin method

  Proxmox VE will switch to the more modern QEMU command line option `-blockdev` replacing `-drive`.
  With `-drive`, it was enough to specify a path, where special protocol paths like `iscsi://` were
  also supported. With `-blockdev`, the data is more structured, a driver needs to be specified
  alongside the path to an image and each driver supports driver-specific options. Most storage
  plugins should be fine using driver `host_device` in case of a block device and `file` in case of
  a file and no special options. See the default implemenation of the base plugin for guidance, also
  if the plugin uses protocol paths. Implement this method for Proxmox VE 9.

  See `$allowed_qemu_blockdev_options` in `PVE/Storage.pm` for currently allowed drivers and option.
  Feel free to request allowing more drivers or options on the pve-devel mailing list based on your
  needs.

* Introduce `rename_snapshot()` plugin method

  This method allow to rename a vm disk snapshot name to a different snapshot name.

* Introduce `volume_qemu_snapshot_method()` plugin method

  This method declares how snapshots should be handled for *running* VMs.

  This should return one of the following:
    'qemu':
      Qemu must perform the snapshot. The storage plugin does nothing.
    'storage':
      The storage plugin *transparently* performs the snapshot and the running VM does not need to
      do anything.
    'mixed': 
      For taking a snapshot: The storage performs an offline snapshot and qemu then has to reopen
      the volume.
      For removing a snapshot: One of 2 things will happen (both must be supported):
      a) Qemu will "unhook" the snapshot by moving its data into the child snapshot, and then call
         `volume_snapshot_delete` with `running` set, in which case the storage should delete only
         the snapshot without touching the surrounding snapshots.
      b) Qemu will "commit" the child snapshot to the one which is being removed, then call
         `volume_snapshot_delete()` on the child snapshot, then call `rename_snapshot()` to move the
         merged snapshot into place.
      NOTE: Storages must support using "current" as a special name in `rename_snapshot()` to
      cheaply convert a snapshot into the current disk state and back.

* Introduce `get_formats()` plugin method

  Get information about the supported formats and default format according to the current storage
  configuration. The default implemenation is backwards-compatible with previous behavior and looks
  at the definition given in the plugin data, as well as the `format` storage configuration option,
  which can override the default format. Must be implemented when the supported formats or default
  format depend on the storage configuration.

##  Version 11:

* Allow declaring storage features via plugin data

  A new `storage_has_feature()` helper function was added that checks a storage plugin's features.
  Plugins can indicate support for certain features in their `plugindata`. The first such feature is
  `backup-provider`, see below for more details. To declare support for this feature, return
  `features => { 'backup-provider' => 1 }` as part of the plugin data.

* Introduce `new_backup_provider()` plugin method

  Proxmox VE now supports a `Backup Provider API` that can be used to implement custom backup
  solutions tightly integrated in the Proxmox VE stack. See the `PVE::BackupProvider::Plugin::Base`
  module for detailed documentation. A backup provider also needs to implement an associated storage
  plugin for user-facing integration in Proxmox VE. Such a plugin needds to opt-in to the
  `backup-provider` feature (see above) and implement the new_backup_provider() method, returning a
  blessed reference to the backup provider class. The rest of the plugin methods, e.g. listing
  content, providing usage information, etc., follow the same API as usual.

* Allow declaring sensitive properties via plugin data

  A new `sensitive_properties()` helper function was added to get the list of sensitive properties
  a plugin uses via the plugin's `plugindata`. The sensitive properties are passed separately from
  other properties to the `on_add_hook()` and `on_update_hook()` methods and should not be written
  to the storage configuration file directly, but stored in the more restricted
  `/etc/pve/priv/storage` directory on the Proxmox Cluster File System. For example, to declare that
  a `ssh-private-key` property used by the plugin is sensitive, return
  `'sensitive-properties' => { 'ssh-private-key' => 1 }` as part of the plugin data. The list of
  sensitive properties was hard-coded previously, as `encryption-key`, `keyring`, `master-pubkey`,
  `password`. For backwards compatibility, this list is still used if a plugin doesn't declare its
  own sensitive properties.

##  Version 10:

* a new `rename_volume` method has been added

  Storage plugins with rename support need to enable
  the `rename` feature flag; e.g. in the `volume_has_feature` method.

* Replace `volume_snapshot_list` with `volume_snapshot_info`:

  `volume_snapshot_list` was used exclusively by replication and currently, replication is only
  allowed for the storage type `zfspool`. Thus, no external plugins should be affected by this
  change and `APIAGE` is *not* reset.

  `volume_snapshot_info` returns a hash with snapshot names as keys and `id` and `timestamp` data
  for each snapshot, rather than just an array of snaphsot names like `volume_snapshot_list` did.

* Add `blockers` parameter to `volume_rollback_is_possible`:

  The parameter *can* be used to return a list of snapshots that is currently preventing rollback.

* Replace get/update_volume_notes with generic get/update_volume_attribute

  falling back to the old implementation for notes until we reset APIAGE. the
  new method optionally also supports querying/setting a protected flag.

##  Version 9: (AGE resets to 0):

* volume_import_formats gets a new parameter *inserted*:

  Old signature:
      sub($plugin, $scfg, $storeid, $volname, $base_snapshot, $with_snapshots)
  New signature:
      sub($plugin, $scfg, $storeid, $volname, $snapshot, $base_snapshot, $with_snapshots)

  This is now the same as `volume_export_formats`.

  The same goes for calls to `PVE::Storage::volume_import_formats`, which now
  takes a `$snapshot` parameter in the same place.

* $with_snapshots *may* now be an array reference containing an ordered list of
  snapshots, but *may* also just be a boolean, and the contained list *may* be
  ignored, so it can still be treated as a boolean.