docs: update README and tidy up docs (#365)

* docs: update README and tidy up docs

Signed-off-by: Abhinandan Purkait <[email protected]>

* docs: refactor CONTRIBUITNG

Signed-off-by: Abhinandan Purkait <[email protected]>

---------

Signed-off-by: Abhinandan Purkait <[email protected]>

CHANGELOG.md

@@ -1,3 +1,12 @@
+lvm-localpv-1.6.2 / 2024-09-19
+========================
+<b>NOTE</b>: This was only a chart release that addressed a bug on prior chart. 
+* fix(chart): revert env OPENEBS_NAMESPACE to LVM_NAMESPACE for v1.6.x ([#333](https://github.com/openebs/lvm-localpv/pull/333),[@niladrih](https://github.com/niladrih))
+
+v1.6.1 / 2024-09-16
+========================
+* chore(deps): update analytics dependency ([#325](https://github.com/openebs/lvm-localpv/pull/325),[@niladrih](https://github.com/niladrih))
+
 v1.6.0 / 2024-07-03
 ========================
 * feat(analytics): add heartbeat pinger ([#318](https://github.com/openebs/lvm-localpv/pull/318),[@niladrih](https://github.com/niladrih))

CONTRIBUTING.md

@@ -1,13 +1,11 @@
 # Contributing Guidelines
 
-<BR>
-
 ## Umbrella Project
 
-OpenEBS is an "umbrella project". Every project, repository and file in the OpenEBS organization adopts and follows the policies found in the Community repo umbrella project files.
-<BR>
+OpenEBS is an `Umbrella Project` whose governance and policies are defined in the [community](https://github.com/openebs/community/) repository.
+These policies are applicable to every sub-project, repository and file existing within the [OpenEBS GitHub organization](https://github.com/openebs/).
 
-This project follows the [OpenEBS Contributor Guidelines](https://github.com/openebs/community/blob/HEAD/CONTRIBUTING.md)
+This project follows the [OpenEBS Contributor Guidelines](https://github.com/openebs/community/blob/HEAD/CONTRIBUTING.md).
 
 ## Contributing to LocalPV-LVM
 

RELEASE.md

@@ -0,0 +1,37 @@
+# Release Process
+
+Local PV LVM tries to follow semantic versioning principles as specified here https://semver.org. It follows a on quarterly release cadence for minor version releases. The scope of the release is determined by contributor availability. The scope is published in the [Release Tracker Projects](https://github.com/orgs/openebs/projects/78).
+
+## Pre-release Candidate Verification Checklist
+
+Every release has a pre-release version that gets created on branch creation, explained further below. This pre-release version is meant for all the below action items throughout the release process:
+
+- Platform Verification
+- Regression and Feature Verification Automated tests
+- Exploratory testing by QA engineers
+- Strict security scanners on the container images
+- Upgrade from previous releases
+- Beta testing by users on issues that they are interested in
+
+If any issues are found during the above stages, they are fixed and the prerelease version is overridden by the newer changes and are up for above action items again.
+
+Once all the above tests are completed, a main release is created.
+
+## Release Tagging
+
+Local PV LVM is released with container images and a respective helm chart as the only recommended way of installation. Even though the [lvm-operator](./deploy/lvm-operator.yaml) is also published, it is generated by templating the helm chart itself.
+
+Before creating a release, the repo owner needs to create a separate branch from the active branch, which is `develop`. Name of the branch should follow the naming convention of `release/2.7` if release is for `2.7.x`.
+
+Upon creation of a release branch ex. `release/2.7`, two automated PRs open up to change the chart versions of the charts in `release/2.7` branch to `2.7.0-prerelease` and `develop` to `2.8.0-develop`. Post merge of these two PRs, the `2.7.0-prerelease` and `2.8.0-develop` versions are pushed to respective docker registries and also the respective helm charts against these versions are published. The prerelease versions increment via automated PRs on every release creation. For example once `2.7.0` is published a `2.7.1-prerelease` image and chart would be published to allow testing of further patch releases and so on.
+
+The format of the release tag follows semver versioning. The final release tag is of format `X.Y.Z` and the respective prerelease and develop versions are `X.Y.Z-prerelease` and `X.Y+1.0-develop`.
+
+Once the release is triggered, the unchanged code undergoes stages as such linting, unit-tests and bdd-tests and the code coverage is updated accordingly. Post the former jobs, the image build is triggered with the specified tag, the images are published and the chart is run though scripts that update the image tags at the relevant places and eventually helm charts are published.
+
+The helm charts are hosted on github deployments for the corresponding releases.
+
+The tagged images are published at: <https://hub.docker.com/r/openebs/lvm-driver/tags>
+The release Helm charts are published at: <https://github.com/openebs/lvm-localpv/tree/gh-pages>
+
+It should be verified if all significant changes to the project have been itemized on to the CHANGELOG.md file, before a release is cut.

docs/faq.md

@@ -95,3 +95,7 @@ allowedTopologies:
 The LVM LocalPV CSI driver will schedule the PV to the nodes where label "openebs.io/rack" is set to "rack1".
 
 Note that if storageclass is using Immediate binding mode and storageclass allowedTopologies is not mentioned then all the nodes should be labeled using "ALLOWED_TOPOLOGIES" keys, that means, "ALLOWED_TOPOLOGIES" keys should be present on all nodes, nodes can have different values for those keys. If some nodes don't have those keys, then LVMPV's default scheduler can not effectively do the volume capacity based scheduling. Here, in this case the CSI provisioner will pick keys from any random node and then prepare the preferred topology list using the nodes which has those keys defined and LVMPV scheduler will schedule the PV among those nodes only.
+
+### 2. How to upgrade the driver to newer version
+
+Please refer to the documentation at <https://openebs.io/docs/user-guides/upgrade>.

docs/quickstart.md

@@ -0,0 +1,168 @@
+## Usage and Deployment
+
+## Prerequisites
+
+> Before installing the LocalPV-LVM driver please make sure your Kubernetes Cluster meets the following prerequisites:
+> 1. All the nodes must have LVM2 utils package installed
+> 2. All the nodes must have dm-snapshot Kernel Module loaded - (Device Mapper Snapshot)
+
+## Setup
+
+Find the disk which you want to use for the LocalPV-LVM.
+
+> **Note**: For testing you can use a loopback device:
+> ```bash
+> truncate -s 1024G /tmp/disk.img
+> sudo losetup -f /tmp/disk.img --show
+> ``
+
+> [!NOTE]
+> - LocalPV-LVM will not provision the VG for the user <BR>
+> - The required Physical Volumes(PV) and Volume Group(VG) names will need to be created and present beforehand.
+
+Create the Volume group on all the nodes, which will be used by the LVM2 Driver for provisioning the volumes
+
+```bash
+sudo pvcreate /dev/loop0
+sudo vgcreate lvmvg /dev/loop0       ## here lvmvg is the volume group name to be created
+```
+
+## Installation
+
+Install the latest release of OpenEBS LVM2 LocalPV-LVM driver by running the following command. Note: All nodes must be running the same version of LocalPV-LVM, LMV2, device-mapper & dm-snapshot.
+
+**NOTE:** Installation using operator YAMLs is not the supported way any longer.  
+We can install the latest release of OpenEBS LVM driver by running the following command:
+
+```bash
+helm repo add openebs https://openebs.github.io/openebs
+helm repo update
+helm install openebs --namespace openebs openebs/openebs --create-namespace
+```
+
+**NOTE:** If you are running a custom Kubelet location, or a Kubernetes distribution that uses a custom Kubelet location, the `kubelet` directory must be changed on the helm values at install-time using the flag option `--set lvm-localpv.lvmNode.kubeletDir=<your-directory-path>` in the `helm install` command.
+
+- For `microk8s`, we need to change the kubelet directory to `/var/snap/microk8s/common/var/lib/kubelet/`, we need to replace `/var/lib/kubelet/` with `/var/snap/microk8s/common/var/lib/kubelet/`.
+- For `k0s`, the default directory (`/var/lib/kubelet`) should be changed to `/var/lib/k0s/kubelet`.
+- For `RancherOS`, the default directory (`/var/lib/kubelet`) should be changed to `/opt/rke/var/lib/kubelet`.
+
+Verify that the LVM driver Components are installed and running using below command. Depending on number of nodes, you will see one lvm-controller pod and lvm-node daemonset running on the nodes :
+```bash
+$ kubectl get pods -n openebs -l role=openebs-lvm
+NAME                                              READY   STATUS    RESTARTS   AGE
+openebs-lvm-localpv-controller-7b6d6b4665-fk78q   5/5     Running   0          11m
+openebs-lvm-localpv-node-mcch4                    2/2     Running   0          11m
+openebs-lvm-localpv-node-pdt88                    2/2     Running   0          11m
+openebs-lvm-localpv-node-r9jn2                    2/2     Running   0          11m
+```
+
+Once LVM driver is installed and running we can provision a volume.
+
+### Deployment
+
+
+#### 1. Create a Storage class
+
+```
+$ cat sc.yaml
+
+apiVersion: storage.k8s.io/v1
+kind: StorageClass
+metadata:
+  name: openebs-lvmpv
+parameters:
+  storage: "lvm"
+  volgroup: "lvmvg"
+provisioner: local.csi.openebs.io
+```
+
+Check the doc on [storageclasses](docs/storageclasses.md) to know all the supported parameters for LocalPV-LVM
+
+##### VolumeGroup Availability
+
+If LVM volume group is available on certain nodes only, then make use of topology to tell the list of nodes where we have the volgroup available.
+As shown in the below storage class, we can use allowedTopologies to describe volume group availability on nodes.
+
+```
+apiVersion: storage.k8s.io/v1
+kind: StorageClass
+metadata:
+  name: openebs-lvmpv
+allowVolumeExpansion: true
+parameters:
+  storage: "lvm"
+  volgroup: "lvmvg"
+provisioner: local.csi.openebs.io
+allowedTopologies:
+- matchLabelExpressions:
+  - key: kubernetes.io/hostname
+    values:
+      - lvmpv-node1
+      - lvmpv-node2
+```
+
+The above storage class tells that volume group "lvmvg" is available on nodes lvmpv-node1 and lvmpv-node2 only. The LVM driver will create volumes on those nodes only.
+
+Please note that the provisioner name for LVM driver is "local.csi.openebs.io", we have to use this while creating the storage class so that the volume provisioning/deprovisioning request can come to LVM driver.
+
+#### 2. Create the PVC
+
+```
+$ cat pvc.yaml
+
+kind: PersistentVolumeClaim
+apiVersion: v1
+metadata:
+  name: csi-lvmpv
+spec:
+  storageClassName: openebs-lvmpv
+  accessModes:
+    - ReadWriteOnce
+  resources:
+    requests:
+      storage: 4Gi
+```
+
+Create a PVC using the storage class created for the LVM driver.
+
+#### 3. Deploy the application
+
+Create the deployment yaml using the pvc backed by LVM storage.
+
+```
+$ cat fio.yaml
+
+apiVersion: v1
+kind: Pod
+metadata:
+  name: fio
+spec:
+  restartPolicy: Never
+  containers:
+  - name: perfrunner
+    image: openebs/tests-fio
+    command: ["/bin/bash"]
+    args: ["-c", "while true ;do sleep 50; done"]
+    volumeMounts:
+       - mountPath: /datadir
+         name: fio-vol
+    tty: true
+  volumes:
+  - name: fio-vol
+    persistentVolumeClaim:
+      claimName: csi-lvmpv
+```
+
+After the deployment of the application, we can go to the node and see that the lvm volume is being used
+by the application for reading/writing the data and space is consumed from the LVM. Please note that to check the provisioned volumes on the node, we need to run `pvscan --cache` command to update the lvm cache and then we can use lvdisplay and all other lvm commands on the node.
+
+#### 4. Deprovisioning
+
+for deprovisioning the volume we can delete the application which is using the volume and then we can go ahead and delete the pv, as part of deletion of pv this volume will also be deleted from the volume group and data will be freed.
+
+```
+$ kubectl delete -f fio.yaml
+pod "fio" deleted
+$ kubectl delete -f pvc.yaml
+persistentvolumeclaim "csi-lvmpv" deleted
+```

docs/upgrade.md

@@ -0,0 +1 @@
+Please refer to the documentation at <https://openebs.io/docs/user-guides/upgrade>.