Restore a VM Backup
You can restore a VM backup in the following ways:
- Full Restore - Restore all VMs and their associated resources from the VM backup to the destination cluster. For more information, see Full restore of a VM backup.
- Specific VMs Restore - Restore the selected VMs from a VM backup to the destination cluster. For more information, see Restore specific VMs from a VM backup.
- File-level Restore - Restore selected files or folders from a VM in a VM backup, instead of the whole VM. For more information, see Restore Specific Files or Folders of a VM.
Starting with Portworx Backup 3.2.0, VM restores are evaluated on a per-VM basis. If a restore includes multiple VMs and some VMs fail while others succeed, the restore completes with a Partial Success status, and the VMs that were restored successfully remain usable. For more information, see Partial Success in VM Restores.
Full restore of a VM backup
Portworx Backup provides the full restore functionality to restore all VMs and their associated resources from the VM backup to the destination cluster. Whether existing resources on the destination cluster are overwritten depends on the Replace existing resources option that you select in the restore wizard, as described in the procedure that follows. You can also use the full restore functionality to recover a large number of resources or resource sets from the backup to the destination cluster.
Requirements
Ensure that the following prerequisites are met before you perform a full restore of a VM backup:
- A VM backup is available.
Procedure
You can perform a full restore of all the VMs from a VM backup.
To perform a full restore of a VM backup, follow these steps:
-
Log in to Portworx Backup web console.
-
From the left navigation pane, click the Clusters icon
. -
On the Clusters page, click the application cluster for which you have taken the backup.
The system displays the application cluster page. -
Click the Backups tab, and select VM to view the backups.
tipUse the timeframe filter to list the backups based on the required timeline such as last 24 hours, 1 week, one month, or a custom timeframe.
-
Click the Actions icon for the required VM backup, and select Restore from the list of available actions.
The system displays the Restore Options page, and prompts you to select the restore option.
-
Select the Full Restore option.
For information on the Virtual Machine Restore option, see Restore Specific VMS from a VM Backup.
The system displays the Restore (Backup) page. -
On the Restore (Backup) page, specify the following information, and click Restore:
- Enter the restore name: Enter a unique name for the restore. You can use this name to identify the restore operation in the Restore tab.
- Choose the destination cluster: Select the destination cluster to restore the backup.
- Replace existing resources?
- Select this checkbox to replace existing resources in the destination cluster with the latest backup data.
- Clear this checkbox to skip restoring resources that already exist in the destination cluster.
- VM options
- Skip MAC address masking: Select this checkbox to retain the original MAC address from the backup during restore.
For more information, see Preserve Static IP and MAC address for VM Backup and Restore. - Skip virtual machine restart after restore: Select this checkbox to skip restarting of VMs after restore.
- Skip MAC address masking: Select this checkbox to retain the original MAC address from the backup during restore.
If you select Replace existing resources, Portworx Backup deletes the matching existing resources on the destination cluster before it restores them. In a multi-VM restore that ends in Partial Success, a VM that fails after its existing resources are deleted is not recovered. Ensure that you have a valid backup before you replace existing resources for critical VMs. For more information, see Partial Success in VM Restores.
The progress bar in the Restore tab displays the percentage completion of the restore.
To obtain detailed status or information during restore, click on the required restore.
After Portworx Backup successfully completes the restore, you can view the resource details in the Restore Details page through Vertical ellipsis >> Show Details at the end of the restore row.
To identify failed resources and their failure reasons, review the restore CR JSON file. To retrieve the file, expand the restore row in the Restore tab and select Download Resources, or use the CLI method. For more information, see View Detailed Restore Failures for Large Restores.
Restore specific VMs from a VM backup
Portworx Backup facilitates you to restore the selected VMs from a VM backup to the destination cluster. The specific VMs restore replaces the selected VMs and their associated resources in the destination cluster.
Requirements
Ensure that the following prerequisites are met before you restore specific VMs from a VM backup:
- A VM backup is available.
- The destination cluster must have a supported virtualization platform installed and running: KubeVirt v1.0.0 or later on Vanilla Kubernetes or EKS/GKE, the equivalent OpenShift Virtualization release on OpenShift, or SUSE Virtualization, which includes its own KubeVirt build. Restoring VM resources to a cluster without these components fails.
- The destination cluster has the same or a later Stork version as the backup cluster. For information on how to install and upgrade Stork, see Install Stork.
- Before you start, check the status of the VM backup against the restore feasibility matrix and confirm that the restore type you intend to use is supported for that status. If it is not, the restore fails or restores only part of the backup. See Supported restore types based on VM backup status.
Procedure
You can perform a restore of specific VMs from a VM backup to the same source cluster or to a new destination cluster, using the configured source-to-destination mapping criteria. To restore specific VMs from a VM backup, follow these steps:
-
Log in to Portworx Backup web console.
-
From the left navigation pane, click the Clusters icon
. -
On the Clusters page, click the application cluster for which you have taken the backup.
The system displays the application cluster page. -
Click the Backups tab, and select VM to view the backups.
tipUse the timeframe filter to list the backups based on the required timeline such as last 24 hours, 1 week, one month, or a custom timeframe.
-
Click the Actions icon for the required backup, and select Restore from the list of available actions.
The system displays the Restore Options page, and prompts you to select the restore option.
-
Select the Virtual Machine Restore option.
For information on the Full Restore option, see Full restore of a VM backup.
The system displays the Restore (Backup) page. -
On the Restore (Backup) page, perform the following actions:
- On the Basic Information page, specify the following information, and click Next.
- Enter the restore name: Enter a unique name for the restore. You can use this name to identify the restore operation in the Restore tab.
- Choose the destination cluster: Select the destination cluster to restore the backup.
- Select or clear the Replace existing resources? checkbox.
- Select this checkbox to replace existing resources in the destination cluster with the latest backup data.
- Clear this checkbox to skip restoring resources that already exist in the destination cluster.
noteIf you are restoring only PVCs with Replace existing resources selected, stop the virtual machines (VMs) that use those PVCs before starting the restore. Running VMs keep the PVCs in use, preventing Portworx Backup from replacing them.
During the restore, Portworx Backup automatically deletes the existing PVCs and recreates them from the backup. No manual cleanup is required. Any data written to the PVCs after the backup was taken is lost because the existing PVCs are replaced with their backed-up versions.
After the restore completes successfully, restart the VMs. - Select or clear the following VM options:
- Skip MAC address masking - Select this checkbox to retain the original MAC address from the backup during restore.
For more information, see Preserve Static IP and MAC address for VM Backup and Restore. - Skip virtual machine restart after restore - Select this checkbox to skip restarting of VMs after restore.
- Skip MAC address masking - Select this checkbox to retain the original MAC address from the backup during restore.
- On the Select Virtual Machines page, select the VMs to restore from the backup, and click Next.
- On the Source and Destination Mapping page, specify the following mappings, and click Next.
- Namespace mapping: If the specified namespace does not exist on the destination cluster, a new namespace is created for the restore. By default, the system uses the same namespace name for both the source and destination clusters. However, you can edit this value to map the namespace to an existing namespace on the destination cluster or specify a new namespace name.
- Storageclass mapping: By default, the system uses the same storage class for both the source and destination clusters. If a storage class from the source cluster does not exist in the destination cluster, the system displays it as NA. To proceed with the restore, you must map every storage class shown as NA to an existing storage class in the destination cluster; the restore cannot proceed while any required storage class is left unmapped.
note
The StorageClass Mapping options appear only when you restore backups created using Portworx or the KDMP driver. These options do not appear when you restore backups created using the native cloud driver (the cloud provider's own volume snapshot driver, used instead of Portworx or KDMP).
- Project mapping (applies to Rancher clusters only): By default, the system uses the same project name for both the source and destination clusters. If a project from the source cluster does not exist in the destination cluster, the system displays it as NA. To proceed with the restore process, you must map the project to an existing project in the destination cluster.
note
-
Portworx Backup maps each source project to a single destination project (one-to-one), and you can map multiple projects in a single restore. You can also restore the backups from a Rancher source cluster to a non-Rancher destination cluster without mapping any projects.
For more information on mapping projects during restore, see Project mapping in Rancher Cluster.
-
When the resource limit is exceeded at the project level on a Rancher cluster, applications on the destination cluster might not start as expected.
-
- On the Review & Restore page, review the restore configuration summary, and click Restore.
- On the Basic Information page, specify the following information, and click Next.
The progress bar in the Restore tab displays the percentage completion of the restore.
To obtain detailed status or information during restore, click on the required restore.
After Portworx Backup successfully completes the restore, you can view the resource details in the Restore Details page through Vertical ellipsis >> Show Details at the end of the restore row.
For large resource restores, the Restore Details page does not display individual resource details or their restore status. A restore is classified as a large resource restore when the size of its Restore Custom Resource (restore CR) exceeds the large-resource-size-limit threshold, which defaults to 1 MiB. This classification can also apply to restores of backups that are not classified as large. To confirm whether a specific restore was treated as a large resource restore, check the status.largeResourceEnabled field in the restore CR JSON; it is set to true for a large resource restore. For more information about the threshold, see stork-controller-config ConfigMap parameters.
To identify failed resources and their failure reasons, review the restore CR JSON file. To retrieve the file, expand the restore row in the Restore tab and select Download Resources, or use the CLI method. For more information, see View Detailed Restore Failures for Large Restores.
View restore details for large restores
When a restore contains a very large number of resources, the Restore Details page might not list individual resources or indicate the success or failure of each resource. In such cases, check the Restore Custom Resource (restore CR) JSON file to identify the failed resources. For more information, see View Detailed Restore Failures from the Backup Location.
Supported restore types based on VM backup status
This table provides the restore feasibility for VMs and their files and folders based on the backed-up entities (single VM or multiple VMs) and the status of the backup operation.
A single-VM backup is either Success or Failed; it does not have a Partial Success state. Partial Success applies only to multi-VM backups, where some VMs are backed up successfully and others fail. A single-VM backup with a Failed status cannot be restored.
| Backup Entities | Backup Status | Restore Possible? | Supported Restore Types | Restore Details |
|---|---|---|---|---|
| Single VM | Failed | ❌ No | NA | Restore is not supported. |
| Single VM | Success | ✅ Yes | Full Restore Specific Files or Folders Restore | Both full restore and restore of specific files or folders of the VM are supported. |
| Multiple VMs | Failed | ❌ No | NA | Restore is not supported. |
| Multiple VMs | Partial Success (some VMs successful) | ✅ Yes | Full Restore Specific VMs Restore Specific Files or Folders Restore | Full Restore is supported for VMs that were successfully backed up. |
| Multiple VMs | Success | ✅ Yes | Full Restore Specific VMs Restore Specific Files or Folders Restore | Full restore, specific VMs restore, and specific files or folders restore are supported. |