openshift · shdeshpa07 · Oct 15, 2025 · Aug 29, 2025
diff --git a/_attributes/common-attributes.adoc b/_attributes/common-attributes.adoc
@@ -41,14 +41,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.5
 :oadp-version-1-3: 1.3.6
 :oadp-version-1-4: 1.4.5
 :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
@@ -71,8 +79,6 @@ endif::[]
 :kueue-op: Red Hat Build of Kueue Operator
 :ms: Red{nbsp}Hat build of MicroShift (MicroShift)
 // 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

diff --git a/...nd_restore/application_backup_and_restore/installing/about-installing-oadp.adoc b/...nd_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[]
 
@@ -56,7 +59,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]

diff --git a/...pplication_backup_and_restore/troubleshooting/backup-and-restore-cr-issues.adoc b/...pplication_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

diff --git a/...ckup_and_restore/troubleshooting/issues-with-velero-and-admission-webhooks.adoc b/...ckup_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.

diff --git a/...re/application_backup_and_restore/troubleshooting/oadp-installation-issues.adoc b/...re/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

diff --git a/...and_restore/application_backup_and_restore/troubleshooting/oadp-monitoring.adoc b/...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

diff --git a/...estore/application_backup_and_restore/troubleshooting/oadp-operator-issues.adoc b/...estore/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}"]

diff --git a/...p_and_restore/application_backup_and_restore/troubleshooting/oadp-timeouts.adoc b/...p_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.

diff --git a/...restore/troubleshooting/pods-crash-or-restart-due-to-lack-of-memory-or-cpu.adoc b/...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]

diff --git a/...p_and_restore/application_backup_and_restore/troubleshooting/restic-issues.adoc b/...p_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

diff --git a/...and_restore/application_backup_and_restore/troubleshooting/troubleshooting.adoc b/...and_restore/application_backup_and_restore/troubleshooting/troubleshooting.adoc
@@ -1,6 +1,8 @@
 :_mod-docs-content-type: ASSEMBLY
 [id="troubleshooting"]
 = Troubleshooting
+:toc:
+
 include::_attributes/common-attributes.adoc[]
 include::_attributes/attributes-openshift-dedicated.adoc[]
 :context: oadp-troubleshooting
@@ -10,8 +12,8 @@ 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::[]
 
+[role="_abstract"]
 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.

diff --git a/.../application_backup_and_restore/troubleshooting/using-the-must-gather-tool.adoc b/.../application_backup_and_restore/troubleshooting/using-the-must-gather-tool.adoc
@@ -1,12 +1,14 @@
 :_mod-docs-content-type: ASSEMBLY
 [id="using-the-must-gather-tool"]
 = Using the must-gather tool
+:toc: 
+
 include::_attributes/common-attributes.adoc[]
 :context: using-the-must-gather-tool
 :must-gather-v1-4: registry.redhat.io/oadp/oadp-mustgather-rhel9:v1.4
 
-toc::[]
 
+[role="_abstract"]
 You can collect logs and information about {oadp-short} custom resources by using the `must-gather` tool. The `must-gather` data must be attached to all customer cases.
 
 The `must-gather` tool is a container and does not run all the time. The tool runs for a few minutes only after you invoke the tool by running the `must-gather` command.

diff --git a/...and_restore/application_backup_and_restore/troubleshooting/velero-cli-tool.adoc b/...and_restore/application_backup_and_restore/troubleshooting/velero-cli-tool.adoc
@@ -1,14 +1,17 @@
 :_mod-docs-content-type: ASSEMBLY
 [id="velero-cli-tool"]
 = Velero CLI tool
+:toc:
+
 include::_attributes/common-attributes.adoc[]
 include::_attributes/attributes-openshift-dedicated.adoc[]
 :context: velero-cli-tool
 :namespace: openshift-adp
 :local-product: OADP
 
-toc::[]
 
+
+[role="_abstract"]
 You can obtain the `velero` CLI tool by using the following options:
 
 * Downloading the `velero` CLI tool

diff --git a/modules/migration-debugging-velero-admission-webhooks-ibm-appconnect.adoc b/modules/migration-debugging-velero-admission-webhooks-ibm-appconnect.adoc
@@ -5,6 +5,7 @@
 [id="migration-debugging-velero-admission-webhooks-ibm-appconnect_{context}"]
 = Restoring {ibm-title} AppConnect resources
 
+[role="_abstract"]
 If you experience issues when you use Velero to a restore an {ibm-name} AppConnect resource that has an admission webhook, you can run the checks in this procedure.
 
 .Procedure

diff --git a/modules/migration-debugging-velero-admission-webhooks-knative.adoc b/modules/migration-debugging-velero-admission-webhooks-knative.adoc
@@ -5,7 +5,8 @@
 [id="migration-debugging-velero-admission-webhooks-knative_{context}"]
 = Restoring Knative resources
 
-You might encounter problems using Velero to back up Knative resources that use admission webhooks.
+[role="_abstract"]
+You might encounter problems by using Velero to back up Knative resources that use admission webhooks.
 
 You can avoid such problems by restoring the top level `Service` resource first whenever you back up and restore Knative resources that use admission webhooks.
 

diff --git a/modules/migration-debugging-velero-resources.adoc b/modules/migration-debugging-velero-resources.adoc
@@ -7,11 +7,12 @@
 [id="migration-debugging-velero-resources_{context}"]
 = Debugging Velero resources with the Velero CLI tool
 
-You can debug `Backup` and `Restore` custom resources (CRs) and retrieve logs with the Velero CLI tool.
+[role="_abstract"]
+You can debug `Backup` and `Restore` custom resources (CRs) and retrieve logs with the Velero CLI tool. The Velero CLI tool provides more detailed information than the OpenShift CLI tool.
 
 The Velero CLI tool provides more detailed information than the OpenShift CLI tool.
 
-[discrete]
+
 [id="velero-command-syntax_{context}"]
 == Syntax
 
@@ -30,7 +31,7 @@ $ oc -n {namespace} exec deployment/velero -c velero -- ./velero \
   backup describe 0e44ae00-5dc3-11eb-9ca8-df7e5254778b-2d8ql
 ----
 
-[discrete]
+
 [id="velero-help-option_{context}"]
 == Help option
 
@@ -43,7 +44,7 @@ $ oc -n {namespace} exec deployment/velero -c velero -- ./velero \
 ----
 
 
-[discrete]
+
 [id="velero-describe-command_{context}"]
 == Describe command
 
@@ -65,11 +66,16 @@ $ oc -n {namespace} exec deployment/velero -c velero -- ./velero \
 The following types of restore errors and warnings are shown in the output of a `velero describe` request:
 
 * `Velero`: A list of messages related to the operation of Velero itself, for example, messages related to connecting to the cloud, reading a backup file, and so on
-* `Cluster`: A list of messages related to backing up or restoring cluster-scoped resources
+
+* `Cluster`:  A list of messages related to backing up or restoring cluster-scoped resources
+
 * `Namespaces`: A list of list of messages related to backing up or restoring resources stored in namespaces
 
 One or more errors in one of these categories results in a `Restore` operation receiving the status of `PartiallyFailed` and not `Completed`. Warnings do not lead to a change in the completion status.
 
+
+Consider the following points for these restore errors:
+
 [IMPORTANT]
 ====
 * For resource-specific errors, that is, `Cluster` and `Namespaces` errors, the `restore describe --details` output includes a resource list that lists all resources that Velero succeeded in restoring. For any resource that has such an error, check to see if the resource is actually in the cluster.
@@ -79,7 +85,6 @@ One or more errors in one of these categories results in a `Restore` operation r
 For example, if the output contains `PodVolumeRestore` or node agent-related errors, check the status of `PodVolumeRestores` and `DataDownloads`. If none of these are failed or still running, then volume data might have been fully restored.
 ====
 
-[discrete]
 [id="velero-logs-command_{context}"]
 == Logs command
 

diff --git a/modules/oadp-creating-alerting-rule.adoc b/modules/oadp-creating-alerting-rule.adoc
@@ -6,7 +6,8 @@
 [id="creating-alerting-rules_{context}"]
 = Creating an alerting rule
 
-The {product-title} monitoring stack allows to receive Alerts configured using Alerting Rules. To create an Alerting rule for the OADP project, use one of the Metrics which are scraped with the user workload monitoring.
+[role="_abstract"]
+The {product-title} monitoring stack receives Alerts configured by using Alerting Rules. To create an Alerting rule for the {oadp-short} project, use one of the Metrics scraped with the user workload monitoring.
 
 .Procedure
 

diff --git a/modules/oadp-creating-service-monitor.adoc b/modules/oadp-creating-service-monitor.adoc
@@ -6,9 +6,9 @@
 [id="oadp-creating-service-monitor_{context}"]
 = Creating OADP service monitor
 
-OADP provides an `openshift-adp-velero-metrics-svc` service which is created when the DPA is configured. The service monitor used by the user workload monitoring must point to the defined service.
-
-Get details about the service by running the following commands:
+[role="_abstract"]
+{oadp-short} provides an `openshift-adp-velero-metrics-svc` service, which is created when the Data Protection Application (DPA) is configured. The user workload monitoring service monitor must point to the defined service.
+To get details about the service, complete the following steps.
 
 .Procedure
 

diff --git a/modules/oadp-csi-snapshot-timeouts.adoc b/modules/oadp-csi-snapshot-timeouts.adoc
@@ -6,6 +6,7 @@
 [id="csisnapshot-timeout_{context}"]
 = CSI snapshot timeout
 
+[role="_abstract"]
 `CSISnapshotTimeout` specifies the time during creation to wait until  the `CSI VolumeSnapshot` status becomes `ReadyToUse`, before returning error as timeout. The default value is `10m`.
 
 Use the `CSISnapshotTimeout`  for the following scenarios:

diff --git a/modules/oadp-datamover-timeouts.adoc b/modules/oadp-datamover-timeouts.adoc
@@ -6,6 +6,7 @@
 [id="datamover-timeout_{context}"]
 = Data Mover timeout
 
+[role="_abstract"]
 `timeout` is a user-supplied timeout to complete `VolumeSnapshotBackup` and `VolumeSnapshotRestore`. The default value is `10m`.
 
 Use the Data Mover `timeout` for the following scenarios:

diff --git a/modules/oadp-debugging-oc-cli.adoc b/modules/oadp-debugging-oc-cli.adoc
@@ -6,6 +6,7 @@
 [id="oadp-debugging-oc-cli_{context}"]
 = Debugging Velero resources with the OpenShift CLI tool
 
+[role="_abstract"]
 You can debug a failed backup or restore by checking Velero custom resources (CRs) and the `Velero` pod log with the OpenShift CLI tool.
 
 [discrete]