TELCODOCS#1876: Moved troubleshooting assembly modules to the main LVMS assembly

sr1kar99 · sr1kar99 · commit 9ec6d4fb3d2b · 2024-06-03T23:35:31.000+05:30
diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml
@@ -1662,8 +1662,6 @@ Topics:
       File: persistent-storage-hostpath
     - Name: Persistent storage using LVM Storage
       File: persistent-storage-using-lvms
-    - Name: Troubleshooting local persistent storage using LVMS
-      File: troubleshooting-local-persistent-storage-using-lvms
 - Name: Using Container Storage Interface (CSI)
   Dir: container_storage_interface
   Distros: openshift-enterprise,openshift-origin
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
@@ -1,20 +1,23 @@
-// This module is included in the following assemblies:
+// Module included in the following assemblies:
 //
-// storage/persistent_storage/persistent_storage_local/troubleshooting-local-persistent-storage-using-lvms.adoc
+// storage/persistent_storage/persistent_storage_local/persistent-storage-using-lvms.adoc
 
 :_mod-docs-content-type: PROCEDURE
 [id="investigating-a-pvc-stuck-in-the-pending-state_{context}"]
 = Investigating a PVC stuck in the Pending state
 
-A persistent volume claim (PVC) can get stuck in a `Pending` state for a number of reasons. For example:
+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 volumes
-- The node with the persistent volume (PV) is in a `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.
 
-Identify the cause by using the `oc describe` command to review details about the stuck PVC.
+.Prerequisites
+
+* You have installed the {oc-first}.
+* You have logged in to the {oc-first} as a user with `cluster-admin` permissions.
 
 .Procedure
 
diff --git a/modules/lvms-troubleshooting-performing-a-forced-cleanup.adoc b/modules/lvms-troubleshooting-performing-a-forced-cleanup.adoc
@@ -1,18 +1,22 @@
-// This module is included in the following assemblies:
+// Module included in the following assemblies:
 //
-// storage/persistent_storage/persistent_storage_local/troubleshooting-local-persistent-storage-using-lvms.adoc
+// storage/persistent_storage/persistent_storage_local/persistent-storage-using-lvms.adoc
 
 :_mod-docs-content-type: PROCEDURE
 [id="performing-a-forced-cleanup_{context}"]
-= Performing a forced cleanup
+= Performing a forced clean-up
 
-If disk- or node-related problems persist after you complete the troubleshooting procedures, it might be necessary to perform a forced cleanup procedure. A forced cleanup is used to comprehensively address persistent issues and ensure the proper functioning of the LVMS.
+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}.
 
 .Prerequisites
 
-. All of the persistent volume claims (PVCs) created using the logical volume manager storage (LVMS) driver have been removed.
+* You have installed the {oc-first}.
 
-. The pods using those PVCs have been stopped.
+* 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
@@ -24,74 +28,70 @@ If disk- or node-related problems persist after you complete the troubleshooting
 $ oc project openshift-storage
 ----
 
-. Ensure there is no `Logical Volume` custom resource (CR) remaining by running the following command:
+. Check if the `LogicalVolume` custom resources (CRs) are present by running the following command:
 +
 [source,terminal]
 ----
 $ oc get logicalvolume
 ----
-+
-.Example output
-[source,terminal]
-----
-No resources found
-----
 
-.. If there are any `LogicalVolume` CRs remaining, remove their finalizers by running the following command:
+.. If the `LogicalVolume` CRs are present, delete them by running the following command:
 +
 [source,terminal]
 ----
-$ oc patch logicalvolume <name> -p '{"metadata":{"finalizers":[]}}' --type=merge <1>
+$ oc delete logicalvolume <name> <1>
 ----
-<1> Replace `<name>` with the name of the CR.
+<1> Replace `<name>` with the name of the `LogicalVolume` CR.
 
-.. After removing their finalizers, delete the CRs by running the following command:
+.. After deleting the `LogicalVolume` CRs, remove their finalizers by running the following command:
 +
 [source,terminal]
 ----
-$ oc delete logicalvolume <name> <1>
+$ oc patch logicalvolume <name> -p '{"metadata":{"finalizers":[]}}' --type=merge <1>
 ----
-<1> Replace `<name>` with the name of the CR.
+<1> Replace `<name>` with the name of the `LogicalVolume` CR.
 
-. Make sure there are no `LVMVolumeGroup` CRs left by running the following command:
+. Check if the `LVMVolumeGroup` CRs are present by running the following command:
 +
 [source,terminal]
 ----
 $ oc get lvmvolumegroup
 ----
+
+.. If the `LVMVolumeGroup` CRs are present, delete them by running the following command:
 +
-.Example output
 [source,terminal]
 ----
-No resources found
+$ oc delete lvmvolumegroup <name> <1>
 ----
+<1> Replace `<name>` with the name of the `LVMVolumeGroup` CR.
 
-.. If there are any `LVMVolumeGroup` CRs left, remove their finalizers by running the following command:
+.. 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>
 ----
-<1> Replace `<name>` with the name of the CR.
+<1> Replace `<name>` with the name of the `LVMVolumeGroup` CR. 
 
-.. After removing their finalizers, delete the CRs by running the following command:
+. Delete any `LVMVolumeGroupNodeStatus` CRs by running the following command:
 +
 [source,terminal]
 ----
-$ oc delete lvmvolumegroup <name> <1>
+$ oc delete lvmvolumegroupnodestatus --all
 ----
-<1> Replace `<name>` with the name of the CR.
 
-. Remove any `LVMVolumeGroupNodeStatus` CRs by running the following command:
+. Delete the `LVMCluster` CR by running the following command:
 +
 [source,terminal]
 ----
-$ oc delete lvmvolumegroupnodestatus --all
+$ oc delete lvmcluster --all
 ----
 
-. Remove the `LVMCluster` CR by running the following command:
+.. After deleting the `LVMCluster` CR, remove its finalizer by running the following command:
 +
 [source,terminal]
 ----
-$ oc delete lvmcluster --all
+$ oc patch lvmcluster <name> -p '{"metadata":{"finalizers":[]}}' --type=merge <1>
 ----
+<1> 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
@@ -0,0 +1,9 @@
+// Module included in the following assemblies:
+//
+// storage/persistent_storage/persistent_storage_local/persistent-storage-using-lvms.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="lvms-troubleshooting-persistent-storage_{context}"]
+= Troubleshooting persistent storage
+
+While configuring persistent storage using {lvms-first}, you can encounter several issues that require troubleshooting.
diff --git a/modules/lvms-troubleshooting-recovering-from-disk-failure.adoc b/modules/lvms-troubleshooting-recovering-from-disk-failure.adoc
@@ -1,12 +1,44 @@
-// This module is included in the following assemblies:
+// Module included in the following assemblies:
 //
-// storage/persistent_storage/persistent_storage_local/troubleshooting-local-persistent-storage-using-lvms.adoc
+// storage/persistent_storage/persistent_storage_local/persistent-storage-using-lvms.adoc
 
 :_mod-docs-content-type: PROCEDURE
 [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 might be a problem with the underlying volume or disk. Disk and volume provisioning issues often result with a generic error first, such as `Failed to provision volume with StorageClass <storage_class_name>`. A second, more specific error message usually follows.
+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. 
+
+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.
+
+The following table describes the volume failure error messages:
+
+.Volume failure error messages
+[%autowidth, options="header"]
+|===
+
+|Error message |Description
+
+|`Failed to check volume existence` 
+|Indicates a problem in verifying whether the volume already exists. Volume verification failure can be caused by network connectivity problems or other failures.
+
+|`Failed to bind volume` 
+|Failure to bind a volume can happen if the persistent volume (PV) that is available does not match the requirements of the PVC.
+
+|`FailedMount` or `FailedAttachVolume`
+|This error indicates problems when trying to mount the volume to a node. If the disk has failed, this error can appear when a pod tries to use the PVC.
+
+|`FailedUnMount`
+|This error indicates problems when trying to unmount a volume from a node. If the disk has failed, this error can appear when a pod tries to use the PVC.
+
+|`Volume is already exclusively attached to one node and cannot be attached to another` 
+|This error can appear with storage solutions that do not support `ReadWriteMany` access modes.
+
+|===
+
+.Prerequisites
+
+* You have installed the {oc-first}.
+* You have logged in to the {oc-first} as a user with `cluster-admin` permissions.
 
 .Procedure
 
@@ -16,18 +48,12 @@ If you see a failure message while inspecting the events associated with the per
 ----
 $ oc describe pvc <pvc_name> <1>
 ----
-<1> Replace `<pvc_name>` with the name of the PVC. Here are some examples of disk or volume failure error messages and their causes:
-+
-- *Failed to check volume existence:* Indicates a problem in verifying whether the volume already exists. Volume verification failure can be caused by network connectivity problems or other failures.
-+
-- *Failed to bind volume:* Failure to bind a volume can happen if the persistent volume (PV) that is available does not match the requirements of the PVC.
-+
-- *FailedMount or FailedUnMount:* This error indicates problems when trying to mount the volume to a node or unmount a volume from a node. If the disk has failed, this error might appear when a pod tries to use the PVC.
-+
-- *Volume is already exclusively attached to one node and cannot be attached to another:* This error can appear with storage solutions that do not support `ReadWriteMany` access modes.
+<1> 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.
 
-After you have resolved the issue with the disk, you might need to perform the forced cleanup procedure if failure messages persist or reoccur.
+.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".
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
@@ -1,16 +1,21 @@
-// This module is included in the following assemblies:
+// Module included in the following assemblies:
 //
-// storage/persistent_storage/persistent_storage_local/troubleshooting-local-persistent-storage-using-lvms.adoc
+// storage/persistent_storage/persistent_storage_local/persistent-storage-using-lvms.adoc
 
 :_mod-docs-content-type: PROCEDURE
 [id="recovering-from-missing-lvms-or-operator-components_{context}"]
-= Recovering from missing LVMS or Operator components
+= Recovering from a missing storage class
 
-If you encounter a storage class "not found" error, check the `LVMCluster` resource and ensure that all the logical volume manager storage (LVMS) pods are running. You can create an `LVMCluster` resource if it does not exist.
+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. 
+
+.Prerequisites
+
+* You have installed the {oc-first}.
+* You have logged in to the {oc-first} as a user with `cluster-admin` permissions.
 
 .Procedure
 
-. Verify the presence of the LVMCluster resource by running the following command:
+. Verify that the `LVMCluster` CR is present by running the following command:
 +
 [source,terminal]
 ----
@@ -24,33 +29,9 @@ NAME            AGE
 my-lvmcluster   65m
 ----
 
-. If the cluster does not have an `LVMCluster` resource, create one by running the following command:
-+
-[source,terminal]
-----
-$ oc create -n openshift-storage -f <custom_resource> <1>
-----
-<1> Replace `<custom_resource>` with a custom resource URL or file tailored to your requirements.
-+
-.Example custom resource
-[source,yaml,options="nowrap",role="white-space-pre"]
-----
-apiVersion: lvm.topolvm.io/v1alpha1
-kind: LVMCluster
-metadata:
-  name: my-lvmcluster
-spec:
-  storage:
-    deviceClasses:
-    - name: vg1
-      default: true
-      thinPoolConfig:
-        name: thin-pool-1
-        sizePercent: 90
-        overprovisionRatio: 10
-----
+. If the `LVMCluster` CR is not present, create an `LVMCluster` CR. For more information, see "Ways to create an LVMCluster custom resource".
 
-. Check that all the pods from LVMS are in the `Running` state in the `openshift-storage` namespace by running the following command:
+. In the `openshift-storage` namespace, check that all the {lvms} pods are in the `Running` state by running the following command:
 +
 [source,terminal]
 ----
@@ -67,9 +48,14 @@ topolvm-node-dr26h                    4/4     Running   0             66m
 vg-manager-r6zdv                      1/1     Running   0             66m
 ----
 +
-The expected output is one running instance of `lvms-operator` and `vg-manager`. One instance of `topolvm-controller` and `topolvm-node` is expected for each node.
+The output of this command must contain a running instance of the following pods:
+
+* `lvms-operator`
+* `vg-manager`
+* `topolvm-controller`
+* `topolvm-node`
 +
-If `topolvm-node` is stuck in the `Init` state, there is a failure to locate an available disk for LVMS to use. To retrieve the information necessary to troubleshoot, review the logs of the `vg-manager` pod by running the following command:
+If the `topolvm-node` pod is stuck in the `Init` state, it is due to a failure to locate an available disk for {lvms} to use. To retrieve the necessary information to troubleshoot this issue, review the logs of the `vg-manager` pod 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
@@ -1,12 +1,19 @@
-// This module is included in the following assemblies:
+// Module included in the following assemblies:
 //
-// storage/persistent_storage/persistent_storage_local/troubleshooting-local-persistent-storage-using-lvms.adoc
+// storage/persistent_storage/persistent_storage_local/persistent-storage-using-lvms.adoc
 
 :_mod-docs-content-type: PROCEDURE
 [id="recovering-from-node-failure_{context}"]
 = Recovering from node failure
 
-Sometimes a persistent volume claim (PVC) is stuck in a `Pending` state because a particular node in the cluster has failed. 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 may require further investigation and troubleshooting.
+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.
+
+.Prerequisites
+
+* You have installed the {oc-first}.
+* You have logged in to the {oc-first} as a user with `cluster-admin` permissions.
 
 .Procedure
 
@@ -30,5 +37,7 @@ vg-manager-r6zdv                      1/1     Running   0             66m
 vg-manager-990ut                      1/1     Running   0             66m
 vg-manager-an118                      1/1     Running   0             66m
 ----
-+
-After you resolve any issues with the node, you might need to perform the forced cleanup procedure if the PVC is still stuck in a `Pending` state.
+
+.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".
diff --git a/storage/persistent_storage/persistent_storage_local/persistent-storage-using-lvms.adoc b/storage/persistent_storage/persistent_storage_local/persistent-storage-using-lvms.adoc
diff --git a/storage/persistent_storage/persistent_storage_local/troubleshooting-local-persistent-storage-using-lvms.adoc b/storage/persistent_storage/persistent_storage_local/troubleshooting-local-persistent-storage-using-lvms.adoc
