openshift · lpettyjo · Aug 5, 2026 · Jul 27, 2026
diff --git a/modules/lvms-troubleshooting-investigating-a-pvc-stuck-in-the-pending-state.adoc b/modules/lvms-troubleshooting-investigating-a-pvc-stuck-in-the-pending-state.adoc
@@ -6,21 +6,22 @@
 [id="investigating-a-pvc-stuck-in-the-pending-state_{context}"]
 = Investigating a PVC stuck in the Pending state
 
+[role="_abstract"]
+Investigate persistent volume claims (PVCs) stuck in a `Pending` state to determine whether the cause is insufficient resources, network problems, mismatched storage classes, or unavailable persistent volumes (PVs).
+
 A persistent volume claim (PVC) can get stuck in the `Pending` state for the following reasons:
 
-- Insufficient computing resources.
-- Network problems.
-- Mismatched storage class or node selector.
-- No available persistent volumes (PVs).
-- The node with the PV is in the `Not Ready` state.
+* Insufficient computing resources.
+* Network problems.
+* Mismatched storage class or node selector.
+* No available persistent volumes (PVs).
+* The node with the PV is in the `Not Ready` state.
 
 .Prerequisites
-
 * You have installed the {oc-first}.
 * You have logged in to the {oc-first} as a user with `cluster-admin` permissions.
 
 .Procedure
-
 . Retrieve the list of PVCs by running the following command:
 +
 [source,terminal]
@@ -39,9 +40,10 @@ lvms-test   Pending                                      lvms-vg1       11s
 +
 [source,terminal]
 ----
-$ oc describe pvc <pvc_name> <1>
+$ oc describe pvc <pvc_name>
 ----
-<1> Replace `<pvc_name>` with the name of the PVC. For example, `lvms-vg1`.
++
+Replace `<pvc_name>` with the name of the PVC. For example, `lvms-vg1`.
 +
 .Example output
 [source,terminal]

diff --git a/modules/lvms-troubleshooting-performing-a-forced-cleanup.adoc b/modules/lvms-troubleshooting-performing-a-forced-cleanup.adoc
@@ -6,29 +6,26 @@
 [id="performing-a-forced-cleanup_{context}"]
 = Performing a forced clean-up
 
-If the disk or node-related problems persist even after you have completed the troubleshooting procedures, you must perform a forced clean-up. A forced clean-up is used to address persistent issues and ensure the proper functioning of {lvms-first}.
+[role="_abstract"]
+Perform a forced clean-up by removing all {lvms-first} custom resources (CRs) when disk or node-related problems continue after standard troubleshooting, to restore proper storage functioning.
 
-.Prerequisites
+If the disk or node-related problems persist even after you have completed the troubleshooting procedures, you must perform a forced clean-up. A forced clean-up is used to address persistent issues and ensure the proper functioning of {lvms}.
 
+.Prerequisites
 * You have installed the {oc-first}.
-
 * You have logged in to the {oc-first} as a user with `cluster-admin` permissions.
-
 * You have deleted all the persistent volume claims (PVCs) that were created by using {lvms}.
-
 * You have stopped the pods that are using the PVCs that were created by using {lvms}.
 
-
 .Procedure
-
 . Switch to the namespace where you have installed the {lvms} Operator by running the following command:
 +
 [source,terminal]
 ----
 $ oc project <namespace>
 ----
 
-. Check if the `LogicalVolume` custom resources (CRs) are present by running the following command:
+. Check if the `LogicalVolume` custom resources are present by running the following command:
 +
 [source,terminal]
 ----
@@ -39,17 +36,19 @@ $ oc get logicalvolume
 +
 [source,terminal]
 ----
-$ oc delete logicalvolume <name> <1>
+$ oc delete logicalvolume <name>
 ----
-<1> Replace `<name>` with the name of the `LogicalVolume` CR.
++
+Replace `<name>` with the name of the `LogicalVolume` CR.
 
 .. After deleting the `LogicalVolume` CRs, remove their finalizers by running the following command:
 +
 [source,terminal]
 ----
-$ oc patch logicalvolume <name> -p '{"metadata":{"finalizers":[]}}' --type=merge <1>
+$ oc patch logicalvolume <name> -p '{"metadata":{"finalizers":[]}}' --type=merge
 ----
-<1> Replace `<name>` with the name of the `LogicalVolume` CR.
++
+Replace `<name>` with the name of the `LogicalVolume` CR.
 
 . Check if the `LVMVolumeGroup` CRs are present by running the following command:
 +
@@ -62,17 +61,19 @@ $ oc get lvmvolumegroup
 +
 [source,terminal]
 ----
-$ oc delete lvmvolumegroup <name> <1>
+$ oc delete lvmvolumegroup <name>
 ----
-<1> Replace `<name>` with the name of the `LVMVolumeGroup` CR.
++
+Replace `<name>` with the name of the `LVMVolumeGroup` CR.
 
 .. After deleting the `LVMVolumeGroup` CRs, remove their finalizers by running the following command:
 +
 [source,terminal]
 ----
-$ oc patch lvmvolumegroup <name> -p '{"metadata":{"finalizers":[]}}' --type=merge <1>
+$ oc patch lvmvolumegroup <name> -p '{"metadata":{"finalizers":[]}}' --type=merge
 ----
-<1> Replace `<name>` with the name of the `LVMVolumeGroup` CR. 
++
+Replace `<name>` with the name of the `LVMVolumeGroup` CR. 
 
 . Delete any `LVMVolumeGroupNodeStatus` CRs by running the following command:
 +
@@ -92,6 +93,7 @@ $ oc delete lvmcluster --all
 +
 [source,terminal]
 ----
-$ oc patch lvmcluster <name> -p '{"metadata":{"finalizers":[]}}' --type=merge <1>
+$ oc patch lvmcluster <name> -p '{"metadata":{"finalizers":[]}}' --type=merge
 ----
-<1> Replace `<name>` with the name of the `LVMCluster` CR. 
++
+Replace `<name>` with the name of the `LVMCluster` CR. 
diff --git a/modules/lvms-troubleshooting-persistent-storage.adoc b/modules/lvms-troubleshooting-persistent-storage.adoc
@@ -6,4 +6,5 @@
 [id="lvms-troubleshooting-persistent-storage_{context}"]
 = Troubleshooting persistent storage
 
-While configuring persistent storage using {lvms-first}, you can encounter several issues that require troubleshooting.
+[role="_abstract"]
+If persistent storage issues occur with {lvms-first}, such as persistent volume claims (PVCs) stuck in a pending state, missing components, or node and disk failures, you can diagnose and resolve the problem by reviewing logs and recovering affected resources.
diff --git a/modules/lvms-troubleshooting-recovering-from-disk-failure.adoc b/modules/lvms-troubleshooting-recovering-from-disk-failure.adoc
@@ -6,7 +6,8 @@
 [id="recovering-from-disk-failure_{context}"]
 = Recovering from disk failure
 
-If you see a failure message while inspecting the events associated with the persistent volume claim (PVC), there can be a problem with the underlying volume or disk. 
+[role="_abstract"]
+Diagnose and resolve disk and volume provisioning failures by inspecting persistent volume claim (PVC) events to identify specific error messages, then connecting to the affected host to fix the underlying disk issue.
 
 Disk and volume provisioning issues result with a generic error message such as `Failed to provision volume with storage class <storage_class_name>`. The generic error message is followed by a specific volume failure error message.
 
@@ -36,24 +37,22 @@ The following table describes the volume failure error messages:
 |===
 
 .Prerequisites
-
 * You have installed the {oc-first}.
 * You have logged in to the {oc-first} as a user with `cluster-admin` permissions.
 
 .Procedure
-
 . Inspect the events associated with a PVC by running the following command:
 +
 [source,terminal]
 ----
-$ oc describe pvc <pvc_name> <1>
+$ oc describe pvc <pvc_name>
 ----
-<1> Replace `<pvc_name>` with the name of the PVC.
++
+Replace `<pvc_name>` with the name of the PVC.
 
 . Establish a direct connection to the host where the problem is occurring.
 
 . Resolve the disk issue.
 
 .Next steps
-
-* If the volume failure messages persist or recur even after you have resolved the issue with the disk, you must perform a forced clean-up. For more information, see "Performing a forced clean-up".
+If the volume failure messages persist or recur even after you have resolved the issue with the disk, you must perform a forced clean-up. For more information, see "Performing a forced clean-up".
diff --git a/...s/lvms-troubleshooting-recovering-from-missing-lvms-or-operator-components.adoc b/...s/lvms-troubleshooting-recovering-from-missing-lvms-or-operator-components.adoc
@@ -6,15 +6,14 @@
 [id="recovering-from-missing-lvms-or-operator-components_{context}"]
 = Recovering from a missing storage class
 
-If you encounter the `storage class not found` error, check the `LVMCluster` custom resource (CR) and ensure that all the {lvms-first} pods are in the `Running` state. 
+[role="_abstract"]
+Resolve the "storage class not found" error by verifying that the LVMCluster custom resource (CR) exists and all {lvms-first} pods are running, then reviewing logs to identify configuration issues.
 
 .Prerequisites
-
 * You have installed the {oc-first}.
 * You have logged in to the {oc-first} as a user with `cluster-admin` permissions.
 
 .Procedure
-
 . Verify that the `LVMCluster` CR is present by running the following command:
 +
 [source,terminal]

diff --git a/modules/lvms-troubleshooting-recovering-from-node-failure.adoc b/modules/lvms-troubleshooting-recovering-from-node-failure.adoc
@@ -6,17 +6,14 @@
 [id="recovering-from-node-failure_{context}"]
 = Recovering from node failure
 
-A persistent volume claim (PVC) can be stuck in the `Pending` state due to a node failure in the cluster. 
-
-To identify the failed node, you can examine the restart count of the `topolvm-node` pod. An increased restart count indicates potential problems with the underlying node, which might require further investigation and troubleshooting.
+[role="_abstract"]
+Identify failed nodes causing persistent volume claims (PVCs) to remain in pending state by examining the restart count of the `topolvm-node` pod, which indicates potential underlying node problems requiring investigation.
 
 .Prerequisites
-
 * You have installed the {oc-first}.
 * You have logged in to the {oc-first} as a user with `cluster-admin` permissions.
 
 .Procedure
-
 * Examine the restart count of the `topolvm-node` pod instances by running the following command:
 +
 [source,terminal]
@@ -39,5 +36,4 @@ vg-manager-an118                      1/1     Running   0             66m
 ----
 
 .Next steps
-
-* If the PVC is stuck in the `Pending` state even after you have resolved any issues with the node, you must perform a forced clean-up. For more information, see "Performing a forced clean-up".
+If the PVC is stuck in the `Pending` state even after you have resolved any issues with the node, you must perform a forced clean-up. For more information, see "Performing a forced clean-up".