openebs/lvm-localpv

Purpose and Runtime

OpenEBS Local PV LVM is a Go-based Kubernetes CSI plugin that provisions node-local Persistent Volumes backed by Linux LVM logical volumes. It is control-plane only: Kubernetes workloads consume host-local block devices or mounted filesystems; LVM2 performs the underlying volume operations. Primary binary entry point: cmd/main.go.

CSI Driver Boundary

The driver implements CSI identity, controller, and node-facing services, accepts gRPC CSI requests, and coordinates Kubernetes/LVM actions. Driver setup, service registration, controller behavior, and node agent behavior are centered in:

• pkg/driver/driver.go

• pkg/driver/grpc.go

• pkg/driver/controller.go

• pkg/driver/agent.go

The CSI controller initiates provisioning; node-side execution owns host-specific operations and volume publication.

Kubernetes Custom Resources and Reconciliation

The repository defines LVMVolume, LVMSnapshot, and LVMNode CRDs as the asynchronous contract between controller decisions and node-local execution:

• pkg/apis/openebs.io/lvm/v1alpha1/lvmvolume.go

• pkg/apis/openebs.io/lvm/v1alpha1/lvmsnapshot.go

• pkg/apis/openebs.io/lvm/v1alpha1/lvmnode.go

Generated clientsets, informers, and listers provide Kubernetes API access/watch machinery under pkg/generated/. CRD installation is delivered through deploy/helm/charts/charts/crds/templates/.

Volume Provisioning Flow

A PVC-driven CSI CreateVolume request is handled by the controller, which selects eligible topology/node capacity and creates an LVMVolume CR. The node volume manager watches that CR, creates/configures the LV locally, and updates status; CSI then returns/uses the resulting volume identity. Core stages:

• Controller and scheduling support: pkg/driver/controller.go, pkg/driver/schd_helper.go

• Volume reconciler/manager: pkg/mgmt/volume/start.go, pkg/mgmt/volume/volume.go

• Volume CR construction: pkg/builder/volbuilder/volume.go

Deletion and expansion follow the same controller-to-CR-to-node pattern. Responses for create, delete, resize, and snapshots are separated in pkg/response/.

Node LVM and Publish Operations

Node-local logic is the boundary to the host Linux environment: LVM command/utilities manage VGs/LVs, while mount and volume code expose filesystem or raw-block volumes to kubelet. This layer also supports thin provisioning, resize, and I/O limiting:

• pkg/lvm/volume.go

• pkg/lvm/mount.go

• pkg/lvm/lvm_util.go

• pkg/lvm/iolimiter_cgroup.go

The required external substrate is a Kubernetes node with local disks, Linux kernel LVM support, LVM2, and kubelet CSI integration. Volumes remain bound to the hosting node; the system provides no replication/dataplane.

Snapshot and Node Capacity Management

Snapshot requests create LVMSnapshot resources and are fulfilled locally by the snapshot manager. Node discovery/capacity reporting is managed through LVMNode resources. Collectors inspect local PV/VG/LV state for capacity and metrics:

• pkg/mgmt/snapshot/start.go

• pkg/mgmt/snapshot/snapshot.go

• pkg/mgmt/lvmnode/start.go

• pkg/collector/vg_collector.go

Deployment and Operations

Helm deploys the CSI controller and node DaemonSet, RBAC, CSI driver registration, monitoring resources, and CRDs:

• deploy/helm/charts/templates/lvm-controller.yaml

• deploy/helm/charts/templates/lvm-node.yaml

• deploy/helm/charts/templates/lvm-node-service.yaml

• deploy/helm/charts/values.yaml

CI builds and publishes container artifacts through GitHub Actions, notably .github/workflows/build_and_push.yml and .github/workflows/release.yml.