{"id":18990758,"url":"https://github.com/openebs-archive/device-localpv","last_synced_at":"2025-04-22T11:27:52.275Z","repository":{"id":40391343,"uuid":"346367152","full_name":"openebs-archive/device-localpv","owner":"openebs-archive","description":"CSI Driver for using Local Block Devices ","archived":false,"fork":false,"pushed_at":"2023-07-24T13:56:11.000Z","size":8346,"stargazers_count":25,"open_issues_count":7,"forks_count":17,"subscribers_count":12,"default_branch":"develop","last_synced_at":"2025-04-17T00:15:58.099Z","etag":null,"topics":["csi-driver","hacktoberfest","kubernetes","openebs","storage"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/openebs-archive.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":"GOVERNANCE.md","roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-03-10T13:34:04.000Z","updated_at":"2025-04-07T13:40:29.000Z","dependencies_parsed_at":"2024-06-19T01:36:04.945Z","dependency_job_id":"ba18325f-00d2-4f05-ae91-028918dca43d","html_url":"https://github.com/openebs-archive/device-localpv","commit_stats":null,"previous_names":["openebs/device-localpv"],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openebs-archive%2Fdevice-localpv","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openebs-archive%2Fdevice-localpv/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openebs-archive%2Fdevice-localpv/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openebs-archive%2Fdevice-localpv/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openebs-archive","download_url":"https://codeload.github.com/openebs-archive/device-localpv/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250231003,"owners_count":21396400,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["csi-driver","hacktoberfest","kubernetes","openebs","storage"],"created_at":"2024-11-08T17:11:14.624Z","updated_at":"2025-04-22T11:27:52.255Z","avatar_url":"https://github.com/openebs-archive.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenEBS Local Device CSI Driver\n[![Build Status](https://github.com/openebs/device-localpv/actions/workflows/build.yml/badge.svg)](https://github.com/openebs/device-localpv/actions/workflows/build.yml)\n[![Slack](https://img.shields.io/badge/chat!!!-slack-ff1493.svg?style=flat-square)](https://kubernetes.slack.com/messages/openebs)\n[![Community Meetings](https://img.shields.io/badge/Community-Meetings-blue)](https://hackmd.io/yJb407JWRyiwLU-XDndOLA?view)\n[![Go Report](https://goreportcard.com/badge/github.com/openebs/device-localpv)](https://goreportcard.com/report/github.com/openebs/device-localpv)\n[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/4871/badge)](https://bestpractices.coreinfrastructure.org/projects/4871)\n[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fopenebs%2Fdevice-localpv.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Fopenebs%2Fdevice-localpv?ref=badge_shield)\n\n\u003cimg width=\"300\" align=\"right\" alt=\"OpenEBS Logo\" src=\"https://raw.githubusercontent.com/cncf/artwork/master/projects/openebs/stacked/color/openebs-stacked-color.png\" xmlns=\"http://www.w3.org/1999/html\"\u003e\n\nCSI Driver for using Local Block Devices \n\n## Project Status\n\nCurrently, the Device-LocalPV CSI Driver is in alpha. The users/organizations using OpenEBS can be found [here](https://github.com/openebs/openebs/tree/master/adopters)\n\n## Usage\n\n### Prerequisites\n\nBefore installing the device CSI driver please make sure your Kubernetes Cluster\nmust meet the following prerequisites:\n\n1. Disks are available on the node with a single 10MB partition having partition name used to \n   identify the disk\n2. You have access to install RBAC components into kube-system namespace.\n   The OpenEBS Device driver components are installed in kube-system namespace\n   to allow them to be flagged as system critical components.\n\n### Supported System\n\nK8S : 1.20+\n\nOS : Ubuntu\n\n### Setup\n\nFind the disk which you want to use for the Device LocalPV, for testing a loopback device can be used\n\n```\ntruncate -s 1024G /tmp/disk.img\nsudo losetup -f /tmp/disk.img --show\n```\n\n###### MetaPartition\nA meta partition is a small (~10MiB) partition that needs to be created on the disk, so as store the disk identification\ninformation. In device localpv, the partition name of the meta partition is used to identify the disk. A partition\nshould follow the below criteria, so that openebs identifies it as a meta partition and use it for disk identification\n1. The partition number should be 1 (`ID_PART_ENTRY_NUMBER=1`)\n2. The partition should not be formatted with any filesystem\n3. The partition should not have any flags set on it\n\nCreate the meta partition on the loop device which will be used for provisioning volumes\n\n```\nsudo parted /dev/loop9 mklabel gpt\nsudo parted /dev/loop9 mkpart test-device 1MiB 10MiB\n```\n\n### Installation\n\nDeploy the Operator yaml\n\n```\nkubectl apply -f https://raw.githubusercontent.com/openebs/device-localpv/develop/deploy/device-operator.yaml\n```\n\n### Deployment\n\n\n#### 1. Create a Storage class\n\n```\n$ cat sc.yaml\n\napiVersion: storage.k8s.io/v1\nkind: StorageClass\nmetadata:\n  name: openebs-device-sc\nallowVolumeExpansion: true\nparameters:\n  devname: \"test-device\"\nprovisioner: device.csi.openebs.io\nvolumeBindingMode: WaitForFirstConsumer\n```\n\nCheck the doc on [storageclasses](docs/storageclasses.md) to know all the supported parameters for Device LocalPV\n\n##### Device Availability\n\nIf the device with [meta partition](#metapartition) is available on certain nodes only, then make use of topology to tell the list of \nnodes where we have the devices available. As shown in the below storage class, we can use allowedTopologies to \ndescribe device availability on nodes.\n\n```\napiVersion: storage.k8s.io/v1\nkind: StorageClass\nmetadata:\n  name: openebs-device-sc\nallowVolumeExpansion: true\nparameters:\n  devname: \"test-device\"\nprovisioner: device.csi.openebs.io\nallowedTopologies:\n- matchLabelExpressions:\n  - key: kubernetes.io/hostname\n    values:\n      - device-node1\n      - device-node2\n```\n\nThe above storage class tells that device with meta partition \"test-device\" is available on nodes device-node1 and \ndevice-node2 only. The Device CSI driver will create volumes on those nodes only.\n\n##### Scheduler\n\nThe OpenEBS Device driver has its own scheduler which will try to distribute the PV across the nodes so that one node \nshould not be loaded with all the volumes. Currently, the driver supports two scheduling algorithms: VolumeWeighted and \nCapacityWeighted, in which it will try to find a device which has lesser number of volumes provisioned in it or \nless capacity of volume provisioned out of a device respectively, from all the nodes where the devices are available. \nTo know about how to select scheduler via storage-class See [this](https://github.com/openebs/device-localpv/blob/master/docs/storageclasses.md#storageclass-with-k8s-scheduler).\nOnce it is able to find the node, it will create a PV for that node and also create a DeviceVolume custom resource for \nthe volume with the node information. The watcher for this DeviceVolume CR will get all the information for this object \nand creates a partition with the given size on the mentioned node.\n\nThe scheduling algorithm currently only accounts for either the number of volumes or total capacity occupied from a \ndevice and does not account for other factors like available cpu or memory while making scheduling decisions. So if you \nwant to use node selector/affinity rules on the application pod, or have cpu/memory constraints, kubernetes scheduler \nshould be used. To make use of kubernetes scheduler, you can set the `volumeBindingMode` as `WaitForFirstConsumer` in \nthe storage class. This will cause a delayed binding, i.e kubernetes scheduler will schedule the application pod first, \nand then it will ask the Device driver to create the PV. The driver will then create the PV on the node where the pod \nis scheduled.\n\n```\napiVersion: storage.k8s.io/v1\nkind: StorageClass\nmetadata:\n  name: openebs-device-sc\nallowVolumeExpansion: true\nparameters:\n  devname: \"test-device\"\nprovisioner: device.csi.openebs.io\nvolumeBindingMode: WaitForFirstConsumer\n```\n\nPlease note that once a PV is created for a node, application using that PV will always get scheduled to that particular\nnode only, as PV will be sticky to that node. The scheduling algorithm by Device driver or kubernetes will come into \npicture only during the deployment time. Once the PV is created, the application can not move anywhere as the data is \nthere on the node where the PV is.\n\n#### 2. Create the PVC\n\n```\n$ cat pvc.yaml\n\nkind: PersistentVolumeClaim\napiVersion: v1\nmetadata:\n  name: csi-devicepv\nspec:\n  storageClassName: openebs-device-sc\n  accessModes:\n    - ReadWriteOnce\n  resources:\n    requests:\n      storage: 4Gi\n```\n\nCreate a PVC using the storage class created for the Device driver.\n\n#### 3. Deploy the application\n\nCreate the deployment yaml using the pvc backed by Device driver storage.\n\n```\n$ cat fio.yaml\n\napiVersion: v1\nkind: Pod\nmetadata:\n  name: fio\nspec:\n  restartPolicy: Never\n  containers:\n  - name: perfrunner\n    image: openebs/tests-fio\n    command: [\"/bin/bash\"]\n    args: [\"-c\", \"while true ;do sleep 50; done\"]\n    volumeMounts:\n       - mountPath: /datadir\n         name: fio-vol\n    tty: true\n  volumes:\n  - name: fio-vol\n    persistentVolumeClaim:\n      claimName: csi-devicepv\n```\n\nAfter the deployment of the application, we can go to the node and see that the partition is created and is being used as a volume\nby the application for reading/writting the data.\n\n#### 4. Deprovisioning\n\nfor 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 the partition will be wiped and deleted from the device.\n\n```\n$ kubectl delete -f fio.yaml\npod \"fio\" deleted\n$ kubectl delete -f pvc.yaml\npersistentvolumeclaim \"csi-devicepv\" deleted\n```\n\nFeatures\n---\n\n- [x] Access Modes\n   - [x] ReadWriteOnce\n   - ~~ReadOnlyMany~~\n   - ~~ReadWriteMany~~\n- [x] Volume modes\n   - [x] `Filesystem` mode\n   - [x] `Block` mode\n- [x] Supports fsTypes: `ext4`, `xfs`\n- [x] Volume metrics\n- [x] Topology\n- [ ] ~~Snapshot~~\n- [ ] ~~Clone~~\n- [ ] Volume Resize\n- [ ] ~~Thin Provision~~\n- [ ] Backup/Restore\n- [ ] Ephemeral inline volume\n\nThe FAQ guide can be found [here](https://github.com/openebs/device-localpv/blob/develop/docs/faq.md) \n\nProject Roadmap\n---\n\nThe project roadmap is defined and tracked using github projects [here](https://github.com/orgs/openebs/projects/37)\n\n\n## License\n[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fopenebs%2Fdevice-localpv.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Fopenebs%2Fdevice-localpv?ref=badge_large)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenebs-archive%2Fdevice-localpv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenebs-archive%2Fdevice-localpv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenebs-archive%2Fdevice-localpv/lists"}