docs(localpv): update localPV docs (#905)

* add troubleshooting docs for local pv * fix localpv device docs * update node label key for local pv hostpath Signed-off-by: Akhil Mohan <[email protected]>
openebs-archive · Dec 17, 2020 · 30f8664 · 30f8664
1 parent 64540cb
commit 30f8664
Show file tree

Hide file tree

Showing 4 changed files with 110 additions and 1 deletion.
diff --git a/docs/t-localpv.md b/docs/t-localpv.md
@@ -0,0 +1,96 @@
+---
+id: t-localpv
+title: Troubleshooting OpenEBS - Dynamic LocalPV
+sidebar_label: LocalPV
+---
+------
+
+<font size="5">General guidelines for troubleshooting</font>
+
+- Contact <a href="/docs/next/support.html" target="_blank">OpenEBS Community</a> for support.
+- Search for similar issues added in this troubleshootiung section.
+- Search for any reported issues on <a href=" https://stackoverflow.com/questions/tagged/openebs" target="_blank">StackOverflow under OpenEBS tag</a>
+
+<br>
+<hr>
+<br>
+
+[LocalPV PVC in Pending state](#pvc-in-pending-state)
+
+[Application pod using LocalPV device not coming into running state](#application-pod-stuck-pending-pvc)
+
+[Stale BDC in pending state after PVC is deleted](#stale-bdc-after-pvc-deletion)
+
+
+<h3><a class="anchor" aria-hidden="true" id="pvc-in-pending-state"></a>PVC in Pending state</h3>
+Created a PVC using localpv-device / localpv-hostpath storage class. But the PV is not created and PVC in Pending state.
+
+**Troubleshooting:**
+The default localpv storage classes from openebs have `volumeBindingMode: WaitForFirstConsumer`. This means that only when the application pod that uses the PVC is scheduled to a node, the provisioner will receive the volume provision request and will create the volume.
+
+**Resolution:**
+Deploy an application that uses the PVC and the PV will be created and application will start using the PV
+
+<br>
+
+<h3><a class="anchor" aria-hidden="true" id="application-pod-stuck-pending-pvc"></a>Application pod using LocalPV not coming into running state</h3>
+Application pod that uses localpv device is stuck in `Pending` state with error 
+
+```
+Warning  FailedScheduling  7m24s (x2 over 7m24s)  default-scheduler  persistentvolumeclaim "<pvc-name>" not found
+```
+
+
+**Troubleshooting:**
+Check if there is a blockdevice present on the node (to which the application pod was scheduled,) which mathces the capacity requirements of the PVC.
+
+```
+kubectl get bd -n openebs -o wide
+```
+
+If matching blockdevices are not present, then the PVC will never get Bound.
+
+**Resolution:**
+Schedule the application pod to a node which has a matching blockdevice available on it.
+
+<br>
+
+<h3><a class="anchor" aria-hidden="true" id="stale-bdc-after-pvc-deletion"></a>Stale BDC in pending state after PVC is deleted</h3>
+```
+kubectl get bdc -n openebs
+```
+shows stale `Pending` BDCs created by localpv provisioner, even after the corresponding PVC has been deleted.
+
+**Resolution:**
+LocalPV provisioner currently does not delete BDCs in Pending state if the corresponding PVCs are deleted. To remove the stale BDC entries,
+
+1. Edit the BDC and remove the `- local.openebs.io/finalizer` finalizer
+```
+kubectl edit bdc <bdc-name> -n openebs
+```
+
+2. Delete the BDC
+```
+kubectl delete bdc <bdc-name> -n openebs
+```
+
+
+
+<br>
+
+<hr>
+<br>
+<br>
+
+## See Also:
+
+### [FAQs](/docs/next/faq.html)
+
+### [Seek support or help](/docs/next/support.html)
+
+### [Latest release notes](/docs/next/releases.html)
+
+<br>
+<hr>
+<br>
+
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
@@ -13,6 +13,7 @@ sidebar_label: Overview
 	-	<a href="/docs/next/t-ndm.html" target="_blank">Troubleshooting NDM</a>.
 	-	<a href="/docs/next/t-jiva.html" target="_blank">Troubleshooting Jiva</a>.
 	-	<a href="/docs/next/t-cstor.html" target="_blank">Troubleshooting cStor</a>.
+	-	<a href="/docs/next/t-localpv.html" target="_blank">Troubleshooting LocalPV</a>.
 -	Contact <a href="/docs/next/support.html" target="_blank">OpenEBS Community</a> for support.
 -	Search for similar issues on <a href="https://github.com/openebs/openebs/issues" target="_blank">OpenEBS GitHub repository</a>.
 -	Search for any reported issues on <a href="https://stackoverflow.com/questions/tagged/openebs" target="_blank">StackOverflow under OpenEBS tag</a>.
@@ -221,6 +222,8 @@ Set the reboot timer schedule at different time i.e staggered at various interva
 
 ### [Troubleshooting cStor](/docs/next/t-cstor.html)
 
+### [Troubleshooting cStor](/docs/next/t-localpv.html)
+
 ### [FAQs](/docs/next/faq.html)
 
 ### [Seek support or help](/docs/next/support.html)

diff --git a/docs/uglocalpv-device.md b/docs/uglocalpv-device.md
@@ -17,7 +17,7 @@ This guide will help you to set up and use OpenEBS Local Persistent Volumes back
 
 *OpenEBS Local PV Device* volumes have the following advantages compared to native Kubernetes Local Peristent Volumes. 
 - Dynamic Volume provisioner as opposed to a Static Provisioner. 
-- Better management of the Block Devices used for creating Local PVs by OpenEBS NDM. NDM provides capabilities like discovering Block Device properties, setting up Device Pools/Filters, metrics collection and ability to detect if the Block Devices have moved across nodes. 
+- Better management of the Block Devices used for creating Local PVs by OpenEBS NDM. NDM provides capabilities like discovering Block Device properties, setting up Device Filters, metrics collection and ability to detect if the Block Devices have moved across nodes. 
 
 OpenEBS Local PV uses volume topology aware pod scheduling enhancements introduced by [Kubernetes Local Volumes](https://kubernetes.io/docs/concepts/storage/volumes/#local)
 

diff --git a/docs/uglocalpv-hostpath.md b/docs/uglocalpv-hostpath.md
@@ -124,6 +124,14 @@ You can skip this section if you have already installed OpenEBS.
      helm install --namespace openebs --name openebs openebs/openebs
      ```
 
+### (Optional) Custom Node Labelling
+
+You can use custom node affinity labels instead of hostname in the hostpath provisioner. This
+helps in cases where the hostname changes when the node is removed and added back with the disks
+still intact. 
+For eg: If the custom node label is `openebs.io/custom-node-unique-id`, it can be added to the storage class config.
+
+
 ## Create StorageClass
 
 You can skip this section if you would like to use default OpenEBS Local PV Hostpath StorageClass created by OpenEBS. 
@@ -144,6 +152,8 @@ The default Storage Class is called `openebs-hostpath` and its `BasePath` is con
            value: hostpath
          - name: BasePath
            value: /var/local-hostpath
+         - name: NodeAffinityLabel
+           value: "openebs.io/custom-node-unique-id"
    provisioner: openebs.io/local
    reclaimPolicy: Delete
    volumeBindingMode: WaitForFirstConsumer