Chapter 15. Backup and restore

Procedure

1. Navigate to Virtualization VirtualMachines in the web console.
2. Select a VM to open the VirtualMachine details page.

3. Click the Snapshots tab and then click Take Snapshot.

   Alternatively, right-click the VM and select Create snapshot from the menu.

4. Enter the snapshot name.
5. Expand Disks included in this Snapshot to see the storage volumes to be included in the snapshot.
6. If your VM has disks that cannot be included in the snapshot and you wish to proceed, select I am aware of this warning and wish to proceed.
7. Click Save.

Procedure

1. Create a YAML file to define a VirtualMachineSnapshot object that specifies the name of the new VirtualMachineSnapshot and the name of the source VM as in the following example:

   apiVersion: snapshot.kubevirt.io/v1beta1
   kind: VirtualMachineSnapshot
   metadata:
     name: <snapshot_name>
   spec:
     source:
       apiGroup: kubevirt.io
       kind: VirtualMachine
       name: <vm_name>

2. Create the VirtualMachineSnapshot object:

   $ oc create -f <snapshot_name>.yaml

   The snapshot controller creates a VirtualMachineSnapshotContent object, binds it to the VirtualMachineSnapshot, and updates the status and readyToUse fields of the VirtualMachineSnapshot object.

Verification

1. Optional: During the snapshot creation process, you can use the wait command to monitor the status of the snapshot and wait until it is ready for use:

   1. Enter the following command:

      $ oc wait <vm_name> <snapshot_name> --for condition=Ready

   2. Verify the status of the snapshot:

      • InProgress - The snapshot operation is still in progress.
      • Succeeded - The snapshot operation completed successfully.

      • Failed - The snapshot operaton failed.

        Note

        Online snapshots have a default time deadline of five minutes (5m). If the snapshot does not complete successfully in five minutes, the status is set to failed. Afterwards, the file system will be thawed and the VM unfrozen but the status remains failed until you delete the failed snapshot image.

        To change the default time deadline, add the FailureDeadline attribute to the VM snapshot spec with the time designated in minutes (m) or in seconds (s) that you want to specify before the snapshot operation times out.

        To set no deadline, you can specify 0, though this is generally not recommended, as it can result in an unresponsive VM.

        If you do not specify a unit of time such as m or s, the default is seconds (s).

2. Verify that the VirtualMachineSnapshot object is created and bound with VirtualMachineSnapshotContent and that the readyToUse flag is set to true:

   $ oc describe vmsnapshot <snapshot_name>

   Example output:

   apiVersion: snapshot.kubevirt.io/v1beta1
   kind: VirtualMachineSnapshot
   metadata:
     creationTimestamp: "2020-09-30T14:41:51Z"
     finalizers:
     - snapshot.kubevirt.io/vmsnapshot-protection
     generation: 5
     name: mysnap
     namespace: default
     resourceVersion: "3897"
     selfLink: /apis/snapshot.kubevirt.io/v1beta1/namespaces/default/virtualmachinesnapshots/my-vmsnapshot
     uid: 28eedf08-5d6a-42c1-969c-2eda58e2a78d
   spec:
     source:
       apiGroup: kubevirt.io
       kind: VirtualMachine
       name: my-vm
   status:
     conditions:
     - lastProbeTime: null
       lastTransitionTime: "2020-09-30T14:42:03Z"
       reason: Operation complete
       status: "False"
       type: Progressing
     - lastProbeTime: null
       lastTransitionTime: "2020-09-30T14:42:03Z"
       reason: Operation complete
       status: "True"
       type: Ready
     creationTime: "2020-09-30T14:42:03Z"
     readyToUse: true
     sourceUID: 355897f3-73a0-4ec4-83d3-3c2df9486f4f
     virtualMachineSnapshotContentName: vmsnapshot-content-28eedf08-5d6a-42c1-969c-2eda58e2a78d
     indications:
       - Online
     includedVolumes:
       - name: rootdisk
         kind: PersistentVolumeClaim
         namespace: default
       - name: datadisk1
         kind: DataVolume
         namespace: default

   where:

   status

   The status field of the Progressing condition specifies if the snapshot is still being created.

   The status field of the Ready condition specifies if the snapshot creation process is complete.

   readyToUse

   Specifies if the snapshot is ready to be used.

   virtualMachineSnapshotContentName

   Specifies that the snapshot is bound to a VirtualMachineSnapshotContent object created by the snapshot controller.

   indications

   Specifies additional information about the snapshot, such as whether it is an online snapshot, or whether it was created with QEMU guest agent running.

   includedVolumes

   Lists the storage volumes that are part of the snapshot, as well as their parameters.

3. Check the includedVolumes section in the snapshot description to verify that the expected PVCs are included in the snapshot.

Procedure

1. Display the output from the snapshot indications by performing one of the following actions:

   • Use the command line to view indicator output in the status stanza of the VirtualMachineSnapshot object YAML.
   • In the web console, click VirtualMachineSnapshot Status in the Snapshot details screen.

2. Verify the status of your online VM snapshot by viewing the values of the status.indications parameter:

   • Online indicates that the VM was running during online snapshot creation.
   • GuestAgent indicates that the QEMU guest agent was active and successfully quiesced the guest file system for the online snapshot. This results in an application-consistent snapshot, preserving data integrity as if the applications had been gracefully shut down.
   • NoGuestAgent indicates that the QEMU guest agent was not installed, or not ready to quiesce the file system during the online snapshot. This results in a crash-consistent snapshot, which captures the VM’s state like an abrupt power-off. As a result, application consistency is not guaranteed, which causes a risk of data issues for critical applications. For higher reliability, install and run the guest agent, or retry the snapshot.
   • QuiesceFailed indicates that an attempt to quiesce the file system failed during the online snapshot process. This means that the snapshot was created, but it is not necessarily application-consistent. To achieve proper consistency, retry the snapshot.

Procedure

1. Navigate to Virtualization VirtualMachines in the web console.
2. Select a VM to open the VirtualMachine details page.
3. If the VM is running, click the Options menu and select Stop to power it down.
4. Click the Snapshots tab to view a list of snapshots associated with the VM.
5. Select a snapshot to open the Snapshot Details screen.
6. Click the Options menu and select Restore VirtualMachine from snapshot.

7. 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.
8. Click Restore.

9. Optional: You can also create a new VM based on the snapshot. To do so:

   1. In the Options menu of the snapshot, select Create VirtualMachine from Snapshot.
   2. Provide a name for the new VM.
   3. Click Create

Procedure

1. 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:

   apiVersion: snapshot.kubevirt.io/v1beta1
   kind: VirtualMachineRestore
   metadata:
     name: <vm_restore>
   spec:
     target:
       apiGroup: kubevirt.io
       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.

2. Optional: To customize the names, labels, and annotations of individual restored persistent volume claims (PVCs), add the volumeRestoreOverrides parameter to the YAML file:

   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.

3. Create the VirtualMachineRestore object:

   $ oc create -f <vm_restore>.yaml

   The snapshot controller updates the status fields of the VirtualMachineRestore object and replaces the existing VM configuration with the snapshot content.

Procedure

1. Navigate to Virtualization VirtualMachines in the web console.
2. Select a VM to open the VirtualMachine details page.
3. Click the Snapshots tab to view a list of snapshots associated with the VM.
4. Click the Options menu beside a snapshot and select Delete snapshot.
5. Click Delete.

Procedure

1. Install the OADP Operator according to the instructions for your storage provider.
2. Install the Data Protection Application (DPA) with the kubevirt and openshift OADP plug-ins.

3. Back up virtual machines by creating a Backup custom resource (CR).

   You restore the Backup CR by creating a Restore CR.

Procedure

1. Click Ecosystem Installed Operators and select the OADP Operator.
2. Under Provided APIs, click Create instance in the DataProtectionApplication box.

3. Click YAML View and update the parameters of the DataProtectionApplication manifest:

   apiVersion: oadp.openshift.io/v1alpha1
   kind: DataProtectionApplication
   metadata:
     name: <dpa_sample>
     namespace: openshift-adp
   spec:
     configuration:
       velero:
         defaultPlugins:
           - kubevirt
           - gcp
           - csi
           - openshift
         resourceTimeout: 10m
       nodeAgent:
         enable: true
         uploaderType: kopia
         podConfig:
           nodeSelector: <node_selector>
     backupLocations:
       - velero:
           provider: gcp
           default: true
           credential:
             key: cloud
             name: <default_secret>
           objectStorage:
             bucket: <bucket_name>
             prefix: <prefix>

   where:

   namespace

   Specifies the default namespace for OADP which is openshift-adp. The namespace is a variable and is configurable.

   kubevirt

   Specifies that the kubevirt plugin is mandatory for OpenShift Virtualization.

   gcp

   Specifies the plugin for the backup provider, for example, gcp, if it exists.

   csi

   Specifies that the csi plugin is mandatory for backing up PVs with CSI snapshots. The csi plugin uses the Velero CSI beta snapshot APIs. You do not need to configure a snapshot location.

   openshift

   Specifies that the openshift plugin is mandatory.

   resourceTimeout

   Specifies how many minutes to wait for several Velero resources such as Velero CRD availability, volumeSnapshot deletion, and backup repository availability, before timeout occurs. The default is 10m.

   nodeAgent

   Specifies the administrative agent that routes the administrative requests to servers.

   enable

   Set this value to true if you want to enable nodeAgent and perform File System Backup.

   uploaderType

   Specifies the uploader type. Enter kopia as your uploader to use the Built-in DataMover. The nodeAgent deploys a daemon set, which means that the nodeAgent pods run on each working node. You can configure File System Backup by adding spec.defaultVolumesToFsBackup: true to the Backup CR.

   nodeSelector

   Specifies the nodes on which Kopia are available. By default, Kopia runs on all nodes.

   provider

   Specifies the backup provider.

   name

   Specifies the correct default name for the Secret, for example, cloud-credentials-gcp, if you use a default plugin for the backup provider. If specifying a custom name, then the custom name is used for the backup location. If you do not specify a Secret name, the default name is used.

   bucket

   Specifies a bucket as the backup storage location. If the bucket is not a dedicated bucket for Velero backups, you must specify a prefix.

   prefix

   Specifies a prefix for Velero backups, for example, velero, if the bucket is used for multiple purposes.

4. Click Create.

Verification

1. Verify the installation by viewing the OpenShift API for Data Protection (OADP) resources by running the following command:

   $ oc get all -n openshift-adp

   NAME                                                     READY   STATUS    RESTARTS   AGE
   pod/oadp-operator-controller-manager-67d9494d47-6l8z8    2/2     Running   0          2m8s
   pod/node-agent-9cq4q                                     1/1     Running   0          94s
   pod/node-agent-m4lts                                     1/1     Running   0          94s
   pod/node-agent-pv4kr                                     1/1     Running   0          95s
   pod/velero-588db7f655-n842v                              1/1     Running   0          95s
   
   NAME                                                       TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)    AGE
   service/oadp-operator-controller-manager-metrics-service   ClusterIP   172.30.70.140    <none>        8443/TCP   2m8s
   service/openshift-adp-velero-metrics-svc                   ClusterIP   172.30.10.0      <none>        8085/TCP   8h
   
   NAME                        DESIRED   CURRENT   READY   UP-TO-DATE   AVAILABLE   NODE SELECTOR   AGE
   daemonset.apps/node-agent    3         3         3       3            3           <none>          96s
   
   NAME                                                READY   UP-TO-DATE   AVAILABLE   AGE
   deployment.apps/oadp-operator-controller-manager    1/1     1            1           2m9s
   deployment.apps/velero                              1/1     1            1           96s
   
   NAME                                                           DESIRED   CURRENT   READY   AGE
   replicaset.apps/oadp-operator-controller-manager-67d9494d47    1         1         1       2m9s
   replicaset.apps/velero-588db7f655                              1         1         1       96s

2. Verify that the DataProtectionApplication (DPA) is reconciled by running the following command:

   $ oc get dpa dpa-sample -n openshift-adp -o jsonpath='{.status}'

   {"conditions":[{"lastTransitionTime":"2023-10-27T01:23:57Z","message":"Reconcile complete","reason":"Complete","status":"True","type":"Reconciled"}]}

3. Verify the type is set to Reconciled.

4. Verify the backup storage location and confirm that the PHASE is Available by running the following command:

   $ oc get backupstoragelocations.velero.io -n openshift-adp

   NAME           PHASE       LAST VALIDATED   AGE     DEFAULT
   dpa-sample-1   Available   1s               3d16h   true

1. Backup discovery: Identify which Velero backups contain a specified virtual machine by creating a VirtualMachineBackupsDiscovery (VMBD) custom resource (CR).
2. File restore: Make the discovered backup files accessible for browsing and downloading by creating a VirtualMachineFileRestore (VMFR) CR.

Procedure

1. Edit the DataProtectionApplication CR to enable the VMFR feature:

   apiVersion: oadp.openshift.io/v1alpha1
   kind: DataProtectionApplication
   metadata:
     name: oadp-backup
     namespace: openshift-adp
   spec:
     configuration:
       nodeAgent:
         enable: true
         uploaderType: kopia
       velero:
         defaultPlugins:
           - kubevirt
           - csi
           - openshift
           - aws
         disableFsBackup: false
     vmFileRestore:
       enable: true
     backupLocations:
       - velero:
           config:
             profile: "default"
             region: <region>
           provider: aws
           default: true
           credential:
             key: cloud
             name: <cloud_credentials>
           objectStorage:
             bucket: <bucket_name>
             prefix: velero

   where:

   kubevirt

   Specifies the kubevirt Velero plugin in the defaultPlugins list. This plugin is required for VM backup and file-level restore operations.

   vmFileRestore

   Specifies the section in the DPA spec to enable the VMFR feature.

   enable

   Specifies whether to enable the VMFR feature. Set to true to enable the feature.

2. Apply the DPA configuration by running the following command:

   $ oc apply -f <dpa_cr_filename>

   Replace <dpa_cr_filename> with the file name containing the DPA CR configuration.

Verification

1. To verify that the DPA is reconciled with the VMFR feature enabled, run the following command:

   $ oc get dpa -n openshift-adp -o yaml

   In the output, verify that the status.conditions section includes a condition with type: VMFileRestoreReady and status: "True".

2. To verify that the oadp-vm-file-restore-controller-manager pod is running, run the following command:

   $ oc get pod -n openshift-adp

   The output should include a running oadp-vm-file-restore-controller-manager pod.

Procedure

1. Create a VirtualMachineBackupsDiscovery CR YAML manifest file with the following configuration:

   apiVersion: oadp.openshift.io/v1alpha1
   kind: VirtualMachineBackupsDiscovery
   metadata:
     name: find-my-vm-backups
     namespace: openshift-adp
   spec:
     virtualMachineName: "production-web-server"
     virtualMachineNamespace: "production"

   where:

   name

   Specifies a name for the VMBD CR. For example, find-my-vm-backups.

   namespace

   Specifies the namespace where the VMBD CR is created. This must be the OADP protected namespace, typically openshift-adp.

   virtualMachineName

   Specifies the name of the virtual machine to search for in backups. For example, production-web-server.

   virtualMachineNamespace

   Specifies the namespace of the target virtual machine. For example, production.

2. Optional: To filter backups by a time range, add startTime and endTime fields to the spec section:

   apiVersion: oadp.openshift.io/v1alpha1
   kind: VirtualMachineBackupsDiscovery
   metadata:
     name: find-my-vm-backups
     namespace: openshift-adp
   spec:
     virtualMachineName: "production-web-server"
     virtualMachineNamespace: "production"
     startTime: "2025-08-01"
     endTime: "2025-09-01"

   where:

   startTime

   Specifies the start of the time range to filter backups. Backups created before this date are excluded.

   endTime

   Specifies the end of the time range to filter backups. Backups created after this date are excluded.

3. Optional: To discover specific backups by name, add the requestedBackups field to the spec section:

   apiVersion: oadp.openshift.io/v1alpha1
   kind: VirtualMachineBackupsDiscovery
   metadata:
     name: find-my-vm-backups
     namespace: openshift-adp
   spec:
     virtualMachineName: "production-web-server"
     virtualMachineNamespace: "production"
     requestedBackups:
       - "initial-backup-from-2024-01-01"
       - "last-working-from-2025-07-28"

   where:

   requestedBackups

   Specifies a list of backup names to include in the discovery. These backups are included regardless of any time range filter.

4. To apply the VMBD CR configuration, run the following command:

   $ oc apply -f <vmbd_cr_filename>

   Replace <vmbd_cr_filename> with the file name containing the VMBD CR configuration.

Procedure

1. [Optional] Create a secret containing the credentials for accessing the file browser:

   If you do not create a secret, the VMFR controller creates a secret for you and references it in the VMFR CR.

   apiVersion: v1
   kind: Secret
   metadata:
     name: vmfr-credentials
     namespace: openshift-adp
   type: Opaque
   data:
     password: <base64_encoded_password>
     username: <base64_encoded_username>

   where:

   password

   Specifies the base64-encoded password for the file browser. The password must be at least 12 characters long before encoding.

   username

   Specifies the base64-encoded username for the file browser.

2. Create a VirtualMachineFileRestore CR YAML manifest file with the following configuration.

   To configure file browser access:

   apiVersion: oadp.openshift.io/v1alpha1
   kind: VirtualMachineFileRestore
   metadata:
     name: restore-config-files
     namespace: openshift-adp
   spec:
     backupsDiscoveryRef: find-my-vm-backups
     selectedBackups:
       - backup-2025-09-20
       - backup-2025-09-15
     fileAccess:
       fileBrowser:
         credentialsSecretRef:
           name: vmfr-credentials
         exposeExternally: true

   To configure SSH access:

   apiVersion: oadp.openshift.io/v1alpha1
   kind: VirtualMachineFileRestore
   metadata:
     name: restore-config-files
     namespace: openshift-adp
   spec:
     backupsDiscoveryRef: find-my-vm-backups
     selectedBackups:
       - backup-2025-09-20
       - backup-2025-09-15
     fileAccess:
       ssh: {}

   where:

   name

   Specifies a name for the VMFR CR. For example, restore-config-files.

   namespace

   Specifies the namespace where the VMFR CR is created. This must be the OADP protected namespace, typically openshift-adp.

   backupsDiscoveryRef

   Specifies the name of the VMBD CR that contains the discovery results. This VMBD CR must be in the Completed phase.

   selectedBackups

   Specifies a list of backup names from the VMBD valid results to restore. A Velero restore operation is created for each backup in this list.

   fileAccess

   Specifies the configuration for accessing the restored files.

   fileBrowser

   Specifies the file browser configuration for web-based access.

   credentialsSecretRef

   Specifies the name of the Kubernetes secret that contains the credentials for file browser access.

   exposeExternally

   Specifies whether to create an external route for accessing the file browser. Set to true to create a publicly accessible route.

   ssh

   Specifies the SSH access configuration. Set to {} to enable SSH access with autogenerated credentials. The controller generates an SSH key pair and stores it in a Kubernetes secret.

   Optionally, you can also specify a username, and publickey for enabling the SSH access as shown in the following example:

   ...
      ssh:
        username: fedora
        publicKey: ""

3. To apply the VMFR CR configuration, run the following command:

   $ oc apply -f <vmfr_cr_filename>

   Replace <vmfr_cr_filename> with the file name containing the VMFR CR configuration.

Procedure

1. To retrieve the file browser access URLs, run the following command:

   $ oc get vmfr <vmfr_cr_name> -n openshift-adp -o jsonpath='{.status.fileServingInfo.fileBrowser}'

   Replace <vmfr_cr_name> with the name of the VMFR CR. The output includes the clusterAccess URL for cluster-internal access and the publicAccess URL if exposeExternally is set to true.

2. If the VMFR CR has exposeExternally set to true, open a web browser and navigate to the publicAccess URL from the status output.

   If exposeExternally is not enabled, set up port forwarding to the file-serving service by running the following command:

   $ oc port-forward svc/vmfr-<vmfr_cr_name>-fileserver-svc -n <restore_namespace> 8443:8443

   Replace <vmfr_cr_name> with the name of the VMFR CR and <restore_namespace> with the namespace from the status.createdNamespace field. Then navigate to https://localhost:8443 in your web browser.

3. Log in by using the credentials from the secret you created for file browser access.

   Figure 15.1. OADP VM File Restore Browser login page

   

4. Browse the files organized by date, backup name, and PVC name.

   Figure 15.2. File browser listing showing backup contents

   

5. View the file content by selecting the file. To download a file, select the file and click Download. To download a directory as an archive, select the directory and click Download.

   Figure 15.3. File preview in the file browser

   

Procedure

1. To retrieve the SSH access information, run the following command:

   $ oc get vmfr <vmfr_cr_name> -o jsonpath='{.status.fileServingInfo.ssh}' | jq

   Replace <vmfr_cr_name> with the name of the VMFR CR. The output includes the clusterAccess URL and credentialsSecretRef containing the name and namespace of the generated SSH key secret.

2. Retrieve the private key from the generated secret and save it to a file:

   $ oc get secret <secret_name> -n <secret_namespace> -o jsonpath='{.data.privateKey}' | base64 -d > id-rsa

   Replace <secret_name> and <secret_namespace> with the values from the status.fileServingInfo.ssh.credentialsSecretRef field.

3. Set the correct permissions on the private key file:

   $ chmod 600 id-rsa

4. Get the name of the file server service created in the VMFR namespace:

   $ oc get svc -n <created_namespace> | grep fileserver

   Replace <created_namespace> with the value from the status.createdNamespace field of the VMFR CR.

5. To copy a file from the backup by using scp, run the following command:

   $ scp -P 2222 -i id-rsa \
     -o StrictHostKeyChecking=no \
     -o UserKnownHostsFile=/dev/null \
     oadp@<fileserver_svc>.<created_namespace>.svc.cluster.local:<remote_path> \
     <local_destination>

   where:

   <fileserver_svc>

   Specifies the name of the file server service.

   <created_namespace>

   Specifies the namespace from the status.createdNamespace field.

   <remote_path>

   Specifies the path to the file in the format /restores/<date>/<backup_name>/<vm_name>/<path_to_file>.

   <local_destination>

   Specifies the local file path to save the restored file.

6. To start an interactive SFTP session, run the following command:

   $ sftp -P 2222 -i id-rsa \
     -o StrictHostKeyChecking=no \
     oadp@<fileserver_svc>.<created_namespace>.svc.cluster.local

Procedure

1. Create a secret for the cloud storage credentials by running the following command:

   $ oc create secret generic <secret_name> -n openshift-adp --from-file cloud=<credentials_file_path>

   where:

   <secret_name>

   Specifies the name of the cloud credentials secret.

   <credentials_file_path>

   Specifies the path to the file that contains the cloud storage credentials.

2. Create a DataProtectionApplication (DPA) CR with the VMFR feature enabled and the kubevirt plugin:

   apiVersion: oadp.openshift.io/v1alpha1
   kind: DataProtectionApplication
   metadata:
     name: vmfr-dpa
     namespace: openshift-adp
   spec:
     backupLocations:
       - velero:
           credential:
             key: cloud
             name: <secret_name>
           default: true
           objectStorage:
             bucket: <bucket_name>
             prefix: velero
           provider: <provider>
     configuration:
       velero:
         defaultPlugins:
           - csi
           - openshift
           - kubevirt
           - <provider>
         disableFsBackup: false
       nodeAgent:
         enable: true
         uploaderType: kopia
     vmFileRestore:
       enable: true

   where:

   <secret_name>

   Specifies the name of the cloud credentials secret you created.

   <bucket_name>

   Specifies the name of the object storage bucket.

   <provider>

   Specifies the cloud provider plugin, such as aws, gcp, or azure.

   vmFileRestore

   Enables the VMFR feature by setting the enable field to true.

3. Apply the DPA configuration by running the following command:

   $ oc apply -f <dpa_cr_filename>

4. Verify that the DPA is reconciled and the VMFR feature is enabled by running the following command:

   $ oc get dpa -n openshift-adp -o yaml

   In the output, verify that the status.conditions section includes a condition with type: VMFileRestoreReady and status: "True".

5. Verify that the velero, nodeAgent, and oadp-vm-file-restore-controller-manager pods are running by running the following command:

   $ oc get pod -n openshift-adp

6. Generate an SSH key pair for accessing the VM:

   $ ssh-keygen -t ed25519 -f ~/.ssh/<vm_key_name> -C "<vm_key_name>"

   Replace <vm_key_name> with a name for the SSH folder and the key file.

7. Create a namespace for the VM by running the following command:

   $ oc create ns <vm_namespace>

8. Create a Kubernetes secret with the SSH public key in the VM namespace:

   $ oc create secret generic <ssh_secret_name> \
     --from-file=key=<path_to_public_key> \
     -n <vm_namespace>

   where:

   <ssh_secret_name>

   Specifies the name of the secret that contains the SSH public key.

   <path_to_public_key>

   Specifies the path to the SSH public key file you created in an earlier step. For example, $HOME/.ssh/vm-key.pub.

   <vm_namespace>

   Specifies the namespace for the VM.

9. Create a VirtualMachine CR by using the built-in VM template fedora-server-small:

   $ oc process -n openshift fedora-server-small -p NAME=<vm_name> | oc apply -n <vm_namespace> -f -

   where:

   <vm_name>

   Specifies the name of the VM.

   <vm_namespace>

   Specifies the namespace for the VM.

10. Wait for the VM to be ready:

    $ oc wait --for=condition=Ready vmi/<vm_name> -n <vm_namespace>

11. Patch the VM configuration accessCredentials object with the SSH public key:

    $ oc patch vm <vm_name> -n <vm_namespace> --type=merge -p '{"spec":{"template":{"spec":{"accessCredentials":[{"sshPublicKey":{"propagationMethod":{"noCloud":{}},"source":{"secret":{"secretName":"<ssh_secret_name>"}}}}]}}}}'

    where:

    <vm_name>

    Specifies the name of the VM.

    <vm_namespace>

    Specifies the namespace for the VM.

    <ssh_secret_name>

    Specifies the name of the secret that contains the SSH public key.

12. SSH to the VM and create a test file:

    $ virtctl ssh <vm_user>@vmi/<vm_name> \
      -n <vm_namespace> \
      --identity-file=$HOME/.ssh/<vm_key_name> \
      --local-ssh-opts="-o StrictHostKeyChecking=no" \
      -c "echo 'Test file for VMFR validation - $(date)' > /home/fedora/test-vmfr-file.txt"

    where:

    <vm_user>

    Specifies the name of the VM user. For the in-built VM template, the user name is fedora.

13. Create a Backup CR to back up the VM namespace:

    apiVersion: velero.io/v1
    kind: Backup
    metadata:
      name: <backup_name>
      namespace: openshift-adp
    spec:
      includedNamespaces:
        - <vm_namespace>
      snapshotMoveData: true

14. Apply the Backup CR by running the following command:

    $ oc apply -f <backup_cr_filename>

15. Verify that the backup is complete by running the following command:

    $ oc get backup.velero <backup_name> -n openshift-adp -o jsonpath='{.status.phase}'

    The output should display Completed.

16. Create a VirtualMachineBackupsDiscovery CR to identify which backups contain the target VM:

    apiVersion: oadp.openshift.io/v1alpha1
    kind: VirtualMachineBackupsDiscovery
    metadata:
      name: <vmbd_name>
      namespace: openshift-adp
    spec:
      virtualMachineName: <vm_name>
      virtualMachineNamespace: <vm_namespace>

17. Apply the VMBD CR by running the following command:

    $ oc apply -f <vmbd_cr_filename>

18. Verify that the discovery is complete by running the following command:

    $ oc get vmbd <vmbd_name> -n openshift-adp

    The PHASE column should display Completed.

19. Create a VirtualMachineFileRestore CR with SSH access to restore files from the discovered backups:

    apiVersion: oadp.openshift.io/v1alpha1
    kind: VirtualMachineFileRestore
    metadata:
      name: <vmfr_name>
      namespace: openshift-adp
    spec:
      backupsDiscoveryRef: <vmbd_name>
      fileAccess:
        ssh: {}

    The ssh: {} configuration instructs the controller to autogenerate an SSH key pair and store it in a Kubernetes secret. The default SSH username is oadp.

20. Apply the VMFR CR by running the following command:

    $ oc apply -f <vmfr_cr_filename>

21. Wait for the VMFR phase to complete:

    $ oc get vmfr <vmfr_name> -n openshift-adp

    The PHASE column should display Completed.

22. Retrieve the SSH access information by running the following command:

    $ oc get vmfr <vmfr_name> -o jsonpath='{.status.fileServingInfo.ssh}' | jq

    The output includes the clusterAccess URL and the credentialsSecretRef containing the name and namespace of the auto generated SSH key secret.

23. Retrieve the private key from the auto generated secret and save it to a file:

    $ oc get secret <secret_name> -n <secret_namespace> -o jsonpath='{.data.privateKey}' | base64 -d > id-rsa

    Replace <secret_name> and <secret_namespace> with the values from the status.fileServingInfo.ssh.credentialsSecretRef field.

24. Copy the private key to the VM so that you can use it for scp from within the VM:

    $ virtctl scp id-rsa \
      <vm_user>@vmi/<vm_name>:/home/<vm_user>/id-rsa \
      -n <vm_namespace> \
      --identity-file=$HOME/.ssh/<vm_key_name>

25. Update the file permissions on the private key inside the VM:

    $ virtctl ssh <vm_user>@vmi/<vm_name> \
      -n <vm_namespace> \
      --identity-file=$HOME/.ssh/<vm_key_name> \
      --local-ssh-opts="-o StrictHostKeyChecking=no" \
      -c "chmod 600 /home/<vm_user>/id-rsa"

26. Get the name of the file server service created in the VMFR namespace:

    $ SVC=$(oc get svc -n <created_namespace> | grep fileserver | awk '{print $1}')

    Replace <created_namespace> with the value from the status.createdNamespace field of the VMFR CR.

27. Restore the file by using scp from within the VM. The remote path format is /restores/<date>/<backup_name>/<vm_name>/<path_to_file>:

    $ virtctl ssh <vm_user>@vmi/<vm_name> \
      -n <vm_namespace> \
      --identity-file=$HOME/.ssh/<vm_key_name> \
      --local-ssh-opts="-o StrictHostKeyChecking=no" \
      -c "scp -P 2222 \
      -i /home/<vm_user>/id-rsa \
      -o StrictHostKeyChecking=no \
      -o UserKnownHostsFile=/dev/null \
      oadp@<fileserver_svc>.<created_namespace>.svc.cluster.local:<remote_path> \
      /tmp/restored.txt"

    where:

    <fileserver_svc>

    Specifies the name of the file server service you retrieved in an earlier step.

    <created_namespace>

    Specifies the namespace from the status.createdNamespace field.

    <remote_path>

    Specifies the path to the file in the format /restores/<date>/<backup_name>/<vm_name>/<path_to_file>. For example, "/restores/2026-02-10/test-backup/fedora-vm-test/home/fedora/test-vmfr-file.txt"

28. Verify that the restored file is intact by comparing MD5 checksums:

    $ virtctl ssh <vm_user>@vmi/<vm_name> \
      -n <vm_namespace> \
      --identity-file=$HOME/.ssh/<vm_key_name> \
      --local-ssh-opts="-o StrictHostKeyChecking=no" \
      -c "echo '===MD5 Checksums===' && md5sum /home/fedora/test-vmfr-file.txt /tmp/restored.txt"

    The checksums of the original and restored files should match. You should see an output as shown in the following example:

    ===MD5 Checksums===
    92245490c552e83baf5f2a2e898d9fff  /home/fedora/test-vmfr-file.txt
    92245490c552e83baf5f2a2e898d9fff  /tmp/restored.txt

29. After you have recovered the files, delete the VMFR CR to clean up resources:

    $ oc delete vmfr <vmfr_name> -n openshift-adp