Restore a Namespace Backup

You can restore a namespace backup in the following ways:

• Full Restore - Restore all namespaces and their associated resources from the namespace backup to the destination cluster. For more information, see Full Restore of a Namespace Backup.
• Specific Namespaces Restore - Restore selected namespaces and their associated resources from the namespace backup to the destination cluster. For more information, see Restore Specific Namespaces or Namespace resources from a Namespace Backup.
• Specific Resources Restore - Restore specific resources from the namespace backup to the destination cluster. For more information, see Restore Specific Namespaces or Namespace resources from a Namespace Backup.

Full Restore of a Namespace Backup

Portworx Backup provides the full restore functionality to restore all namespaces and their associated resources from the namespace backup to the destination cluster. The full restore replaces all the namespaces and their associated resources in the destination cluster.

Additionally, you can use the full restore functionality to recover a large number of resources or resource sets from the backup to the destination cluster. For uninterrupted restores of namespaces that contain large number of resources, you can add few parameters to ConfigMap in the kube-system namespace and customize to suit your environment. For more information on advanced settings related to such operations, see Large resource ConfigMap parameters.

Requirements

Ensure that the following prerequisites are met before you perform a full restore of a namespace backup:

• A namespace backup is available.
• The destination cluster has the same or latest stork version than the backup cluster. For example, if the namespace backup is taken from a backup cluster running stork version 26.2.0, the destination cluster must be running stork version 26.2.0 or later. For information on how to install and upgrade Stork, see Install Stork.
• Observe the restore feasibility matrix for namespace backup. For more information, see Supported Restore Types Based on Namespace Backup Status.

Procedure

To perform a full restore of a namespace backup, follow these steps:

1. Log in to Portworx Backup web console.

2. From the left navigation pane, click the Clusters icon .

3. On the Clusters page, click the application cluster for which you have taken the backup.
   The system displays the application cluster page.

4. Click the Backups tab, and select NS to view the backups.

   tip

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

5. Click the Actions icon for the required NS 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.

   

6. Select the Full Restore option.
   For information on the Namespace Restore and Resource Restore options, see Restore Specific Namespaces or Namespace resources from a Namespace Backup. The system displays the Restore (Backup) page.

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

       If you are restoring only PVCs with the Replace existing resources option, scale down the deployment before initiating the restore; otherwise, existing pods will continue to use the current PVCs.
       After you scale down the deployment, the existing PVCs are deleted automatically without any manual intervention, and the restore succeeds.
       Once the restore is complete, scale the deployment back up.

     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.

     note

     • For large resource restores, the Restore Details page does not display individual resource details due to the high resource count. If a full restore of a non-large backup is treated as a large backup restore, the Restore Details window does not list restored resources or indicate the success or failure of individual resources because the restore is partial. However, you can 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.
     • If the resources already exist in the namespace of the destination cluster, Portworx Backup restores only the associated volumes of that namespace and not the resources. The web console displays the status of such a restore as partial success.

     The following error message appears in the stork log for the specific resources associated with the restore, when a restore succeeds partially:

     time="2023-04-24T08:47:26Z" level=warning msg="Error deleting ConfigMap <configmap-name> during restore, ReplacePolicy set to Retain: configmaps "<configmap-name>" already exists" ApplicationRestoreName=<name-of-restore> ApplicationRestoreUID=<restore-uid> Namespace=<namespace>

Restore Specific Namespaces or Namespace resources from a Namespace Backup

Portworx Backup facilitates you to restore selected namespaces and their associated resources, or selected resources of a namespace backup when you restore a namespace backup to the destination cluster.
The specific namespaces restore replaces all selected namespaces and their associated resources in the destination cluster based on the configured source-to-destination mapping criteria.
The specific resource restore replaces all the selected resources in the destination cluster based on the configured source-to-destination mapping criteria.

Requirements

Ensure that the following prerequisites are met before you restore specific namespaces or namespace resources from a namespace backup:

• A namespace backup is available for the source cluster.
• A large namespace backup must be taken after upgrading Portworx Backup to 2.11.0 or later version and stork to 26.2.0 or later version.
• A valid resources-metadata.json file is present at the backup location. This metadata file enables you to select specific namespace resources during the restore operation.
  If the resources-metadata.json file is missing, corrupted, or manually modified, you cannot perform a resource-level restore from the namespace backup.
• Stork is upgraded to the 26.2.0 or later version in the destination cluster for the following scenarios:
  • To restore large namespace backups.
  • To restore non-large namespace backups taken before upgrading to Portworx Backup 2.11.0 or later version. If the Stork in the destination cluster is not updated to the latest version, the Portworx Backup only allows you to do a full restore and namespace restore, but not resource restore. For information on how to install and upgrade Stork, see Install Stork.
• Observe the restore feasibility matrix for namespace backup. For more information, see Supported Restore Types Based on Namespace Backup Status.
• Observe the Concurrency Limit for Namespace and Resource Restore.

Procedure

You can restore specific namespaces or resources of a namespace from a backup to the same source cluster or to a new destination cluster, using the configured source-to-destination mapping criteria. To restore a specific namespace or resources of a namespace from the namespace backup, follow these steps:

1. Log in to Portworx Backup web console.

2. From the left navigation pane, click the Clusters icon .

3. On the Clusters page, click the application cluster for which you have taken the backup. The system displays the application cluster page.

4. Click the Backups tab, and select NS to view the backups.

   tip

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

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

   

6. Select one of the following options on the Restore Options page, and click Next:

   • Namespace Restore: Restore selected namespaces from the backup to the destination cluster. Use this option to choose namespaces and map both the namespaces and storage classes from the backup to the destination cluster.
   • Resource Restore: Restore selected resources from the namespace backup to the destination cluster. Use this option to choose resources and map their associated namespaces and storage classes from the backup to the destination cluster.

   For information on the Full Restore option, see Full Restore of a Namespace Backup.

   The system displays the Restore (Backup) page for the selected restore option.

   • For the Namespace Restore option, follow these steps:

     1. 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.
        • 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.
          note

          If you are restoring only PVCs with the Replace existing resources option, scale down the deployment before initiating the restore; otherwise, existing pods will continue to use the current PVCs.
          After you scale down the deployment, the existing PVCs are deleted automatically without any manual intervention, and the restore succeeds.
          Once the restore is complete, scale the deployment back up.

     2. On the Select Namespaces page, select the namespaces to restore from the backup, and click Next.

        tip

        Use the filter options to list the required namespaces. Resource-type filters used during namespace selection do not limit the scope of a Namespace restore; all resources within the namespace are restored.

        

     3. On the Source and Destination Mapping page, map the namespaces, storage classes, and rancher projects from the namespace backup to the destination cluster, 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.
          Additionally, you can specify a prefix to add to the namespace name in the destination cluster.
          For the namespace mapping:
          • Select Prefix option and enter the text to be prefixed to the namespace name in the destination cluster after restore.
          • Select Original option to retain the same namespace name in the destination cluster after restore.

        After you select the Prefix or Original option, click Apply and preview list to view the the list of namespace names that appear in the destination cluster.

        • 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. You can map the storage class to an existing storage class in the destination cluster.

          note

          The StorageClass Mapping options appear only when you restore the backups created using Portworx or the KDMP driver. These options do not appear when you restore backups that are created using the native cloud driver.

        • Project mapping: 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 Nil. You can map the project to an existing project in the destination cluster.

          note

          • Portworx Backup allows one-to-one mapping of multiple projects during the 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, refer 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.

     4. On the Review & Restore page, review the restore configuration summary, and click Restore.

   • For the Resource Restore option, follow these steps:

     1. 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.
        • 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.
          note

          If you are restoring only PVCs with the Replace existing resources option, scale down the deployment before initiating the restore; otherwise, existing pods will continue to use the current PVCs.
          After you scale down the deployment, the existing PVCs are deleted automatically without any manual intervention, and the restore succeeds.
          Once the restore is complete, scale the deployment back up.

     2. On the Select Resources page, select the resources to restore from the backup, and click Next.

        tip

        Use the filter options to list the required resources.

        

     3. On the Source and Destination Mapping page, map the namespaces, storage classes, and rancher projects from the namespace backup to the destination cluster, 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.
          Additionally, you can specify a prefix to add to the namespace name in the destination cluster.
          For the namespace mapping:
          • Select Prefix option and enter the text to be prefixed to the namespace name in the destination cluster after restore.
          • Select Original option to retain the same namespace name in the destination cluster after restore.

        After you select the Prefix or Original option, click Apply and preview list to view the the list of namespace names that appear in the destination cluster.

        • 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 process, you must map the storage class to an existing storage class in the destination cluster.
          note

          The StorageClass Mapping options appear only when you restore the backups created using Portworx or the KDMP driver. These options do not appear when you restore backups that are created using the native cloud driver.

        • Project mapping: 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 Nil. To proceed with the restore process, you must map the project to an existing project in the destination cluster.
          note

          • Portworx Backup allows one-to-one mapping of multiple projects during the 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, refer 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.

     4. On the Review & Restore page, review the restore configuration summary, and click Restore.

     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.

     note

     • For large resource restores, the Restore Details page does not display individual resource details due to the high resource count. If a full restore of a non-large backup is treated as a large backup restore, the Restore Details window does not list restored resources or indicate the success or failure of individual resources because the restore is partial. However, you can 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.
     • If resources with the same name already exist in the namespace during a namespace restore and you choose to skip restoring them, Portworx Backup skips those resources. The web console displays the restore status as Partial Success.

     The following error message appears in the stork log for the specific resources associated with the restore, when a restore succeeds partially:

     time="2023-04-24T08:47:26Z" level=warning msg="Error deleting ConfigMap <configmap-name> during restore, ReplacePolicy set to Retain: configmaps "<configmap-name>" already exists" ApplicationRestoreName=<name-of-restore> ApplicationRestoreUID=<restore-uid> Namespace=<namespace>

Concurrency Limit for Namespace and Resource Restore

The following concurrency limits apply when you restore specific namespaces or namespace resources from a namespace backup:

• For namespace restore, by default, the NAMESPACE_SYNC_MAX_LIMIT is set to 25, which means you can run up to 25 namespace restore operations in parallel at any given time, across 25 different backup objects.
  To run more than 25 namespace restores in parallel, update the NAMESPACE_SYNC_MAX_LIMIT parameter to the desired value.

• For resource restore, by default, the RESOURCE_SYNC_MAX_LIMIT is set to 5, which means you can run up to 5 granular resource restore operations in parallel at any given time, across 5 different backup objects.
  To run more than 5 granular restores in parallel, update the RESOURCE_SYNC_MAX_LIMIT parameter to the desired value.

note

For a full restore of a namespace backup, no concurrency limits apply, and you can perform any number of full namespace restore operations in parallel.

To identify the backups that are in use for resource or namespace restore, observe the icon in the Backups tab.

Supported Restore Types Based on Namespace Backup Status

This table provides the restore feasibility for namespaces and their associated resources based on the backed-up entities (single namespace or multiple namespaces) and the status of the backup operation.

Backup Entities	Backup Status	Is Restore Supported?	Supported Restore Types	Additional Information
Single Namespace	Failed	❌ No	NA	Restore is not supported.
Single Namespace	Partial Success	✅ Yes	Resource Restore	Restore Restore is only supported for the namespace backup.
Single Namespace	Success	✅ Yes	Full Restore Namespace Restore Resource Restore	Full restore, namespace restore, and resource restore are supported for the namespace backup.
Multiple namespaces	Failed	❌ No	NA	Restore is not supported.
Multiple namespaces	Partial Success	✅ Yes	Full Restore Namespace Restore Resource Restore	Full restore, namespace restore, and resource restore are supported for the namespaces and their resources that are backed up successfully.
Multiple namespaces	Success	✅ Yes	Full Restore Namespace Restore Resource Restore	Full restore, namespace restore, and resource restore are supported for the namespace backup.