Restore Kubernetes applications using a custom resource

01/28/2026 Contributors

You can use custom resources to restore your applications from a snapshot or backup. Restoring from an existing snapshot will be faster when restoring the application to the same cluster.

When you restore an application, all execution hooks configured for the application are restored with the app. If a post-restore execution hook is present, it runs automatically as part of the restore operation.
Restoring from a backup to a different namespace or to the original namespace is supported for qtree volumes. However, restoring from a snapshot to a different namespace or to the original namespace is not supported for qtree volumes.
You can use advanced settings to customize restore operations. To learn more, refer to Use advanced custom resource restore settings.

Restore a backup to a different namespace

When you restore a backup to a different namespace using a BackupRestore CR, Backup and Recovery restores the application in a new namespace and creates an application CR for the restored application. To protect the restored application, create on-demand backups or snapshots, or establish a protection schedule.

Restoring a backup to a different namespace with existing resources will not alter any resources that share names with those in the backup. To restore all resources in the backup, either delete and re-create the target namespace, or restore the backup to a new namespace.
When using a CR to restore to a new namespace, you must manually create the destination namespace before applying the CR. Backup and Recovery automatically creates namespaces only when using the CLI.

Before you begin

Ensure that the AWS session token expiration is sufficient for any long-running s3 restore operations. If the token expires during the restore operation, the operation can fail.

Refer to the AWS API documentation for more information about checking the current session token expiration.
Refer to the AWS IAM documentation for more information about credentials with AWS resources.

When you restore backups using Kopia as the data mover, you can optionally specify annotations in the CR to control the behavior of the temporary storage used by Kopia. Refer to the Kopia documentation for more information about the options you can configure.

Steps

Create the custom resource (CR) file and name it trident-protect-backup-restore-cr.yaml.
In the file you created, configure the following attributes:
- metadata.name: (Required) The name of this custom resource; choose a unique and sensible name for your environment.
- spec.appArchivePath: The path inside AppVault where the backup contents are stored. You can use the following command to find this path:
  kubectl get backups <BACKUP_NAME> -n my-app-namespace -o jsonpath='{.status.appArchivePath}'
- spec.appVaultRef: (Required) The name of the AppVault where the backup contents are stored.
- spec.namespaceMapping: The mapping of the source namespace of the restore operation to the destination namespace. Replace my-source-namespace and my-destination-namespace with information from your environment.
  apiVersion: protect.trident.netapp.io/v1 kind: BackupRestore metadata: name: my-cr-name namespace: my-destination-namespace spec: appArchivePath: my-backup-path appVaultRef: appvault-name namespaceMapping: [{"source": "my-source-namespace", "destination": "my-destination-namespace"}]

(Optional) If you need to select only certain resources of the application to restore, add filtering that includes or excludes resources marked with particular labels:

Trident Protect selects some resources automatically because of their relationship with resources that you select. For example, if you select a persistent volume claim resource and it has an associated pod, Trident Protect will also restore the associated pod.

resourceFilter.resourceSelectionCriteria: (Required for filtering) Use Include or Exclude to include or exclude a resource defined in resourceMatchers. Add the following resourceMatchers parameters to define the resources to be included or excluded:
- resourceFilter.resourceMatchers: An array of resourceMatcher objects. If you define multiple elements in this array, they match as an OR operation, and the fields inside each element (group, kind, version) match as an AND operation.
  - resourceMatchers[].group: (Optional) Group of the resource to be filtered.
  - resourceMatchers[].kind: (Optional) Kind of the resource to be filtered.
  - resourceMatchers[].version: (Optional) Version of the resource to be filtered.
  - resourceMatchers[].names: (Optional) Names in the Kubernetes metadata.name field of the resource to be filtered.
  - resourceMatchers[].namespaces: (Optional) Namespaces in the Kubernetes metadata.name field of the resource to be filtered.
  - resourceMatchers[].labelSelectors: (Optional) Label selector string in the Kubernetes metadata.name field of the resource as defined in the Kubernetes documentation. For example: "trident.netapp.io/os=linux".
    
    For example:
    
    spec: resourceFilter: resourceSelectionCriteria: "Include" resourceMatchers: - group: my-resource-group-1 kind: my-resource-kind-1 version: my-resource-version-1 names: ["my-resource-names"] namespaces: ["my-resource-namespaces"] labelSelectors: ["trident.netapp.io/os=linux"] - group: my-resource-group-2 kind: my-resource-kind-2 version: my-resource-version-2 names: ["my-resource-names"] namespaces: ["my-resource-namespaces"] labelSelectors: ["trident.netapp.io/os=linux"]

After you populate the trident-protect-backup-restore-cr.yaml file with the correct values, apply the CR:
```
kubectl apply -f trident-protect-backup-restore-cr.yaml
```

Restore a backup to the original namespace

You can restore a backup to the original namespace at any time.

Before you begin

Ensure that the AWS session token expiration is sufficient for any long-running s3 restore operations. If the token expires during the restore operation, the operation can fail.

Refer to the AWS API documentation for more information about checking the current session token expiration.
Refer to the AWS IAM documentation for more information about credentials with AWS resources.

Steps

Create the custom resource (CR) file and name it trident-protect-backup-ipr-cr.yaml.
In the file you created, configure the following attributes:
- metadata.name: (Required) The name of this custom resource; choose a unique and sensible name for your environment.
- spec.appArchivePath: The path inside AppVault where the backup contents are stored. You can use the following command to find this path:
  kubectl get backups <BACKUP_NAME> -n my-app-namespace -o jsonpath='{.status.appArchivePath}'
- spec.appVaultRef: (Required) The name of the AppVault where the backup contents are stored.
  
  For example:
  apiVersion: protect.trident.netapp.io/v1 kind: BackupInplaceRestore metadata: name: my-cr-name namespace: my-app-namespace spec: appArchivePath: my-backup-path appVaultRef: appvault-name

(Optional) If you need to select only certain resources of the application to restore, add filtering that includes or excludes resources marked with particular labels:

resourceFilter.resourceSelectionCriteria: (Required for filtering) Use Include or Exclude to include or exclude a resource defined in resourceMatchers. Add the following resourceMatchers parameters to define the resources to be included or excluded:
- resourceFilter.resourceMatchers: An array of resourceMatcher objects. If you define multiple elements in this array, they match as an OR operation, and the fields inside each element (group, kind, version) match as an AND operation.
  - resourceMatchers[].group: (Optional) Group of the resource to be filtered.
  - resourceMatchers[].kind: (Optional) Kind of the resource to be filtered.
  - resourceMatchers[].version: (Optional) Version of the resource to be filtered.
  - resourceMatchers[].names: (Optional) Names in the Kubernetes metadata.name field of the resource to be filtered.
  - resourceMatchers[].namespaces: (Optional) Namespaces in the Kubernetes metadata.name field of the resource to be filtered.
  - resourceMatchers[].labelSelectors: (Optional) Label selector string in the Kubernetes metadata.name field of the resource as defined in the Kubernetes documentation. For example: "trident.netapp.io/os=linux".
    
    For example:
    
    spec: resourceFilter: resourceSelectionCriteria: "Include" resourceMatchers: - group: my-resource-group-1 kind: my-resource-kind-1 version: my-resource-version-1 names: ["my-resource-names"] namespaces: ["my-resource-namespaces"] labelSelectors: ["trident.netapp.io/os=linux"] - group: my-resource-group-2 kind: my-resource-kind-2 version: my-resource-version-2 names: ["my-resource-names"] namespaces: ["my-resource-namespaces"] labelSelectors: ["trident.netapp.io/os=linux"]

After you populate the trident-protect-backup-ipr-cr.yaml file with the correct values, apply the CR:
```
kubectl apply -f trident-protect-backup-ipr-cr.yaml
```

Restore a backup to a different cluster

You can restore a backup to a different cluster if there is an issue with the original cluster.

When you restore backups using Kopia as the data mover, you can optionally specify annotations in the CR to control the behavior of the temporary storage used by Kopia. Refer to the Kopia documentation for more information about the options you can configure.
When using a CR to restore to a new namespace, you must manually create the destination namespace before applying the CR.

Before you begin

Ensure the following prerequisites are met:

The destination cluster has Trident Protect installed.
The destination cluster has access to the bucket path of the same AppVault as the source cluster, where the backup is stored.
Ensure that the AWS session token expiration is sufficient for any long-running restore operations. If the token expires during the restore operation, the operation can fail.
- Refer to the AWS API documentation for more information about checking the current session token expiration.
- Refer to the AWS documentation for more information about credentials with AWS resources.

Steps

Check the availability of the AppVault CR on the destination cluster using Trident Protect CLI plugin:
```
tridentctl-protect get appvault --context <destination_cluster_name>
```
Ensure that the namespace intended for the application restore exists on the destination cluster.

View the backup contents of the available AppVault from the destination cluster:

tridentctl-protect get appvaultcontent <appvault_name> \
--show-resources backup \
--show-paths \
--context <destination_cluster_name>

Running this command displays the available backups in the AppVault, including their originating clusters, corresponding application names, timestamps, and archive paths.

Example output:

+-------------+-----------+--------+-----------------+--------------------------+-------------+
|   CLUSTER   |    APP    |  TYPE  |      NAME       |        TIMESTAMP         |    PATH     |
+-------------+-----------+--------+-----------------+--------------------------+-------------+
| production1 | wordpress | backup | wordpress-bkup-1| 2024-10-30 08:37:40 (UTC)| backuppath1 |
| production1 | wordpress | backup | wordpress-bkup-2| 2024-10-30 08:37:40 (UTC)| backuppath2 |
+-------------+-----------+--------+-----------------+--------------------------+-------------+

Restore the application to the destination cluster using the AppVault name and archive path:

Create the custom resource (CR) file and name it trident-protect-backup-restore-cr.yaml.
In the file you created, configure the following attributes:
- metadata.name: (Required) The name of this custom resource; choose a unique and sensible name for your environment.
- spec.appVaultRef: (Required) The name of the AppVault where the backup contents are stored.
- spec.appArchivePath: The path inside AppVault where the backup contents are stored. You can use the following command to find this path:
  kubectl get backups <BACKUP_NAME> -n my-app-namespace -o jsonpath='{.status.appArchivePath}'
  If BackupRestore CR is not available, you can use the command mentioned in step 2 to view the backup contents.
- spec.namespaceMapping: The mapping of the source namespace of the restore operation to the destination namespace. Replace my-source-namespace and my-destination-namespace with information from your environment.
  
  For example:
  apiVersion: protect.trident.netapp.io/v1 kind: BackupRestore metadata: name: my-cr-name namespace: my-destination-namespace spec: appVaultRef: appvault-name appArchivePath: my-backup-path namespaceMapping: [{"source": "my-source-namespace", "destination": "my-destination-namespace"}]
After you populate the trident-protect-backup-restore-cr.yaml file with the correct values, apply the CR:
```
kubectl apply -f trident-protect-backup-restore-cr.yaml
```

Restore a snapshot to a different namespace

You can restore data from a snapshot using a custom resource (CR) file either to a different namespace or the original source namespace. When you restore a snapshot to a different namespace using a SnapshotRestore CR, Backup and Recovery restores the application in a new namespace and creates an application CR for the restored application. To protect the restored application, create on-demand backups or snapshots, or establish a protection schedule.

SnapshotRestore supports the spec.storageClassMapping attribute, but only when the source and destination storage classes use the same storage backend. If you attempt to restore to a StorageClass that uses a different storage backend, the restore operation will fail.
When using a CR to restore to a new namespace, you must manually create the destination namespace before applying the CR.

Before you begin

Ensure that the AWS session token expiration is sufficient for any long-running s3 restore operations. If the token expires during the restore operation, the operation can fail.

Refer to the AWS API documentation for more information about checking the current session token expiration.
Refer to the AWS IAM documentation for more information about credentials with AWS resources.

Steps

Create the custom resource (CR) file and name it trident-protect-snapshot-restore-cr.yaml.
In the file you created, configure the following attributes:
- metadata.name: (Required) The name of this custom resource; choose a unique and sensible name for your environment.
- spec.appVaultRef: (Required) The name of the AppVault where the snapshot contents are stored.
- spec.appArchivePath: The path inside AppVault where the snapshot contents are stored. You can use the following command to find this path:
  kubectl get snapshots <SNAPHOT_NAME> -n my-app-namespace -o jsonpath='{.status.appArchivePath}'
- spec.namespaceMapping: The mapping of the source namespace of the restore operation to the destination namespace. Replace my-source-namespace and my-destination-namespace with information from your environment.
  apiVersion: protect.trident.netapp.io/v1 kind: SnapshotRestore metadata: name: my-cr-name namespace: my-app-namespace spec: appVaultRef: appvault-name appArchivePath: my-snapshot-path namespaceMapping: [{"source": "my-source-namespace", "destination": "my-destination-namespace"}]

(Optional) If you need to select only certain resources of the application to restore, add filtering that includes or excludes resources marked with particular labels:

resourceFilter.resourceSelectionCriteria: (Required for filtering) Use Include or Exclude to include or exclude a resource defined in resourceMatchers. Add the following resourceMatchers parameters to define the resources to be included or excluded:
- resourceFilter.resourceMatchers: An array of resourceMatcher objects. If you define multiple elements in this array, they match as an OR operation, and the fields inside each element (group, kind, version) match as an AND operation.
  - resourceMatchers[].group: (Optional) Group of the resource to be filtered.
  - resourceMatchers[].kind: (Optional) Kind of the resource to be filtered.
  - resourceMatchers[].version: (Optional) Version of the resource to be filtered.
  - resourceMatchers[].names: (Optional) Names in the Kubernetes metadata.name field of the resource to be filtered.
  - resourceMatchers[].namespaces: (Optional) Namespaces in the Kubernetes metadata.name field of the resource to be filtered.
  - resourceMatchers[].labelSelectors: (Optional) Label selector string in the Kubernetes metadata.name field of the resource as defined in the Kubernetes documentation. For example: "trident.netapp.io/os=linux".
    
    For example:
    
    spec: resourceFilter: resourceSelectionCriteria: "Include" resourceMatchers: - group: my-resource-group-1 kind: my-resource-kind-1 version: my-resource-version-1 names: ["my-resource-names"] namespaces: ["my-resource-namespaces"] labelSelectors: ["trident.netapp.io/os=linux"] - group: my-resource-group-2 kind: my-resource-kind-2 version: my-resource-version-2 names: ["my-resource-names"] namespaces: ["my-resource-namespaces"] labelSelectors: ["trident.netapp.io/os=linux"]

After you populate the trident-protect-snapshot-restore-cr.yaml file with the correct values, apply the CR:
```
kubectl apply -f trident-protect-snapshot-restore-cr.yaml
```

Restore a snapshot to the original namespace

You can restore a snapshot to the original namespace at any time.

Before you begin

Ensure that the AWS session token expiration is sufficient for any long-running s3 restore operations. If the token expires during the restore operation, the operation can fail.

Refer to the AWS API documentation for more information about checking the current session token expiration.
Refer to the AWS IAM documentation for more information about credentials with AWS resources.

Steps

Create the custom resource (CR) file and name it trident-protect-snapshot-ipr-cr.yaml.
In the file you created, configure the following attributes:
- metadata.name: (Required) The name of this custom resource; choose a unique and sensible name for your environment.
- spec.appVaultRef: (Required) The name of the AppVault where the snapshot contents are stored.
- spec.appArchivePath: The path inside AppVault where the snapshot contents are stored. You can use the following command to find this path:
  kubectl get snapshots <SNAPSHOT_NAME> -n my-app-namespace -o jsonpath='{.status.appArchivePath}'
  apiVersion: protect.trident.netapp.io/v1 kind: SnapshotInplaceRestore metadata: name: my-cr-name namespace: my-app-namespace spec: appVaultRef: appvault-name appArchivePath: my-snapshot-path

(Optional) If you need to select only certain resources of the application to restore, add filtering that includes or excludes resources marked with particular labels:

resourceFilter.resourceSelectionCriteria: (Required for filtering) Use Include or Exclude to include or exclude a resource defined in resourceMatchers. Add the following resourceMatchers parameters to define the resources to be included or excluded:
- resourceFilter.resourceMatchers: An array of resourceMatcher objects. If you define multiple elements in this array, they match as an OR operation, and the fields inside each element (group, kind, version) match as an AND operation.
  - resourceMatchers[].group: (Optional) Group of the resource to be filtered.
  - resourceMatchers[].kind: (Optional) Kind of the resource to be filtered.
  - resourceMatchers[].version: (Optional) Version of the resource to be filtered.
  - resourceMatchers[].names: (Optional) Names in the Kubernetes metadata.name field of the resource to be filtered.
  - resourceMatchers[].namespaces: (Optional) Namespaces in the Kubernetes metadata.name field of the resource to be filtered.
  - resourceMatchers[].labelSelectors: (Optional) Label selector string in the Kubernetes metadata.name field of the resource as defined in the Kubernetes documentation. For example: "trident.netapp.io/os=linux".
    
    For example:
    
    spec: resourceFilter: resourceSelectionCriteria: "Include" resourceMatchers: - group: my-resource-group-1 kind: my-resource-kind-1 version: my-resource-version-1 names: ["my-resource-names"] namespaces: ["my-resource-namespaces"] labelSelectors: ["trident.netapp.io/os=linux"] - group: my-resource-group-2 kind: my-resource-kind-2 version: my-resource-version-2 names: ["my-resource-names"] namespaces: ["my-resource-namespaces"] labelSelectors: ["trident.netapp.io/os=linux"]

After you populate the trident-protect-snapshot-ipr-cr.yaml file with the correct values, apply the CR:
```
kubectl apply -f trident-protect-snapshot-ipr-cr.yaml
```

Restore Kubernetes applications using a custom resource

Creating your file...

Restore a backup to a different namespace

Restore a backup to the original namespace

Restore a backup to a different cluster

Restore a snapshot to a different namespace

Restore a snapshot to the original namespace