From d8b396a62fe701351b8e9f89793d8aa9aa8976d4 Mon Sep 17 00:00:00 2001 From: Lisa Pettyjohn Date: Mon, 27 Jul 2026 10:39:37 -0400 Subject: [PATCH] OSDOCS-16950#CQA work Stor6 - LVMS troubleshooting --- ...ting-a-pvc-stuck-in-the-pending-state.adoc | 20 +++++----- ...eshooting-performing-a-forced-cleanup.adoc | 38 ++++++++++--------- ...ms-troubleshooting-persistent-storage.adoc | 3 +- ...shooting-recovering-from-disk-failure.adoc | 13 +++---- ...m-missing-lvms-or-operator-components.adoc | 5 +-- ...shooting-recovering-from-node-failure.adoc | 10 ++--- 6 files changed, 44 insertions(+), 45 deletions(-) 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 index f89f7c304f7..6a0c84571f7 100644 --- 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 <1> +$ oc describe pvc ---- -<1> Replace `` with the name of the PVC. For example, `lvms-vg1`. ++ +Replace `` 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 index f20723c3d2a..223096ea748 100644 --- a/modules/lvms-troubleshooting-performing-a-forced-cleanup.adoc +++ b/modules/lvms-troubleshooting-performing-a-forced-cleanup.adoc @@ -6,21 +6,18 @@ [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] @@ -28,7 +25,7 @@ If the disk or node-related problems persist even after you have completed the t $ oc project ---- -. 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 <1> +$ oc delete logicalvolume ---- -<1> Replace `` with the name of the `LogicalVolume` CR. ++ +Replace `` 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 -p '{"metadata":{"finalizers":[]}}' --type=merge <1> +$ oc patch logicalvolume -p '{"metadata":{"finalizers":[]}}' --type=merge ---- -<1> Replace `` with the name of the `LogicalVolume` CR. ++ +Replace `` 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 <1> +$ oc delete lvmvolumegroup ---- -<1> Replace `` with the name of the `LVMVolumeGroup` CR. ++ +Replace `` 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 -p '{"metadata":{"finalizers":[]}}' --type=merge <1> +$ oc patch lvmvolumegroup -p '{"metadata":{"finalizers":[]}}' --type=merge ---- -<1> Replace `` with the name of the `LVMVolumeGroup` CR. ++ +Replace `` 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 -p '{"metadata":{"finalizers":[]}}' --type=merge <1> +$ oc patch lvmcluster -p '{"metadata":{"finalizers":[]}}' --type=merge ---- -<1> Replace `` with the name of the `LVMCluster` CR. ++ +Replace `` with the name of the `LVMCluster` CR. diff --git a/modules/lvms-troubleshooting-persistent-storage.adoc b/modules/lvms-troubleshooting-persistent-storage.adoc index 3dffe9fa4f1..1decba0744f 100644 --- 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. \ No newline at end of file +[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. \ No newline at end of file diff --git a/modules/lvms-troubleshooting-recovering-from-disk-failure.adoc b/modules/lvms-troubleshooting-recovering-from-disk-failure.adoc index 633fe15cd9a..8dba0f30c51 100644 --- 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 `. 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 <1> +$ oc describe pvc ---- -<1> Replace `` with the name of the PVC. ++ +Replace `` 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". \ No newline at end of file +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". \ No newline at end of file diff --git a/modules/lvms-troubleshooting-recovering-from-missing-lvms-or-operator-components.adoc b/modules/lvms-troubleshooting-recovering-from-missing-lvms-or-operator-components.adoc index 3218489aa1e..944b3cbdaf9 100644 --- a/modules/lvms-troubleshooting-recovering-from-missing-lvms-or-operator-components.adoc +++ b/modules/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 index f51e152ae99..147177c5743 100644 --- 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". \ No newline at end of file +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". \ No newline at end of file