kvalliyurnatt / topolvm

Capacity-aware CSI plugin for Kubernetes

TopoLVM

TopoLVM is a CSI plugin using LVM for Kubernetes. It can be considered as a specific implementation of local persistent volumes using CSI and LVM.

• Conformed CSI version: 1.5.0

Our supported platform are:

• Kubernetes: 1.29, 1.28, 1.27
• Node OS: Linux with LVM2 (*1), specifically tested on Ubuntu
• CPU Architecture: x86 (*2), arm64 (*3), ppc64le (*3), s390x (*4)
• Filesystems: ext4, xfs, btrfs(experimental)
• lvm version 2.02.163 or later (adds JSON output support)

*1 The host's Linux Kernel must be v4.9 or later which supports rmapbt and reflink, if you use xfs filesystem with an official docker image.
*2 Tier1 support. The official docker images are provided and all functionalities are tested by CI.
*3 Tier2 support. The official docker images are provided, but no tests run by CI.
*4 Tier3 support. No docker images are provided, and no tests run by CI, but binaries are built.

Docker images are available on ghcr.io.

Getting Started

If you want to try TopoLVM on your local machine, see example directory which provides scripts to run TopoLVM on kind (Kubernetes IN Docker).

To use TopoLVM on your real kubernetes cluster, read documents.

Deprecated: If you want to use TopoLVM on Rancher/RKE, see docs/deprecated/rancher/README.md.

Contributing

TopoLVM project welcomes contributions from any member of our community. To get started contributing, please see our Contributing Guide.

Scope

In Scope

• Dynamic provisioning: Volumes are created dynamically when PersistentVolumeClaim objects are created.
• Raw block volume: Volumes are available as block devices inside containers.
• Topology: TopoLVM uses CSI topology feature to schedule Pod to Node where LVM volume exists.
• Extended scheduler: TopoLVM extends the general Pod scheduler to prioritize Nodes having larger storage capacity.
• Volume metrics: Usage stats are exported as Prometheus metrics from kubelet.
• Volume Expansion: Volumes can be expanded by editing PersistentVolumeClaim objects.
• Storage capacity tracking: You can enable Storage Capacity Tracking mode instead of using topolvm-scheduler.
• Snapshot: Snapshots can be taken when using thin provisioning.

Planned Features

• Prioritize based on volume capacity without using the extended scheduler.

Communications

If you have any questions or ideas, please use discussions.

Resources

docs directory contains the user manual, designs and specifications, and so on.

A diagram of components is available in docs/design.md.

TopoLVM maintainers presented the motivation and implementation of TopoLVM at KubeCon Europe 2020: https://kccnceu20.sched.com/event/ZerD

License

This project is licensed under Apache License 2.0.