OADP-6202 move one level up

shdeshpa07 · openshift-cherrypick-robot · commit f85369b91199 · 2025-06-05T07:47:54.000Z
Signed-off-by: Shruti Deshpande &lt;shdeshpa@redhat.com&gt;
diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml
@@ -3660,29 +3660,58 @@ Topics:
       File: oadp-usecase-enable-ca-cert
     - Name: Using the legacy-aws Velero plugin
       File: oadp-usecase-legacy-aws-plugin
-  - Name: Installing and configuring OADP
+    - Name: Backing up workloads on OADP with ROSA STS
+      File: oadp-rosa-backup-restore
+  - Name: Installing OADP
     Dir: installing
     Topics:
     - Name: About installing OADP
       File: about-installing-oadp
     - Name: Installing the OADP Operator
       File: oadp-installing-operator
+  - Name: Configuring OADP with AWS S3 compatible storage
+    Dir: installing
+    Topics:
     - Name: Configuring OADP with AWS S3 compatible storage
       File: installing-oadp-aws
+  - Name: Configuring OADP with IBM Cloud
+    Dir: installing
+    Topics:
     - Name: Configuring OADP with IBM Cloud
       File: installing-oadp-ibm-cloud
+  - Name: Configuring OADP with Azure
+    Dir: installing
+    Topics:
     - Name: Configuring OADP with Azure
       File: installing-oadp-azure
+  - Name: Configuring OADP with GCP
+    Dir: installing
+    Topics:
     - Name: Configuring OADP with GCP
       File: installing-oadp-gcp
+  - Name: Configuring OADP with MCG
+    Dir: installing
+    Topics:
     - Name: Configuring OADP with MCG
       File: installing-oadp-mcg
+  - Name: Configuring OADP with ODF
+    Dir: installing
+    Topics:
     - Name: Configuring OADP with ODF
       File: installing-oadp-ocs
+  - Name: Configuring OADP with OpenShift Virtualization
+    Dir: installing
+    Topics:
     - Name: Configuring OADP with OpenShift Virtualization
       File: installing-oadp-kubevirt
+  - Name: Configuring OADP with multiple backup storage locations
+    Dir: installing
+    Topics:
     - Name: Configuring OADP with multiple backup storage locations
       File: configuring-oadp-multiple-bsl
+  - Name: Configuring OADP with multiple Volume Snapshot Locations
+    Dir: installing
+    Topics:
     - Name: Configuring OADP with multiple Volume Snapshot Locations
       File: configuring-oadp-multiple-vsl
   - Name: Uninstalling OADP
@@ -3757,28 +3786,31 @@ Topics:
     File: oadp-api
   - Name: Advanced OADP features and functionalities
     File: oadp-advanced-topics
-  - Name: Troubleshooting OADP
-    File: troubleshooting
-  - Name: Velero CLI tool
-    File: velero-cli-tool
-  - Name: Pods crash or restart due to lack of memory or CPU
-    File: pods-crash-or-restart-due-to-lack-of-memory-or-cpu
-  - Name: Issues with Velero and admission webhooks
-    File: issues-with-velero-and-admission-webhooks
-  - Name: OADP installation issues
-    File: oadp-installation-issues
-  - Name: OADP Operator issues
-    File: oadp-operator-issues
-  - Name: OADP timeouts
-    File: oadp-timeouts
-  - Name: Backup and Restore CR issues
-    File: backup-and-restore-cr-issues
-  - Name: Restic issues
-    File: restic-issues
-  - Name: Using the must-gather tool
-    File: using-the-must-gather-tool
-  - Name: OADP monitoring
-    File: oadp-monitoring
+  - Name: OADP troubleshooting
+    Dir: troubleshooting
+    Topics:
+    - Name: Troubleshooting OADP
+      File: troubleshooting
+    - Name: Velero CLI tool
+      File: velero-cli-tool
+    - Name: Pods crash or restart due to lack of memory or CPU
+      File: pods-crash-or-restart-due-to-lack-of-memory-or-cpu
+    - Name: Issues with Velero and admission webhooks
+      File: issues-with-velero-and-admission-webhooks
+    - Name: OADP installation issues
+      File: oadp-installation-issues
+    - Name: OADP Operator issues
+      File: oadp-operator-issues
+    - Name: OADP timeouts
+      File: oadp-timeouts
+    - Name: Backup and Restore CR issues
+      File: backup-and-restore-cr-issues
+    - Name: Restic issues
+      File: restic-issues
+    - Name: Using the must-gather tool
+      File: using-the-must-gather-tool
+    - Name: OADP monitoring
+      File: oadp-monitoring
 - Name: Control plane backup and restore
   Dir: control_plane_backup_and_restore
   Topics:
@@ -4729,28 +4761,28 @@ Topics:
 - Name: Advanced VM creation
   Dir: creating_vms_advanced
   Topics:
-    - Name: Advanced virtual machine creation overview
-      File: advanced-vm-creation-overview
-    - Name: Creating VMs in the web console
-      Dir: creating_vms_advanced_web
-      Topics:
-      - Name: Creating VMs from Red Hat images
-        File: virt-creating-vms-from-rh-images-overview
-      - Name: Creating VMs by importing images from web pages
-        File: virt-creating-vms-from-web-images
-      - Name: Creating VMs by uploading images
-        File: virt-creating-vms-uploading-images
-      - Name: Cloning VMs
-        File: virt-cloning-vms
-    - Name: Creating VMs using the CLI
-      Dir: creating_vms_cli
-      Topics:
-      - Name: Creating virtual machines from the command line
-        File: virt-creating-vms-from-cli
-      - Name: Creating VMs by using container disks
-        File: virt-creating-vms-from-container-disks
-      - Name: Creating VMs by cloning PVCs
-        File: virt-creating-vms-by-cloning-pvcs
+  - Name: Advanced virtual machine creation overview
+    File: advanced-vm-creation-overview
+  - Name: Creating VMs in the web console
+    Dir: creating_vms_advanced_web
+    Topics:
+    - Name: Creating VMs from Red Hat images
+      File: virt-creating-vms-from-rh-images-overview
+    - Name: Creating VMs by importing images from web pages
+      File: virt-creating-vms-from-web-images
+    - Name: Creating VMs by uploading images
+      File: virt-creating-vms-uploading-images
+    - Name: Cloning VMs
+      File: virt-cloning-vms
+  - Name: Creating VMs using the CLI
+    Dir: creating_vms_cli
+    Topics:
+    - Name: Creating virtual machines from the command line
+      File: virt-creating-vms-from-cli
+    - Name: Creating VMs by using container disks
+      File: virt-creating-vms-from-container-disks
+    - Name: Creating VMs by cloning PVCs
+      File: virt-creating-vms-by-cloning-pvcs
 - Name: Managing VMs
   Dir: managing_vms
   Topics:
diff --git a/backup_and_restore/application_backup_and_restore/backing_up_and_restoring/backing-up-applications.adoc b/backup_and_restore/application_backup_and_restore/backing_up_and_restoring/backing-up-applications.adoc
@@ -61,7 +61,7 @@ You can schedule backups by creating a `Schedule` CR instead of a `Backup` CR. S
 This issue has been resolved in the OADP 1.1.6 and OADP 1.2.2 releases, therefore it is recommended that users upgrade to these releases.
 
 ifndef::openshift-rosa,openshift-rosa-hcp[]
-For more information, see xref:../../../backup_and_restore/application_backup_and_restore/restic-issues.adoc#oadp-restic-restore-failing-psa-policy_restic-issues[Restic restore partially failing on OCP 4.15 due to changed PSA policy].
+For more information, see xref:../../../backup_and_restore/application_backup_and_restore/troubleshooting/restic-issues.adoc#oadp-restic-restore-failing-psa-policy_restic-issues[Restic restore partially failing on OCP 4.15 due to changed PSA policy].
 endif::openshift-rosa,openshift-rosa-hcp[]
 
 // TODO: Add xrefs to ROSA HCP when Operators book is added.
diff --git a/backup_and_restore/application_backup_and_restore/troubleshooting.adoc b/backup_and_restore/application_backup_and_restore/troubleshooting.adoc
diff --git a/backup_and_restore/application_backup_and_restore/troubleshooting/_attributes b/backup_and_restore/application_backup_and_restore/troubleshooting/_attributes
@@ -0,0 +1 @@
+../../../_attributes/
diff --git a/backup_and_restore/application_backup_and_restore/troubleshooting/backup-and-restore-cr-issues.adoc b/backup_and_restore/application_backup_and_restore/troubleshooting/backup-and-restore-cr-issues.adoc
diff --git a/backup_and_restore/application_backup_and_restore/troubleshooting/images b/backup_and_restore/application_backup_and_restore/troubleshooting/images
@@ -0,0 +1 @@
+../../../images/
diff --git a/backup_and_restore/application_backup_and_restore/troubleshooting/issues-with-velero-and-admission-webhooks.adoc b/backup_and_restore/application_backup_and_restore/troubleshooting/issues-with-velero-and-admission-webhooks.adoc
@@ -28,6 +28,6 @@ include::modules/oadp-plugins-receiving-eof-message.adoc[leveloffset=+1]
 [role="_additional-resources"]
 .Additional resources
 
-* xref:../../architecture/admission-plug-ins.adoc#admission-plug-ins[Admission plugins]
-* xref:../../architecture/admission-plug-ins.adoc#admission-webhooks-about_admission-plug-ins[Webhook admission plugins]
-* xref:../../architecture/admission-plug-ins.adoc#admission-webhook-types_admission-plug-ins[Types of webhook admission plugins]
+* xref:../../../architecture/admission-plug-ins.adoc#admission-plug-ins[Admission plugins]
+* xref:../../../architecture/admission-plug-ins.adoc#admission-webhooks-about_admission-plug-ins[Webhook admission plugins]
+* xref:../../../architecture/admission-plug-ins.adoc#admission-webhook-types_admission-plug-ins[Types of webhook admission plugins]
diff --git a/backup_and_restore/application_backup_and_restore/troubleshooting/modules b/backup_and_restore/application_backup_and_restore/troubleshooting/modules
@@ -0,0 +1 @@
+../../modules/
diff --git a/backup_and_restore/application_backup_and_restore/troubleshooting/oadp-installation-issues.adoc b/backup_and_restore/application_backup_and_restore/troubleshooting/oadp-installation-issues.adoc
diff --git a/backup_and_restore/application_backup_and_restore/troubleshooting/oadp-monitoring.adoc b/backup_and_restore/application_backup_and_restore/troubleshooting/oadp-monitoring.adoc
@@ -18,15 +18,15 @@ By using the {product-title} monitoring stack, users and administrators can effe
 
 [role="_additional-resources"]
 .Additional resources
-* xref:../../observability/monitoring/about-ocp-monitoring/about-ocp-monitoring.adoc#about-ocp-monitoring[About {product-title} monitoring]
+* xref:../../../observability/monitoring/about-ocp-monitoring/about-ocp-monitoring.adoc#about-ocp-monitoring[About {product-title} monitoring]
 
 include::modules/oadp-monitoring-setup.adoc[leveloffset=+1]
 include::modules/oadp-creating-service-monitor.adoc[leveloffset=+1]
 include::modules/oadp-creating-alerting-rule.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
 .Additional resources
-* xref:../../observability/monitoring/managing-alerts/managing-alerts-as-an-administrator.adoc#managing-alerts-as-an-administrator[Managing alerts as an Administrator]
+* xref:../../../observability/monitoring/managing-alerts/managing-alerts-as-an-administrator.adoc#managing-alerts-as-an-administrator[Managing alerts as an Administrator]
 
 include::modules/oadp-list-of-metrics.adoc[leveloffset=+1]
 include::modules/oadp-viewing-metrics-ui.adoc[leveloffset=+1]
diff --git a/backup_and_restore/application_backup_and_restore/troubleshooting/oadp-operator-issues.adoc b/backup_and_restore/application_backup_and_restore/troubleshooting/oadp-operator-issues.adoc
diff --git a/backup_and_restore/application_backup_and_restore/troubleshooting/oadp-timeouts.adoc b/backup_and_restore/application_backup_and_restore/troubleshooting/oadp-timeouts.adoc
@@ -15,17 +15,17 @@ Ensure that you balance timeout extensions in a logical manner so that you do no
 
 The following OADP timeouts show instructions of how and when to implement these parameters:
 
-* xref:../../backup_and_restore/application_backup_and_restore/oadp-timeouts.adoc#restic-timeout_oadp-timeouts[Restic timeout]
+* xref:../../../backup_and_restore/application_backup_and_restore/troubleshooting/oadp-timeouts.adoc#restic-timeout_oadp-timeouts[Restic timeout]
 
-* xref:../../backup_and_restore/application_backup_and_restore/oadp-timeouts.adoc#velero-timeout_oadp-timeouts[Velero resource timeout]
+* xref:../../../backup_and_restore/application_backup_and_restore/troubleshooting/oadp-timeouts.adoc#velero-timeout_oadp-timeouts[Velero resource timeout]
 
-* xref:../../backup_and_restore/application_backup_and_restore/oadp-timeouts.adoc#datamover-timeout_oadp-timeouts[Data Mover timeout]
+* xref:../../../backup_and_restore/application_backup_and_restore/troubleshooting/oadp-timeouts.adoc#datamover-timeout_oadp-timeouts[Data Mover timeout]
 
-* xref:../../backup_and_restore/application_backup_and_restore/oadp-timeouts.adoc#csisnapshot-timeout_oadp-timeouts[CSI snapshot timeout]
+* xref:../../../backup_and_restore/application_backup_and_restore/troubleshooting/oadp-timeouts.adoc#csisnapshot-timeout_oadp-timeouts[CSI snapshot timeout]
 
-* xref:../../backup_and_restore/application_backup_and_restore/oadp-timeouts.adoc#item-operation-timeout-backup_oadp-timeouts[Item operation timeout - backup]
+* xref:../../../backup_and_restore/application_backup_and_restore/troubleshooting/oadp-timeouts.adoc#item-operation-timeout-backup_oadp-timeouts[Item operation timeout - backup]
 
-* xref:../../backup_and_restore/application_backup_and_restore/oadp-timeouts.adoc#item-operation-timeout-restore_oadp-timeouts[Item operation timeout - restore]
+* xref:../../../backup_and_restore/application_backup_and_restore/troubleshooting/oadp-timeouts.adoc#item-operation-timeout-restore_oadp-timeouts[Item operation timeout - restore]
 
 include::modules/oadp-restic-timeouts.adoc[leveloffset=+1]
 include::modules/oadp-velero-timeouts.adoc[leveloffset=+1]
diff --git a/backup_and_restore/application_backup_and_restore/troubleshooting/pods-crash-or-restart-due-to-lack-of-memory-or-cpu.adoc b/backup_and_restore/application_backup_and_restore/troubleshooting/pods-crash-or-restart-due-to-lack-of-memory-or-cpu.adoc
@@ -25,7 +25,7 @@ requests:
 
 [role="_additional-resources"]
 .Additional resources
-* xref:../../backup_and_restore/application_backup_and_restore/installing/about-installing-oadp.adoc#oadp-velero-cpu-memory-requirements_about-installing-oadp[Velero CPU and memory requirements based on collected data]
+* xref:../../../backup_and_restore/application_backup_and_restore/installing/about-installing-oadp.adoc#oadp-velero-cpu-memory-requirements_about-installing-oadp[Velero CPU and memory requirements based on collected data]
 
 include::modules/oadp-pod-crash-set-resource-request-velero.adoc[leveloffset=+1]
 include::modules/oadp-pod-crash-set-resource-request-restic.adoc[leveloffset=+1]
diff --git a/backup_and_restore/application_backup_and_restore/troubleshooting/restic-issues.adoc b/backup_and_restore/application_backup_and_restore/troubleshooting/restic-issues.adoc
diff --git a/backup_and_restore/application_backup_and_restore/troubleshooting/snippets b/backup_and_restore/application_backup_and_restore/troubleshooting/snippets
@@ -0,0 +1 @@
+../../../snippets/
diff --git a/backup_and_restore/application_backup_and_restore/troubleshooting/troubleshooting.adoc b/backup_and_restore/application_backup_and_restore/troubleshooting/troubleshooting.adoc
@@ -0,0 +1,32 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="troubleshooting"]
+= Troubleshooting
+include::_attributes/common-attributes.adoc[]
+include::_attributes/attributes-openshift-dedicated.adoc[]
+:context: oadp-troubleshooting
+:oadp-troubleshooting:
+:namespace: openshift-adp
+:local-product: OADP
+:must-gather-v1-3: registry.redhat.io/oadp/oadp-mustgather-rhel9:v1.3
+:must-gather-v1-4: registry.redhat.io/oadp/oadp-mustgather-rhel9:v1.4
+
+toc::[]
+
+You can troubleshoot OADP issues by using the following methods:
+
+* Debug Velero custom resources (CRs) by using the xref:../../../backup_and_restore/application_backup_and_restore/troubleshooting/velero-cli-tool.adoc#oadp-debugging-oc-cli_velero-cli-tool[OpenShift CLI tool] or the xref:../../../backup_and_restore/application_backup_and_restore/troubleshooting/velero-cli-tool.adoc#migration-debugging-velero-resources_velero-cli-tool[Velero CLI tool]. The Velero CLI tool provides more detailed logs and information.
+
+* Debug Velero or Restic pod crashes, which are caused due to a lack of memory or CPU by using xref:../../../backup_and_restore/application_backup_and_restore/troubleshooting/pods-crash-or-restart-due-to-lack-of-memory-or-cpu.adoc#pods-crash-or-restart-due-to-lack-of-memory-or-cpu[Pods crash or restart due to lack of memory or CPU].
+
+* Debug issues with Velero and admission webhooks by using xref:../../../backup_and_restore/application_backup_and_restore/troubleshooting/issues-with-velero-and-admission-webhooks.adoc#issues-with-velero-and-admission-webhooks[Issues with Velero and admission webhooks].
+
+* Check xref:../../../backup_and_restore/application_backup_and_restore/troubleshooting/oadp-installation-issues.adoc#oadp-installation-issues[OADP installation issues], xref:../../../backup_and_restore/application_backup_and_restore/troubleshooting/oadp-operator-issues.adoc#oadp-operator-issues[OADP Operator issues], xref:../../../backup_and_restore/application_backup_and_restore/troubleshooting/backup-and-restore-cr-issues.adoc#backup-and-restore-cr-issues[backup and restore CR issues], and xref:../../../backup_and_restore/application_backup_and_restore/troubleshooting/restic-issues.adoc#restic-issues[Restic issues].
+
+* Use the available xref:../../../backup_and_restore/application_backup_and_restore/troubleshooting/oadp-timeouts.adoc#oadp-timeouts[OADP timeouts] to reduce errors, retries, or failures.
+
+* Collect logs and CR information by using the xref:../../../backup_and_restore/application_backup_and_restore/troubleshooting/using-the-must-gather-tool.adoc#using-the-must-gather-tool[`must-gather` tool].
+
+* Monitor and analyze the workload performance with the help of xref:../../../backup_and_restore/application_backup_and_restore/troubleshooting/oadp-monitoring.adoc#oadp-monitoring[OADP monitoring].
+
+
+:oadp-troubleshooting!:
diff --git a/backup_and_restore/application_backup_and_restore/troubleshooting/using-the-must-gather-tool.adoc b/backup_and_restore/application_backup_and_restore/troubleshooting/using-the-must-gather-tool.adoc
@@ -70,7 +70,7 @@ This operation can take a long time. The data is saved as `must-gather/metrics/p
 
 [role="_additional-resources"]
 .Additional resources
-* xref:../../support/gathering-cluster-data.adoc#gathering-cluster-data[Gathering cluster data]
+* xref:../../../support/gathering-cluster-data.adoc#gathering-cluster-data[Gathering cluster data]
 
 include::modules/support-insecure-tls-connections.adoc[leveloffset=+1]
 include::modules/migration-combining-must-gather.adoc[leveloffset=+1]
diff --git a/backup_and_restore/application_backup_and_restore/troubleshooting/velero-cli-tool.adoc b/backup_and_restore/application_backup_and_restore/troubleshooting/velero-cli-tool.adoc
diff --git a/backup_and_restore/index.adoc b/backup_and_restore/index.adoc
@@ -38,7 +38,7 @@ You can always recover from a disaster situation by xref:../backup_and_restore/c
 
 As a cluster administrator, you can back up and restore applications running on {product-title} by using the OpenShift API for Data Protection (OADP).
 
-OADP backs up and restores Kubernetes resources and internal images, at the granularity of a namespace, by using the version of Velero that is appropriate for the version of OADP you install, according to the table in xref:../backup_and_restore/application_backup_and_restore/velero-cli-tool.adoc#velero-obtaining-by-downloading_velero-cli-tool[Downloading the Velero CLI tool].  OADP backs up and restores persistent volumes (PVs) by using snapshots or Restic. For details, see xref:../backup_and_restore/application_backup_and_restore/oadp-features-plugins.adoc#oadp-features_oadp-features-plugins[OADP features].
+OADP backs up and restores Kubernetes resources and internal images, at the granularity of a namespace, by using the version of Velero that is appropriate for the version of OADP you install, according to the table in xref:../backup_and_restore/application_backup_and_restore/troubleshooting/velero-cli-tool.adoc#velero-obtaining-by-downloading_velero-cli-tool[Downloading the Velero CLI tool].  OADP backs up and restores persistent volumes (PVs) by using snapshots or Restic. For details, see xref:../backup_and_restore/application_backup_and_restore/oadp-features-plugins.adoc#oadp-features_oadp-features-plugins[OADP features].
 
 [id="oadp-requirements"]
 === OADP requirements
