Merge pull request #112910 from danielclowers/CNV-77510

CNV-77510: Document volume restore policy feature for VM snapshots

Author: danielclowers

modules/virt-cloning-vm-web.adoc

@@ -18,5 +18,8 @@ You can clone an existing VM by using the web console.
 Alternatively, access the same menu in the tree view by right-clicking the VM.
 . Select *Clone*.
 . On the *Clone VirtualMachine* page, enter the name of the new VM.
-. (Optional) Select the *Start cloned VM* checkbox to start the cloned VM.
+. Optional: Select the *Start cloned VM* checkbox to start the cloned VM.
+. Optional: In the *Volume name policy* section, select how cloned persistent volume claims (PVCs) are named:
+** *Randomize names* - The cloned PVC names are randomly generated. This is the default setting.
+** *Prefix target name* - The cloned PVC names use the target VM name as a prefix.
 . Click *Clone*.

modules/virt-creating-vm-from-snapshot-web.adoc

@@ -16,6 +16,9 @@ You can create a new VM by copying an existing snapshot.
 . Click the *Snapshots* tab.
 . Click the Options menu {kebab} for the snapshot you want to copy.
 . Select *Create VirtualMachine*.
-. Enter the name of the virtual machine.
-. (Optional) Select the *Start this VirtualMachine after creation* checkbox to start the new virtual machine.
+. Enter the name of the VM.
+. Optional: Select the *Start this VM after creation* checkbox to start the new VM.
+. Optional: In the *Volume name policy* section, select how cloned persistent volume claims (PVCs) are named:
+** *Randomize names* - The cloned PVC names are randomly generated. This is the default setting.
+** *Prefix target name* - The cloned PVC names use the target VM name as a prefix.
 . Click *Create*.

modules/virt-restoring-vm-from-snapshot-cli.adoc

@@ -21,6 +21,11 @@ You can restore an existing virtual machine (VM) to a previous configuration by
 ** `WaitGracePeriod 5` - The restore process waits for a set amount of time, in minutes, for the VM to be ready. This is the default setting, with the default value set to 5 minutes.
 ** `WaitEventually` - The restore process waits indefinitely for the VM to be ready.
 
+* Optional: To control how restored persistent volume claims (PVCs) are named, you can set the `volumeRestorePolicy` parameter to one of the following values:
+** `PrefixTargetName` - The restored PVC names use the target VM name as a prefix: `<vm_name>-<volume_name>`. This is the default setting.
+** `RandomizeNames` - The restored PVC names are randomly generated: `restore-<uid>-<volume_name>`.
+** `InPlace` - The restored PVCs overwrite the original PVCs. The original PVCs are deleted if they exist, and new PVCs are created with the same names.
+
 .Procedure
 
 . Create a YAML file to define a `VirtualMachineRestore` object that specifies the name of the VM you want to restore and the name of the snapshot to be used as the source as in the following example:
@@ -37,7 +42,42 @@ spec:
     kind: VirtualMachine
     name: <vm_name>
   virtualMachineSnapshotName: <snapshot_name>
+  volumeRestorePolicy: PrefixTargetName
+----
++
+Where:
++
+** `volumeRestorePolicy`: Optional. The volume restore policy determines how restored PVCs are named. Valid values are `PrefixTargetName` (default), `RandomizeNames`, or `InPlace`.
+
+. Optional: To customize the names, labels, and annotations of individual restored persistent volume claims (PVCs), add the `volumeRestoreOverrides` parameter to the YAML file:
++
+[source,yaml]
+----
+apiVersion: snapshot.kubevirt.io/v1beta1
+kind: VirtualMachineRestore
+metadata:
+  name: <vm_restore>
+spec:
+  target:
+    apiGroup: kubevirt.io
+    kind: VirtualMachine
+    name: <vm_name>
+  virtualMachineSnapshotName: <snapshot_name>
+  volumeRestoreOverrides:
+  - volumeName: <volume_name>
+    restoreName: <custom_pvc_name>
+    labels:
+      custom-label: <label_value>
+    annotations:
+      custom-annotation: <annotation_value>
 ----
++
+Where:
++
+** `volumeName`: Required. The name of the volume from the snapshot to customize.
+** `restoreName`: Optional. The custom name for the restored PVC. If not specified, the PVC name is determined by the `volumeRestorePolicy` setting.
+** `labels`: Optional. Custom labels to add to the restored PVC. These labels are merged with any existing labels from the source PVC.
+** `annotations`: Optional. Custom annotations to add to the restored PVC. These annotations are merged with any existing annotations from the source PVC.
 
 . Create the `VirtualMachineRestore` object:
 +

modules/virt-restoring-vm-from-snapshot-web.adoc

@@ -17,6 +17,10 @@ You can restore a virtual machine (VM) to a previous configuration represented b
 . Click the *Snapshots* tab to view a list of snapshots associated with the VM.
 . Select a snapshot to open the *Snapshot Details* screen.
 . Click the Options menu {kebab} and select *Restore VirtualMachine from snapshot*.
+. Optional: In the *Volume restore policy* section, select how restored persistent volume claims (PVCs) are named:
+** *Prefix target name* - The restored PVC names use the target VM name as a prefix. This is the default setting.
+** *In place* - The restored PVCs overwrite the original PVCs with the same names.
+** *Randomize names* - The restored PVC names are randomly generated.
 . Click *Restore*.
 
 . Optional: You can also create a new VM based on the snapshot. To do so: