[RFC qemu-server 4/4] remote migrate: add precondition check endpoint

[Erik Fastermann <e.fastermann@proxmox.com>]

Add a remote_migrate_vm_precondition endpoint that runs the remote
migration precondition checks without starting a migration and returns
them as a list of {severity, code, message} findings, so callers such
as the web UI can surface blockers and warnings before the user commits
to a migration.

It reuses the same validate_remote_migrate_preconditions helper the
migrate endpoint uses, so the precheck cannot drift from what is
actually enforced. The endpoint is POST rather than GET, on its own
path, to keep the remote API token out of request URLs and the access
log.

Suggested-by: Dominik Csapak <d.csapak@proxmox.com>
Signed-off-by: Erik Fastermann <e.fastermann@proxmox.com>
---
 src/PVE/API2/Qemu.pm | 156 ++++++++++++++++++++++++++++++-------------
 1 file changed, 111 insertions(+), 45 deletions(-)

diff --git a/src/PVE/API2/Qemu.pm b/src/PVE/API2/Qemu.pm
index 9b487457..ade1451e 100644
--- a/src/PVE/API2/Qemu.pm
+++ b/src/PVE/API2/Qemu.pm
@@ -1042,6 +1042,53 @@ sub assert_scsi_feature_compatibility {
     }
 }
 
+my $remote_migrate_vm_properties = {
+    additionalProperties => 0,
+    properties => {
+        node => get_standard_option('pve-node'),
+        vmid =>
+            get_standard_option('pve-vmid', { completion => \&PVE::QemuServer::complete_vmid }),
+        'target-vmid' => get_standard_option('pve-vmid', { optional => 1 }),
+        'target-endpoint' => get_standard_option('proxmox-remote', {
+                description => "Remote target endpoint",
+        }),
+        online => {
+            type => 'boolean',
+            description =>
+                "Use online/live migration if VM is running. Ignored if VM is stopped.",
+            optional => 1,
+        },
+        delete => {
+            type => 'boolean',
+            description => "Delete the original VM and related data after successful migration."
+                . " By default the original VM is kept on the source cluster in a stopped state.",
+            optional => 1,
+            default => 0,
+        },
+        'target-storage' => get_standard_option(
+            'pve-targetstorage',
+            {
+                completion => \&PVE::QemuServer::complete_migration_storage,
+                optional => 0,
+            },
+        ),
+        'target-bridge' => {
+            type => 'string',
+            description => "Mapping from source to target bridges. Providing only a single"
+                . " bridge ID maps all source bridges to that bridge. Providing the special"
+                . " value '1' will map each source bridge to itself.",
+            format => 'bridge-pair-list',
+        },
+        bwlimit => {
+            description => "Override I/O bandwidth limit (in KiB/s).",
+            optional => 1,
+            type => 'integer',
+            minimum => '0',
+            default => 'migrate limit from datacenter or storage config',
+        },
+    },
+};
+
 my sub validate_remote_migrate_preconditions {
     my ($param, $findings) = @_;
 
@@ -5837,61 +5884,80 @@ __PACKAGE__->register_method({
 });
 
 __PACKAGE__->register_method({
-    name => 'remote_migrate_vm',
-    path => '{vmid}/remote_migrate',
+    name => 'remote_migrate_vm_precondition',
+    path => '{vmid}/remote_migrate_precondition',
     method => 'POST',
     protected => 1,
     proxyto => 'node',
-    description =>
-        "Migrate virtual machine to a remote cluster. Creates a new migration task. EXPERIMENTAL feature!",
+    description => "Get preconditions for remote migration.",
     permissions => {
         check => ['perm', '/vms/{vmid}', ['VM.Migrate']],
     },
-    parameters => {
-        additionalProperties => 0,
-        properties => {
-            node => get_standard_option('pve-node'),
-            vmid =>
-                get_standard_option('pve-vmid', { completion => \&PVE::QemuServer::complete_vmid }),
-            'target-vmid' => get_standard_option('pve-vmid', { optional => 1 }),
-            'target-endpoint' => get_standard_option('proxmox-remote', {
-                    description => "Remote target endpoint",
-            }),
-            online => {
-                type => 'boolean',
-                description =>
-                    "Use online/live migration if VM is running. Ignored if VM is stopped.",
-                optional => 1,
-            },
-            delete => {
-                type => 'boolean',
-                description =>
-                    "Delete the original VM and related data after successful migration. By default the original VM is kept on the source cluster in a stopped state.",
-                optional => 1,
-                default => 0,
-            },
-            'target-storage' => get_standard_option(
-                'pve-targetstorage',
-                {
-                    completion => \&PVE::QemuServer::complete_migration_storage,
-                    optional => 0,
+    parameters => { $remote_migrate_vm_properties->%* },
+    returns => {
+        type => "array",
+        items => {
+            description => "List of findings.",
+            type => "object",
+            properties => {
+                severity => {
+                    description => "Severity of the finding.",
+                    type => 'string',
+                    enum => [qw(error warning)],
                 },
-            ),
-            'target-bridge' => {
-                type => 'string',
-                description =>
-                    "Mapping from source to target bridges. Providing only a single bridge ID maps all source bridges to that bridge. Providing the special value '1' will map each source bridge to itself.",
-                format => 'bridge-pair-list',
-            },
-            bwlimit => {
-                description => "Override I/O bandwidth limit (in KiB/s).",
-                optional => 1,
-                type => 'integer',
-                minimum => '0',
-                default => 'migrate limit from datacenter or storage config',
+                code => {
+                    description => "Machine readable code of the finding.",
+                    type => 'string',
+                    enum => [qw(
+                        load-vm-config
+                        vm-locked
+                        vm-ha-configured
+                        remote-conn
+                        target-vmid-exists
+                        storage-missing
+                        storage-no-images
+                        vm-replicated
+                        offline-migration-vm-running
+                        online-migration-vm-not-running
+                        custom-cpu-validation
+                        custom-cpu-mismatch
+                        storage-mapping
+                    )],
+                },
+                message => {
+                    description => "Human readable message.",
+                    type => 'string',
+                },
+                storage => get_standard_option(
+                    'pve-storage-id',
+                    {
+                        description => "Optional associated storage.",
+                        optional => 1,
+                    },
+                ),
             },
         },
     },
+    code => sub {
+        my ($param) = @_;
+        my $findings = [];
+        validate_remote_migrate_preconditions($param, $findings);
+        return $findings;
+    },
+});
+
+__PACKAGE__->register_method({
+    name => 'remote_migrate_vm',
+    path => '{vmid}/remote_migrate',
+    method => 'POST',
+    protected => 1,
+    proxyto => 'node',
+    description =>
+        "Migrate virtual machine to a remote cluster. Creates a new migration task. EXPERIMENTAL feature!",
+    permissions => {
+        check => ['perm', '/vms/{vmid}', ['VM.Migrate']],
+    },
+    parameters => { $remote_migrate_vm_properties->%* },
     returns => {
         type => 'string',
         description => "the task ID.",
-- 
2.47.3