openshift · shdeshpa07 · Sep 4, 2025 · Aug 29, 2025
diff --git a/_attributes/common-attributes.adoc b/_attributes/common-attributes.adoc
@@ -42,6 +42,8 @@ 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.16
 :oadp-first: OpenShift API for Data Protection (OADP)
 :oadp-full: OpenShift API for Data Protection
 :oadp-short: OADP
@@ -50,7 +52,14 @@ endif::[]
 :oadp-version-1-4: 1.4.5
 :oadp-version-1-5: 1.5.0
 :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
@@ -70,8 +79,6 @@ endif::[]
 :descheduler-operator: Kube Descheduler Operator
 :cli-manager: CLI Manager Operator
 // Backup and restore
-:velero-domain: velero.io
-:velero-version: 1.16
 :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,14 +1,17 @@
 :_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::[]
 
+
+[role="_abstract"]
 You might encounter the following common issues with `Backup` and `Restore` custom resources (CRs):
 
 * Backup CR cannot retrieve volume

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,14 +1,17 @@
 :_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::[]
 
+
+[role="_abstract"]
 You might encounter issues caused by using invalid directories or incorrect credentials when you install the Data Protection Application (DPA).
 
 include::modules/resolving-backup-storage-contains-invalid-directories-issue.adoc[leveloffset=+1]

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.
 
 include::modules/resolving-oadp-operator-fails-silently-issue.adoc[leveloffset=+1]
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,8 +11,9 @@ 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"]
 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:

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,14 +1,17 @@
 :_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::[]
 
+
+[role="_abstract"]
 You might encounter the following issues when you back up applications with Restic:
 
 * Restic permission error for NFS data volumes with the `root_squash` resource/parameter enabled

diff --git a/...oting/restoring-workarounds-for-velero-backups-that-use-admission-webhooks.adoc b/...oting/restoring-workarounds-for-velero-backups-that-use-admission-webhooks.adoc
@@ -1,6 +1,8 @@
 :_mod-docs-content-type: ASSEMBLY
 [id="restoring-workarounds-for-velero-backups-that-use-admission-webhooks"]
 = Restoring workarounds for Velero backups that use admission webhooks
+:toc:
+
 include::_attributes/common-attributes.adoc[]
 include::_attributes/attributes-openshift-dedicated.adoc[]
 :context: restoring-workarounds-for-velero-backups-that-use-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/...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-5: registry.redhat.io/oadp/oadp-mustgather-rhel9:v1.5
 
-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/avoiding-the-velero-plugin-panic-error.adoc b/modules/avoiding-the-velero-plugin-panic-error.adoc
@@ -8,11 +8,12 @@
 [id="avoiding-the-velero-plugin-panic-error_{context}"]
 = Avoiding the Velero plugin panic error
 
+[role="_abstract"]
 A missing secret can cause a panic error for the Velero plugin during image stream backups.
 
 When the backup and the Backup Storage Location (BSL) are managed outside the scope of the Data Protection Application (DPA), the OADP controller does not create the relevant `oadp-<bsl_name>-<bsl_provider>-registry-secret` parameter.
 
-During the backup operation, the OpenShift Velero plugin panics on the imagestream backup, with the following panic error:
+During the backup operation, the OpenShift Velero plugin panics on the `imagestream` backup, with the following panic error:
 
 [source,text]
 ----

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
@@ -6,7 +6,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 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,6 +7,7 @@
 [id="migration-debugging-velero-resources_{context}"]
 = Debugging Velero resources 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.
 
 .Procedure
@@ -66,18 +67,17 @@ $ 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
+* `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
+* `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:
 
 * For resource-specific errors, that is, `Cluster` and `Namespaces` errors, the `restore describe --details` output includes a resource list that includes all resources that Velero restored. For any resource that has such an error, check if the resource is actually in the cluster.

diff --git a/modules/oadp-creating-alerting-rule.adoc b/modules/oadp-creating-alerting-rule.adoc
@@ -6,6 +6,7 @@
 [id="creating-alerting-rules_{context}"]
 = Creating an alerting rule
 
+[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,6 +6,7 @@
 [id="oadp-creating-service-monitor_{context}"]
 = Creating OADP service monitor
 
+[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.
 

diff --git a/modules/oadp-csi-snapshot-timeouts.adoc b/modules/oadp-csi-snapshot-timeouts.adoc
@@ -6,6 +6,7 @@
 [id="csisnapshot-timeout_{context}"]
 = Implementing 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}"]
 = Implementing 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.
 
 .Procedure

diff --git a/modules/oadp-item-backup-timeouts.adoc b/modules/oadp-item-backup-timeouts.adoc
@@ -6,6 +6,7 @@
 [id="item-operation-timeout-backup_{context}"]
 = Implementing item operation timeout - backup
 
+[role="_abstract"]
 The `ItemOperationTimeout` setting specifies the time used to wait for asynchronous
 `BackupItemAction` operations. The default value is `1h`.
 

diff --git a/modules/oadp-item-restore-timeouts.adoc b/modules/oadp-item-restore-timeouts.adoc
@@ -6,6 +6,7 @@
 [id="item-operation-timeout-restore_{context}"]
 = Implementing item operation timeout - restore
 
+[role="_abstract"]
 The `ItemOperationTimeout` setting specifies the time that is used to wait for `RestoreItemAction` operations. The default value is `1h`.
 
 Use the restore `ItemOperationTimeout` for the following scenarios:

diff --git a/modules/oadp-list-of-metrics.adoc b/modules/oadp-list-of-metrics.adoc
@@ -6,6 +6,7 @@
 [id="list-of-metrics_{context}"]
 = List of available metrics
 
+[role="_abstract"]
 Refer to the following table for a list of `Velero` metrics provided by {oadp-short} together with their https://prometheus.io/docs/concepts/metric_types/[Types]:
 
 .Velero metrics