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 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.