public inbox for pve-devel@lists.proxmox.com
 help / color / mirror / Atom feed
* [pve-devel] [RFC qemu/storage/qemu-server/container/manager 00/23] backup provider API
@ 2024-07-23  9:56 Fiona Ebner
  2024-07-23  9:56 ` [pve-devel] [PATCH qemu 01/23] block/reqlist: allow adding overlapping requests Fiona Ebner
                   ` (22 more replies)
  0 siblings, 23 replies; 31+ messages in thread
From: Fiona Ebner @ 2024-07-23  9:56 UTC (permalink / raw)
  To: pve-devel

======

A backup provider needs to implement a storage plugin as well as a
backup provider plugin. The storage plugin is for integration in
Proxmox VE's front-end, so users can manage the backups via
UI/API/CLI. The backup provider plugin is for interfacing with the
backup provider's backend to integrate backup and restore with that
backend into Proxmox VE.

This is an initial draft of an API and required changes to the backup
stack in Proxmox VE to make it work. Depending on feedback from other
developers and interested parties, it can still substantially change.

======

The backup provider API is split into two parts, both of which again
need different implementations for VM and LXC guests:

1. Backup API

There hook callbacks for the start/end/abort phases of guest backups
as well as for start/end/abort phases of a whole backup job.

The backup_get_mechanism() method is used to decide on the backup
mechanism. Currently only 'nbd' for VMs and 'directory' for containers
are possible. It also let's the plugin decide whether to use a bitmap
for incremental VM backup or not.

Next, there are methods for backing up guest and firewall
configuration as well as for the backup mechanisms:

- a container filesystem using a provided directory. The directory
  contains an unchanging copy of the container's file system.

- a VM disk using a provided NBD export. The export is an unchanging
  copy of the VM's disk. Either the full image, or in case a bitmap is
  used, the dirty parts of the image since the last time the bitmap
  was used for a successful backup. Reading outside of the dirty parts
  will result in an error. After backing up each part of the disk, it
  should be discarded in the export to avoid unnecessary space usage
  on the Proxmox VE side (there is an associated fleecing image).

Finally, some helpers like getting the provider name or volume ID for
the backup target, as well as for handling the backup log.

2. Restore API

The restore_get_mechanism() method is used to decide on the restore
mechanism. Currently, only 'qemu-img' for VMs and 'directory' and
'tar' for containers are possible.

Next, methods for extracting the guest and firewall configuration and
the implementations of the restore mechanism. It is enough to
implement one restore mechanism per guest type of course:

- for VMs, with the 'qemu-img' mechanism, the backup provider gives a
  path to the disk image that will be restore. The path should be
  something qemu-img can deal with, e.g. can also be an NBD URI.

- for containers, with the 'directory' mechanism, the backup provider
  gives the path to a directory with the full filesystem structure of
  the container.

- for containers, with the 'tar' mechanism, the backup provider gives
  the path to a (potentially compressed) tar archive with the full
  filesystem structure of the container.

For VMs, there also is a restore_qemu_get_device_info() helper
required, to get the disks included in the backup and their sizes.

See the PVE::BackupProvider::Plugin module for the full API
documentation.

======

This series adapts the backup stack in Proxmox VE to allow using the
above API. For QEMU, backup access setup and teardown QMP commands are
implemented to be able to provide access to a consistent disk state to
the backup provider.

The series also provides an example implementation for a backup
provider as a proof-of-concept, exposing the different features.

======

Open questions:

Should the backup provider plugin system also follow the same API
age+version schema with a Custom/ directory for external plugins
derived from the base plugin?

Should there also be hook callbacks (i.e. start/end/abort) for
restore?

Should the bitmap action be passed directly to the backup provider?
I.e. have 'not-used', 'not-used-removed', 'new', 'used', 'invalid',
instead of only 'none', 'new' and 'reuse'. It makes API slightly more
complicated. Is there any situation where backup provider could care
if bitmap is new, because it was the first or bitmap is new because
previous was invalid? Both cases require the backup provider to do a
full backup.

======

The patches marked as PATCH rather than RFC can make sense
independently, with QEMU patches 02 and 03 having been sent already
before (touching same code, so included here):

https://lore.proxmox.com/pve-devel/20240625133551.210636-1-f.ebner@proxmox.com/#r

======

Feedback is very welcome, especially from people wishing to implement
such a backup provider plugin! Please tell me what issues you see with
the proposed API, what would and wouldn't work from your perspective?

======

Dependencies: pve-manager, pve-container and qemu-server all depend on
new libpve-storage-perl. pve-manager also build-depends on the new
libpve-storage-perl for its tests. To keep things clean, pve-manager
should also depend on new pve-container and qemu-server.

In qemu-server, there is no version guard added yet, as that depends
on the QEMU version the feature will land in.

======


qemu:

Fiona Ebner (9):
  block/reqlist: allow adding overlapping requests
  PVE backup: fixup error handling for fleecing
  PVE backup: factor out setting up snapshot access for fleecing
  PVE backup: save device name in device info structure
  PVE backup: include device name in error when setting up snapshot
    access fails
  PVE backup: add target ID in backup state
  PVE backup: get device info: allow caller to specify filter for which
    devices use fleecing
  PVE backup: implement backup access setup and teardown API for
    external providers
  PVE backup: implement bitmap support for external backup access

 block/copy-before-write.c |   3 +-
 block/reqlist.c           |   2 -
 pve-backup.c              | 619 +++++++++++++++++++++++++++++++++-----
 pve-backup.h              |  16 +
 qapi/block-core.json      |  58 ++++
 system/runstate.c         |   6 +
 6 files changed, 633 insertions(+), 71 deletions(-)
 create mode 100644 pve-backup.h


storage:

Fiona Ebner (3):
  plugin: introduce new_backup_provider() method
  extract backup config: delegate to backup provider if there is one
  add backup provider example

 src/PVE/BackupProvider/DirectoryExample.pm    | 533 ++++++++++++++++++
 src/PVE/BackupProvider/Makefile               |   6 +
 src/PVE/BackupProvider/Plugin.pm              | 343 +++++++++++
 src/PVE/Makefile                              |   1 +
 src/PVE/Storage.pm                            |  22 +-
 .../Custom/BackupProviderDirExamplePlugin.pm  | 289 ++++++++++
 src/PVE/Storage/Custom/Makefile               |   5 +
 src/PVE/Storage/Makefile                      |   1 +
 src/PVE/Storage/Plugin.pm                     |  15 +
 9 files changed, 1213 insertions(+), 2 deletions(-)
 create mode 100644 src/PVE/BackupProvider/DirectoryExample.pm
 create mode 100644 src/PVE/BackupProvider/Makefile
 create mode 100644 src/PVE/BackupProvider/Plugin.pm
 create mode 100644 src/PVE/Storage/Custom/BackupProviderDirExamplePlugin.pm
 create mode 100644 src/PVE/Storage/Custom/Makefile


qemu-server:

Fiona Ebner (7):
  move nbd_stop helper to QMPHelpers module
  backup: move cleanup of fleecing images to cleanup method
  backup: cleanup: check if VM is running before issuing QMP commands
  backup: allow adding fleecing images also for EFI and TPM
  backup: implement backup for external providers
  restore: die early when there is no size for a device
  backup: implement restore for external providers

 PVE/API2/Qemu.pm             |  33 +++++-
 PVE/CLI/qm.pm                |   3 +-
 PVE/QemuServer.pm            | 139 +++++++++++++++++++++-
 PVE/QemuServer/QMPHelpers.pm |   6 +
 PVE/VZDump/QemuServer.pm     | 218 +++++++++++++++++++++++++++++++----
 5 files changed, 365 insertions(+), 34 deletions(-)


container:

Fiona Ebner (2):
  backup: implement backup for external providers
  backup: implement restore for external providers

 src/PVE/LXC/Create.pm | 143 ++++++++++++++++++++++++++++++++++++++++++
 src/PVE/VZDump/LXC.pm |  20 +++++-
 2 files changed, 162 insertions(+), 1 deletion(-)


manager:

Fiona Ebner (2):
  ui: backup: also check for backup subtype to classify archive
  backup: implement backup for external providers

 PVE/VZDump.pm                      | 43 +++++++++++++++++++++++++-----
 test/vzdump_new_test.pl            |  3 +++
 www/manager6/Utils.js              | 10 ++++---
 www/manager6/grid/BackupView.js    |  4 +--
 www/manager6/storage/BackupView.js |  4 +--
 5 files changed, 50 insertions(+), 14 deletions(-)


Summary over all repositories:
  27 files changed, 2423 insertions(+), 122 deletions(-)

-- 
Generated by git-murpp 0.5.0


_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel


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

end of thread, other threads:[~2024-07-26 12:45 UTC | newest]

Thread overview: 31+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2024-07-23  9:56 [pve-devel] [RFC qemu/storage/qemu-server/container/manager 00/23] backup provider API Fiona Ebner
2024-07-23  9:56 ` [pve-devel] [PATCH qemu 01/23] block/reqlist: allow adding overlapping requests Fiona Ebner
2024-07-23  9:56 ` [pve-devel] [PATCH qemu 02/23] PVE backup: fixup error handling for fleecing Fiona Ebner
2024-07-23  9:56 ` [pve-devel] [PATCH qemu 03/23] PVE backup: factor out setting up snapshot access " Fiona Ebner
2024-07-23  9:56 ` [pve-devel] [PATCH qemu 04/23] PVE backup: save device name in device info structure Fiona Ebner
2024-07-23  9:56 ` [pve-devel] [PATCH qemu 05/23] PVE backup: include device name in error when setting up snapshot access fails Fiona Ebner
2024-07-23  9:56 ` [pve-devel] [RFC qemu 06/23] PVE backup: add target ID in backup state Fiona Ebner
2024-07-23  9:56 ` [pve-devel] [RFC qemu 07/23] PVE backup: get device info: allow caller to specify filter for which devices use fleecing Fiona Ebner
2024-07-23  9:56 ` [pve-devel] [RFC qemu 08/23] PVE backup: implement backup access setup and teardown API for external providers Fiona Ebner
2024-07-23  9:56 ` [pve-devel] [RFC qemu 09/23] PVE backup: implement bitmap support for external backup access Fiona Ebner
2024-07-23  9:56 ` [pve-devel] [RFC storage 10/23] plugin: introduce new_backup_provider() method Fiona Ebner
2024-07-25  9:48   ` Max Carrara
2024-07-25 13:11     ` Fiona Ebner
2024-07-25 13:25       ` Fiona Ebner
2024-07-25 15:32       ` Max Carrara
2024-07-26  9:52         ` Fiona Ebner
2024-07-26 12:02           ` Max Carrara
2024-07-26 12:45             ` Fiona Ebner
2024-07-23  9:56 ` [pve-devel] [RFC storage 11/23] extract backup config: delegate to backup provider if there is one Fiona Ebner
2024-07-23  9:56 ` [pve-devel] [POC storage 12/23] add backup provider example Fiona Ebner
2024-07-23  9:56 ` [pve-devel] [PATCH qemu-server 13/23] move nbd_stop helper to QMPHelpers module Fiona Ebner
2024-07-23  9:56 ` [pve-devel] [PATCH qemu-server 14/23] backup: move cleanup of fleecing images to cleanup method Fiona Ebner
2024-07-23  9:56 ` [pve-devel] [PATCH qemu-server 15/23] backup: cleanup: check if VM is running before issuing QMP commands Fiona Ebner
2024-07-23  9:56 ` [pve-devel] [RFC qemu-server 16/23] backup: allow adding fleecing images also for EFI and TPM Fiona Ebner
2024-07-23  9:56 ` [pve-devel] [RFC qemu-server 17/23] backup: implement backup for external providers Fiona Ebner
2024-07-23  9:56 ` [pve-devel] [PATCH qemu-server 18/23] restore: die early when there is no size for a device Fiona Ebner
2024-07-23  9:56 ` [pve-devel] [RFC qemu-server 19/23] backup: implement restore for external providers Fiona Ebner
2024-07-23  9:56 ` [pve-devel] [RFC container 20/23] backup: implement backup " Fiona Ebner
2024-07-23  9:56 ` [pve-devel] [RFC container 21/23] backup: implement restore " Fiona Ebner
2024-07-23  9:56 ` [pve-devel] [PATCH manager 22/23] ui: backup: also check for backup subtype to classify archive Fiona Ebner
2024-07-23  9:56 ` [pve-devel] [RFC manager 23/23] backup: implement backup for external providers Fiona Ebner

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