Merge pull request #101140 from openshift-cherrypick-robot/cherry-pick-100389-to-enterprise-4.17

[enterprise-4.17] 4.18 backport dita oadp troubleshooting

Author: shdeshpa07

_attributes/common-attributes.adoc

@@ -37,14 +37,22 @@ endif::[]
 :hybrid-console-second: Hybrid Cloud Console
 :hybrid-console-url: link:https://console.redhat.com[Red Hat Hybrid Cloud Console]
 // OADP attributes
+:velero-domain: velero.io
+:velero-version: 1.14
 :oadp-first: OpenShift API for Data Protection (OADP)
 :oadp-full: OpenShift API for Data Protection
 :oadp-short: OADP
 :oadp-version: 1.4.6
 :oadp-version-1-3: 1.3.6
 :oadp-version-1-4: 1.4.6
 :oadp-bsl-api: backupstoragelocations.velero.io
+:velero-overview: link:https://{velero-domain}/docs/v{velero-version}/locations/[Overview of backup and snapshot locations in the Velero documentation]
 :velero-link: link:https://{velero-domain}/docs/v{velero-version}/[Velero {velero-version}]
+:velero-cli-install: link:https://{velero-domain}/docs/v{velero-version}/basic-install/#install-the-cli["Install the CLI" on the Velero website]
+:velero-1.12: link:https://{velero-domain}/docs/v1.12/[1.12]
+:velero-1.14: link:https://{velero-domain}/docs/v1.14/[1.14]
+:velero-1.16: link:https://{velero-domain}/docs/v1.16/[1.16]
+:ocp-user-workload-monitoring: link:https://docs.redhat.com/en/documentation/openshift_container_platform/{product-version}/html/monitoring/configuring-user-workload-monitoring[Configuring user workload monitoring]
 :oc-first: pass:quotes[OpenShift CLI (`oc`)]
 :product-registry: OpenShift image registry
 :product-mirror-registry: Mirror registry for Red Hat OpenShift
@@ -62,8 +70,6 @@ endif::[]
 :descheduler-operator: Kube Descheduler Operator
 :cli-manager: CLI Manager Operator
 // Backup and restore
-:velero-domain: velero.io
-:velero-version: 1.14
 :launch: image:app-launcher.png[title="Application Launcher"]
 :mtc-first: Migration Toolkit for Containers (MTC)
 :mtc-short: MTC

backup_and_restore/application_backup_and_restore/installing/about-installing-oadp.adoc

@@ -1,13 +1,16 @@
 :_mod-docs-content-type: ASSEMBLY
 [id="about-installing-oadp"]
 = About installing OADP
+:toc:
+
 include::_attributes/common-attributes.adoc[]
 include::_attributes/attributes-openshift-dedicated.adoc[]
 :context: about-installing-oadp
 
-toc::[]
 
-As a cluster administrator, you install the OpenShift API for Data Protection (OADP) by installing the OADP Operator. The OADP Operator installs link:https://{velero-domain}/docs/v{velero-version}/[Velero {velero-version}].
+
+[role="_abstract"]
+As a cluster administrator, you install the OpenShift API for Data Protection (OADP) by installing the OADP Operator. The OADP Operator installs {velero-link}.
 
 include::snippets/oadp-mtc-operator.adoc[]
 
@@ -57,7 +60,7 @@ include::modules/oadp-configuring-noobaa-for-dr.adoc[leveloffset=+1]
 [role="_additional-resources"]
 .Additional resources
 
-* link:https://{velero-domain}/docs/v{velero-version}/locations/[Overview of backup and snapshot locations in the Velero documentation]
+* {velero-overview}
 
 include::modules/about-oadp-update-channels.adoc[leveloffset=+1]
 include::modules/about-installing-oadp-on-multiple-namespaces.adoc[leveloffset=+1]

backup_and_restore/application_backup_and_restore/troubleshooting/backup-and-restore-cr-issues.adoc

@@ -1,15 +1,18 @@
 :_mod-docs-content-type: ASSEMBLY
 [id="backup-and-restore-cr-issues"]
 = Backup and Restore CR issues
+:toc:
+
 include::_attributes/common-attributes.adoc[]
 include::_attributes/attributes-openshift-dedicated.adoc[]
 :context: backup-and-restore-cr-issues
 :namespace: openshift-adp
 :local-product: OADP
 
-toc::[]
 
-You might encounter these common issues with `Backup` and `Restore` custom resources (CRs).
+
+[role="_abstract"]
+You might encounter the following common issues with `Backup` and `Restore` custom resources (CRs):
 
 [id="backup-cannot-retrieve-volume_{context}"]
 == Backup CR cannot retrieve volume

backup_and_restore/application_backup_and_restore/troubleshooting/issues-with-velero-and-admission-webhooks.adoc

@@ -1,6 +1,8 @@
 :_mod-docs-content-type: ASSEMBLY
 [id="issues-with-velero-and-admission-webhooks"]
-= Issues with Velero and admission webhooks
+= Restoring workarounds for Velero backups that use admission webhooks
+:toc:
+
 include::_attributes/common-attributes.adoc[]
 include::_attributes/attributes-openshift-dedicated.adoc[]
 :context: issues-with-velero-and-admission-webhooks
@@ -9,6 +11,7 @@ include::_attributes/attributes-openshift-dedicated.adoc[]
 
 toc::[]
 
+[role="_abstract"]
 Velero has limited abilities to resolve admission webhook issues during a restore. If you have workloads with admission webhooks, you might need to use an additional Velero plugin or make changes to how you restore the workload.
 
 Typically, workloads with admission webhooks require you to create a resource of a specific kind first. This is especially true if your workload has child resources because admission webhooks typically block child resources.

backup_and_restore/application_backup_and_restore/troubleshooting/oadp-installation-issues.adoc

@@ -1,15 +1,18 @@
 :_mod-docs-content-type: ASSEMBLY
 [id="oadp-installation-issues"]
 = OADP installation issues
+:toc:
+
 include::_attributes/common-attributes.adoc[]
 include::_attributes/attributes-openshift-dedicated.adoc[]
 :context: installation-issues
 :namespace: openshift-adp
 :local-product: OADP
 
-toc::[]
 
-You might encounter issues caused by using invalid directories or incorrect credentials when you install the Data Protection Application.
+
+[role="_abstract"]
+You might encounter issues caused by using invalid directories or incorrect credentials when you install the Data Protection Application (DPA).
 
 [id="oadp-backup-location-contains-invalid-directories_{context}"]
 == Backup storage contains invalid directories

backup_and_restore/application_backup_and_restore/troubleshooting/oadp-monitoring.adoc

@@ -1,14 +1,17 @@
 :_mod-docs-content-type: ASSEMBLY
 [id="oadp-monitoring"]
 = OADP monitoring
+:toc:
+
 include::_attributes/common-attributes.adoc[]
 include::_attributes/attributes-openshift-dedicated.adoc[]
 :context: oadp-monitoring
 :namespace: openshift-adp
 :local-product: OADP
 
-toc::[]
 
+
+[role="_abstract"]
 By using the {product-title} monitoring stack, users and administrators can effectively perform the following tasks:
 
 * Monitor and manage clusters

backup_and_restore/application_backup_and_restore/troubleshooting/oadp-operator-issues.adoc

@@ -1,14 +1,17 @@
 :_mod-docs-content-type: ASSEMBLY
 [id="oadp-operator-issues"]
 = OADP Operator issues
+:toc:
+
 include::_attributes/common-attributes.adoc[]
 include::_attributes/attributes-openshift-dedicated.adoc[]
 :context: oadp-operator-issues
 :namespace: openshift-adp
 :local-product: OADP
 
-toc::[]
 
+
+[role="_abstract"]
 The {oadp-first} Operator might encounter issues caused by problems it is not able to resolve.
 
 [id="oadp-operator-fails-silently_{context}"]

backup_and_restore/application_backup_and_restore/troubleshooting/oadp-timeouts.adoc

@@ -1,14 +1,17 @@
 :_mod-docs-content-type: ASSEMBLY
 [id="oadp-timeouts"]
 = OADP timeouts
+:toc:
+
 include::_attributes/common-attributes.adoc[]
 include::_attributes/attributes-openshift-dedicated.adoc[]
 :context: oadp-timeouts
 :namespace: openshift-adp
 :local-product: OADP
 
-toc::[]
 
+
+[role="_abstract"]
 Extending a timeout allows complex or resource-intensive processes to complete successfully without premature termination. This configuration can reduce errors, retries, or failures.
 
 Ensure that you balance timeout extensions in a logical manner so that you do not configure excessively long timeouts that might hide underlying issues in the process. Consider and monitor an appropriate timeout value that meets the needs of the process and the overall system performance.

backup_and_restore/application_backup_and_restore/troubleshooting/pods-crash-or-restart-due-to-lack-of-memory-or-cpu.adoc

@@ -1,6 +1,8 @@
 :_mod-docs-content-type: ASSEMBLY
 [id="pods-crash-or-restart-due-to-lack-of-memory-or-cpu"]
 = Pods crash or restart due to lack of memory or CPU
+:toc:
+
 include::_attributes/common-attributes.adoc[]
 include::_attributes/attributes-openshift-dedicated.adoc[]
 :context: pods-crash-or-restart-due-to-lack-of-memory-or-cpu
@@ -9,11 +11,11 @@ include::_attributes/attributes-openshift-dedicated.adoc[]
 :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::[]
 
-If a Velero or Restic pod crashes due to a lack of memory or CPU, you can set specific resource requests for either of those resources.
 
-The values for the resource request fields must follow the same format as Kubernetes resource requirements.
+[role="_abstract"]
+If a Velero or Restic pod crashes due to a lack of memory or CPU, you can set specific resource requests for either of those resources. The values for the resource request fields must follow the same format as Kubernetes resource requirements.
+
 If you do not specify `configuration.velero.podConfig.resourceAllocations` or `configuration.restic.podConfig.resourceAllocations`, see the following default `resources` specification configuration for a Velero or Restic pod:
 
 [source,yaml]

backup_and_restore/application_backup_and_restore/troubleshooting/restic-issues.adoc

@@ -1,15 +1,18 @@
 :_mod-docs-content-type: ASSEMBLY
 [id="restic-issues"]
 = Restic issues
+:toc:
+
 include::_attributes/common-attributes.adoc[]
 include::_attributes/attributes-openshift-dedicated.adoc[]
 :context: restic-issues
 :namespace: openshift-adp
 :local-product: OADP
 
-toc::[]
 
-You might encounter these issues when you back up applications with Restic.
+
+[role="_abstract"]
+You might encounter the following issues when you back up applications with Restic:
 
 [id="restic-permission-error-nfs-root-squash-enabled_{context}"]
 == Restic permission error for NFS data volumes with root_squash enabled