Merge pull request #91436 from stevsmit/OADP-4561-4-19-manual-cp

[enterprise-4.19] OADP-4561: Update parent ToC for Troubleshooting modules

Author: stevsmit

_topic_maps/_topic_map.yml

@@ -3670,12 +3670,32 @@ Topics:
       File: oadp-backup-restore-csi-snapshots
     - Name: Overriding Kopia algorithms
       File: overriding-kopia-algorithms
-  - Name: Troubleshooting
-    File: troubleshooting
   - Name: OADP API
     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: Control plane backup and restore
   Dir: control_plane_backup_and_restore
   Topics:

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/troubleshooting.adoc#oadp-restic-restore-failing-psa-policy_oadp-troubleshooting[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/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.

modules/oadp-backup-restore-cr-issues.adoc renamed to backup_and_restore/application_backup_and_restore/backup-and-restore-cr-issues.adoc

@@ -1,17 +1,20 @@
-// Module included in the following assemblies:
-//
-// * backup_and_restore/application_backup_and_restore/troubleshooting.adoc
-
-:_mod-docs-content-type: CONCEPT
-[id="oadp-backup-restore-cr-issues_{context}"]
+:_mod-docs-content-type: ASSEMBLY
+[id="backup-and-restore-cr-issues"]
 = Backup and Restore CR issues
+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).
 
 [id="backup-cannot-retrieve-volume_{context}"]
 == Backup CR cannot retrieve volume
 
-The `Backup` CR displays the error message, `InvalidVolume.NotFound: The volume ‘vol-xxxx’ does not exist`.
+The `Backup` CR displays the following error message: `InvalidVolume.NotFound: The volume ‘vol-xxxx’ does not exist`.
 
 .Cause
 
@@ -33,26 +36,26 @@ If a backup is interrupted, it cannot be resumed.
 
 .Solution
 
-. Retrieve the details of the `Backup` CR:
+. Retrieve the details of the `Backup` CR by running the following command:
 +
 [source,terminal]
 ----
 $ oc -n {namespace} exec deployment/velero -c velero -- ./velero \
   backup describe <backup>
 ----
 
-. Delete the `Backup` CR:
+. Delete the `Backup` CR by running the following command:
 +
 [source,terminal]
 ----
 $ oc delete backups.velero.io <backup> -n openshift-adp
 ----
 +
-You do not need to clean up the backup location because a `Backup` CR in progress has not uploaded files to object storage.
+You do not need to clean up the backup location because an in progress `Backup` CR has not uploaded files to object storage.
 
 . Create a new `Backup` CR.
 
-. View the Velero backup details
+. View the Velero backup details by running the following command:
 +
 [source,terminal, subs="+quotes"]
 ----
@@ -62,11 +65,11 @@ $ velero backup describe _<backup-name>_ --details
 [id="backup-cr-remains-partiallyfailed_{context}"]
 == Backup CR status remains in PartiallyFailed
 
-The status of a `Backup` CR without Restic in use remains in the `PartiallyFailed` phase and does not complete. A snapshot of the affiliated PVC is not created.
+The status of a `Backup` CR without Restic in use remains in the `PartiallyFailed` phase and is not completed. A snapshot of the affiliated PVC is not created.
 
 .Cause
 
-If the backup is created based on the CSI snapshot class, but the label is missing, CSI snapshot plugin fails to create a snapshot. As a result, the `Velero` pod logs an error similar to the following:
+If the backup created based on the CSI snapshot class is missing a label, the CSI snapshot plugin fails to create a snapshot. As a result, the `Velero` pod logs an error similar to the following message:
 
 [source,text]
 ----
@@ -75,7 +78,7 @@ time="2023-02-17T16:33:13Z" level=error msg="Error backing up item" backup=opens
 
 .Solution
 
-. Delete the `Backup` CR:
+. Delete the `Backup` CR by running the following command::
 +
 [source,terminal]
 ----
@@ -84,11 +87,11 @@ $ oc delete backups.velero.io <backup> -n openshift-adp
 
 . If required, clean up the stored data on the `BackupStorageLocation` to free up space.
 
-. Apply label `velero.io/csi-volumesnapshot-class=true` to the `VolumeSnapshotClass` object:
+. Apply the label `velero.io/csi-volumesnapshot-class=true` to the `VolumeSnapshotClass` object by running the following command:
 +
 [source,terminal]
 ----
 $ oc label volumesnapshotclass/<snapclass_name> velero.io/csi-volumesnapshot-class=true
 ----
 
-. Create a new `Backup` CR.
+. Create a new `Backup` CR.

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

@@ -0,0 +1,33 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="issues-with-velero-and-admission-webhooks"]
+= Issues with Velero and admission webhooks
+include::_attributes/common-attributes.adoc[]
+include::_attributes/attributes-openshift-dedicated.adoc[]
+:context: issues-with-velero-and-admission-webhooks
+:namespace: openshift-adp
+:local-product: OADP
+
+toc::[]
+
+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.
+
+For example, creating or restoring a top-level object such as `service.serving.knative.dev` typically creates child resources automatically. If you do this first, you will not need to use Velero to create and restore these resources. This avoids the problem of child resources being blocked by an admission webhook that Velero might use.
+
+[id="velero-restore-workarounds-for-workloads-with-admission-webhooks_{context}"]
+== Restoring workarounds for Velero backups that use admission webhooks
+
+You need additional steps to restore resources for several types of Velero backups that use admission webhooks.
+
+include::modules/migration-debugging-velero-admission-webhooks-knative.adoc[leveloffset=+2]
+include::modules/migration-debugging-velero-admission-webhooks-ibm-appconnect.adoc[leveloffset=+2]
+include::modules/oadp-features-plugins-known-issues.adoc[leveloffset=+1]
+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]

modules/oadp-installation-issues.adoc renamed to backup_and_restore/application_backup_and_restore/oadp-installation-issues.adoc

@@ -1,17 +1,20 @@
-// Module included in the following assemblies:
-//
-// * backup_and_restore/application_backup_and_restore/troubleshooting.adoc
+:_mod-docs-content-type: ASSEMBLY
+[id="oadp-installation-issues"]
+= OADP installation issues
+include::_attributes/common-attributes.adoc[]
+include::_attributes/attributes-openshift-dedicated.adoc[]
+:context: installation-issues
+:namespace: openshift-adp
+:local-product: OADP
 
-:_mod-docs-content-type: CONCEPT
-[id="oadp-installation-issues_{context}"]
-= Installation issues
+toc::[]
 
 You might encounter issues caused by using invalid directories or incorrect credentials when you install the Data Protection Application.
 
 [id="oadp-backup-location-contains-invalid-directories_{context}"]
 == Backup storage contains invalid directories
 
-The `Velero` pod log displays the error message, `Backup storage contains invalid top-level directories`.
+The `Velero` pod log displays the following error message: `Backup storage contains invalid top-level directories`.
 
 .Cause
 
@@ -24,9 +27,9 @@ If the object storage is not dedicated to Velero, you must specify a prefix for
 [id="oadp-incorrect-aws-credentials_{context}"]
 == Incorrect AWS credentials
 
-The `oadp-aws-registry` pod log displays the error message, `InvalidAccessKeyId: The AWS Access Key Id you provided does not exist in our records.`
+The `oadp-aws-registry` pod log displays the following error message: `InvalidAccessKeyId: The AWS Access Key Id you provided does not exist in our records.`
 
-The `Velero` pod log displays the error message, `NoCredentialProviders: no valid providers in chain`.
+The `Velero` pod log displays the following error message: `NoCredentialProviders: no valid providers in chain`.
 
 .Cause
 

backup_and_restore/application_backup_and_restore/oadp-monitoring.adoc

@@ -0,0 +1,32 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="oadp-monitoring"]
+= OADP monitoring
+include::_attributes/common-attributes.adoc[]
+include::_attributes/attributes-openshift-dedicated.adoc[]
+:context: oadp-monitoring
+:namespace: openshift-adp
+:local-product: OADP
+
+toc::[]
+
+By using the {product-title} monitoring stack, users and administrators can effectively perform the following tasks:
+
+* Monitor and manage clusters
+* Analyze the workload performance of user applications
+* Monitor services running on the clusters
+* Receive alerts if an event occurs
+
+[role="_additional-resources"]
+.Additional resources
+* 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]
+
+include::modules/oadp-list-of-metrics.adoc[leveloffset=+1]
+include::modules/oadp-viewing-metrics-ui.adoc[leveloffset=+1]

modules/oadp-operator-issues.adoc renamed to backup_and_restore/application_backup_and_restore/oadp-operator-issues.adoc

@@ -1,17 +1,20 @@
-// Module included in the following assemblies:
-//
-// * backup_and_restore/application_backup_and_restore/troubleshooting.adoc
-
-:_mod-docs-content-type: PROCEDURE
-[id="oadp-operator-issues_{context}"]
+:_mod-docs-content-type: ASSEMBLY
+[id="oadp-operator-issues"]
 = OADP Operator issues
+include::_attributes/common-attributes.adoc[]
+include::_attributes/attributes-openshift-dedicated.adoc[]
+:context: oadp-operator-issues
+:namespace: openshift-adp
+:local-product: OADP
+
+toc::[]
 
 The {oadp-first} Operator might encounter issues caused by problems it is not able to resolve.
 
 [id="oadp-operator-fails-silently_{context}"]
 == OADP Operator fails silently
 
-The S3 buckets of an OADP Operator might be empty, but when you run the command `oc get po -n <OADP_Operator_namespace>`, you see that the Operator has a status of `Running`.  In such a case, the Operator is said to have _failed silently_ because it incorrectly reports that it is running.
+The S3 buckets of an OADP Operator might be empty, but when you run the command `oc get po -n <oadp_operator_namespace>`, you see that the Operator has a status of `Running`. In such a case, the Operator is said to have _failed silently_ because it incorrectly reports that it is running.
 
 .Cause
 
@@ -23,31 +26,28 @@ Retrieve a list of backup storage locations (BSLs) and check the manifest of eac
 
 .Procedure
 
-. Run one of the following commands to retrieve a list of BSLs:
-
-.. Using the OpenShift CLI:
+. Retrieve a list of BSLs by using either the OpenShift or Velero command-line interface (CLI):
+.. Retrieve a list of BSLs by using the OpenShift CLI (`oc`):
 +
 [source,terminal]
 ----
 $ oc get backupstoragelocations.velero.io -A
 ----
-
-.. Using the Velero CLI:
+.. Retrieve a list of BSLs by using the `velero` CLI:
 +
 [source,terminal]
 ----
-$ velero backup-location get -n <OADP_Operator_namespace>
+$ velero backup-location get -n <oadp_operator_namespace>
 ----
 
-. Using the list of BSLs, run the following command to display the manifest of each BSL, and examine each manifest for an error.
+. Use the list of BSLs from the previous step and run the following command to examine the manifest of each BSL for an error:
 +
 [source,terminal]
 ----
 $ oc get backupstoragelocations.velero.io -n <namespace> -o yaml
 ----
-
++
 .Example result
-
 [source, yaml]
 ----
 apiVersion: v1
@@ -90,4 +90,4 @@ items:
 kind: List
 metadata:
   resourceVersion: ""
-----
+----

backup_and_restore/application_backup_and_restore/oadp-timeouts.adoc

@@ -0,0 +1,36 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="oadp-timeouts"]
+= OADP timeouts
+include::_attributes/common-attributes.adoc[]
+include::_attributes/attributes-openshift-dedicated.adoc[]
+:context: oadp-timeouts
+:namespace: openshift-adp
+:local-product: OADP
+
+toc::[]
+
+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.
+
+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/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/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/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]
+include::modules/oadp-velero-default-timeouts.adoc[leveloffset=+2]
+include::modules/oadp-datamover-timeouts.adoc[leveloffset=+1]
+include::modules/oadp-csi-snapshot-timeouts.adoc[leveloffset=+1]
+include::modules/oadp-item-restore-timeouts.adoc[leveloffset=+1]
+include::modules/oadp-item-backup-timeouts.adoc[leveloffset=+1]

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

@@ -0,0 +1,31 @@
+:_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
+include::_attributes/common-attributes.adoc[]
+include::_attributes/attributes-openshift-dedicated.adoc[]
+:context: pods-crash-or-restart-due-to-lack-of-memory-or-cpu
+: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::[]
+
+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]
+----
+requests:
+  cpu: 500m
+  memory: 128Mi
+----
+
+[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]
+
+include::modules/oadp-pod-crash-set-resource-request-velero.adoc[leveloffset=+1]
+include::modules/oadp-pod-crash-set-resource-request-restic.adoc[leveloffset=+1]