# zfs-localpv: ZFS-backed local volumes for Kubernetes

> OpenEBS Local PV ZFS is a CSI driver that turns a Kubernetes PersistentVolumeClaim into a ZFS dataset on the node that will run the workload. It is a control plane only, it is bound to a single node, and it does not replicate.

**openebs/zfs-localpv** — Dynamically provision Stateful Persistent Node-Local Volumes & Filesystems for Kubernetes that is integrated with a backend ZFS data storage stack.

- Repository: https://github.com/openebs/zfs-localpv
- Website: https://openebs.io
- Stars: 602 · Forks: 130
- Language: Go
- License: Apache-2.0
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/openebs-zfs-localpv

## A control plane over the kernel's own ZFS

The overview states the scope in plain words and the wording is deliberate. OpenEBS Local PV ZFS is a CSI plugin for ZFS backed persistent volumes for Kubernetes, and it is a local storage solution, which means the device, the volume and the application are on the same host. It does not contain any dataplane, in the README's phrasing, it is simply a control plane for the kernel ZFS volumes. That distinction is the whole design. There is no separate block device driver, no network file system and no storage server in the data path. The ZFS implementation already lives in the kernel, and what this project adds is the piece that lets Kubernetes ask for a dataset and get one. The reasons given for choosing it are three. It is a lightweight and easy to set up storage provisioner for host-local volumes in a Kubernetes cluster. It makes the ZFS stack available to Kubernetes, so end users can use ZFS features such as snapshot, restore, clone, thin provisioning, resize, encryption, compression and deduplication for their persistent volumes. And it is cloud native in the sense that it follows the CSI specification, so it is developed to run on Kubernetes rather than beside it.

## Two CSI components and a custom resource between them

The project comprises two components implemented in accordance with the CSI specifications, and the division is the standard one. The CSI Controller fronts the incoming requests and initiates the operation. The CSI Node Plugin serves the requests by performing the operations and making the volume available for the initiator. The flow between them is where the design is visible, and it uses a custom resource. When a PersistentVolumeClaim is created, the Local PV ZFS CSI Controller creates a ZFSVolume custom resource, which emits an event for the Local PV ZFS CSI Node Plugin to create the zvol or dataset. When workloads are scheduled, the node plugin makes that zvol or dataset available through a mount point on the host. So the controller does not talk to the node directly for each operation. It writes a custom resource, the event carries the request, and the node plugin reconciles it. That indirection is what makes the driver safe to run in a cluster where the controller and the nodes are separate workloads, and it is also the reason the design fits the CSI model, where the controller service is the only part that talks to the Kubernetes API for volume lifecycle.

## What local means: node bound, no replication, low latency

The architecture section defines LocalPV as storage that is directly attached to a specific node in the Kubernetes cluster, using locally available disks on that node, such as SSDs and HDDs. The use case the README names is workloads that require low-latency access to storage or where data locality is critical, with databases and caching systems given as examples. Then come the characteristics, and they are a compact statement of the trade-off. The volume is node-bound, tied to the node where the disk is physically located. There is no replication, so the data is not replicated across nodes and if the node fails the data may become inaccessible. And because the storage is local, it typically offers lower latency compared with network-attached storage. That third point is the reason to accept the second, and the whole design is a deliberate choice of latency and simplicity over availability. The alternative approach to the same problem is network-attached storage with its own replication, and the difference in approach is exactly this: with a local PV there is no copy of your data anywhere else, and the workload must be pinned to the node that holds the disk, which is a scheduling constraint your platform team has to plan for rather than a detail.

## The feature list, including the access modes it will not give you

The features checklist is worth reading closely because the crossed-out items are as informative as the ticked ones. Access modes support ReadWriteOnce, while ReadOnlyMany and ReadWriteMany are struck through, which is the expected consequence of node-bound storage and a direct consequence of the no-replication characteristic above. Both volume modes are supported, the Filesystem mode and the Block mode, and there is a separate document for raw block volumes. The supported file systems are ext4, btrfs, xfs and zfs, and the filesystem type can be chosen per volume. The ZFS level features are the reason to use this driver at all. Snapshots can be created and restored, with the restore documented as the path to create a clone from a snapshot, and a volume can be cloned from an existing volume. Volumes can be resized, volume metrics are exposed, and there is a backup and restore path. One item is not done, ephemeral inline volume, which is the usual gap for a driver that has to pre-provision a dataset on disk.

## Supported systems, and the memory advice for deduplication

The supported system table is short and gives you the constraints before you install anything. Kubernetes 1.23 and newer is required. The supported distributions are Alpine, Arch, CentOS, Debian, Fedora, NixOS, SUSE, RHEL and Ubuntu. The oldest supported kernel is 2.6.32, which is an unusually old floor and tells you the driver does not depend on modern kernel interfaces. The supported ZFS versions are 0.7, 0.8 and 2.2.3, and that list is the one to check against your nodes, because a ZFS version outside it is the most likely reason for a driver that will not create a dataset. Two memory notes follow from ZFS itself rather than from the driver. ECC memory is highly recommended, and 8GiB of RAM is recommended for the best performance with deduplication enabled, while the table notes it will work with 2GiB or less if deduplication is off. That is a useful practical detail, because deduplication is the feature that makes ZFS interesting for a local PV in the first place, and it is also the one that needs memory and RAM to do its work.

## The Go dependency set and how the images are built

The module is a Go project with a current toolchain and a dependency set that reflects the Kubernetes and CSI ecosystem. The module path is versioned, github.com/openebs/zfs-localpv/v2, and the go directive names go 1.26.2. The direct dependencies are the Container Storage Interface spec at v1.12.0, the Kubernetes CSI library utilities, the OpenEBS lib-csi helper at v0.11.0, cobra for the command line, gRPC and protobuf for the transport, and the Kubernetes client libraries at v0.35.4 along with controller-runtime and mount-utils. The test tooling is Ginkgo with Gomega, and testify is also in the list.

```bash
module github.com/openebs/zfs-localpv/v2

go 1.26.2
```

The build tooling in the repository is as modern as the dependencies. There is a Makefile plus a Makefile.buildx.mk, which points at container image builds rather than local binaries, and the image naming convention is documented inside the Makefile, where an image URI is a registry URL, an image organisation, an image repository and a tag, with the organisation defaulting to openebs. The repository also carries a ct.yaml for chart testing, a buildscripts directory, a ci directory, a tests directory, a design directory, and Nix files, which is an unusually complete setup for a storage driver. There is also a deprecated directory, which is a useful signal, because it means the project has moved things rather than accumulating them.

## CNCF sandbox status, a develop branch, and where the documentation lives

The governance is stated in the README and in the repository layout. OpenEBS is a CNCF Sandbox project, and this driver inherits that status, which is the entry level of the CNCF incubation track and a statement about the project's maturity rather than about its code. The licence is Apache-2.0, and the README carries a FOSSA licence compliance badge alongside the OpenSSF best practices badge and a Go report card, which is a reasonable set of signals for a component that runs with elevated privileges on every node. The repository keeps a GOVERNANCE.md, a MAINTAINERS.md, a RELEASE.md describing the release process, a CHANGELOG.md, SECURITY.md and SECURITY_CONTACTS.md, an Adopters.md, a code of conduct and a contributing guide, so the process side is well covered. The default branch is develop, and the release tags are frequent, with v2.11.0 on 2026-08-18, v2.11.1 on 2026-09-04 and v2.11.2 on 2026-10-06, and the last push on 2026-10-09. The user facing documentation is kept in the docs directory with a quickstart, a developer setup, and separate pages for snapshots, clones, resize, raw block volumes and backup and restore, plus a features document that the README tells you to check for the Kubernetes version you run.

## Conclusion

Adopt zfs-localpv if you run a Kubernetes cluster on nodes with local disks and you want the ZFS feature set, snapshots, clones, thin provisioning, compression, encryption and deduplication, available to your PersistentVolumeClaims without running a separate storage appliance. It does not fit a workload whose data must survive the loss of a node, because the volume is bound to the node and the README states plainly that data is not replicated, and it does not fit an application that needs ReadWriteMany, which the feature list marks as unsupported. Before you deploy it, check the ZFS version on your nodes against the supported list, which covers 0.7, 0.8 and 2.2.3, and read the features document for the Kubernetes version you run, since support is documented per version.

## FAQ

### What is OpenEBS Local PV ZFS?

It is a CSI plugin that implements ZFS backed persistent volumes for Kubernetes. It is a local storage solution, so the device, the volume and the application are on the same host, and the README is clear that it contains no dataplane and acts only as a control plane for the kernel ZFS volumes.

### How does the ZFS CSI driver create a volume?

When a PersistentVolumeClaim is created, the CSI Controller creates a ZFSVolume custom resource, which emits an event for the CSI Node Plugin to create the zvol or dataset. When workloads are scheduled, the node plugin makes that zvol or dataset available through a mount point on the host.

### Is data replicated by zfs-localpv?

No. The README lists the characteristics of local PV storage and states that there is no replication, so the data is not replicated across nodes and may become inaccessible if the node fails. The volume is node-bound and the trade is lower latency compared with network-attached storage.

### Which access modes and features does zfs-localpv support?

The feature list shows ReadWriteOnce as the supported access mode, with ReadOnlyMany and ReadWriteMany marked as unsupported, and both the Filesystem and Block volume modes supported. The ZFS level features include snapshot create and restore, clone, volume resize, volume metrics, raw block volume and backup and restore, while ephemeral inline volume is not implemented.

### What system requirements does zfs-localpv have?

Kubernetes 1.23 or newer, with Alpine, Arch, CentOS, Debian, Fedora, NixOS, SUSE, RHEL and Ubuntu listed as supported distributions, the oldest supported kernel being 2.6.32, and ZFS versions 0.7, 0.8 and 2.2.3 supported. ECC memory is highly recommended, and 8GiB of RAM is recommended for the best performance with deduplication enabled.

## Sources

- [License: Apache-2.0](https://github.com/openebs/zfs-localpv/blob/develop/LICENSE)
- [openebs/zfs-localpv on GitHub](https://github.com/openebs/zfs-localpv)
- [Project website](https://openebs.io)
- [README](https://github.com/openebs/zfs-localpv/blob/develop/README.md)
- [Releases](https://github.com/openebs/zfs-localpv/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/openebs-zfs-localpv