DirectPV: a CSI driver that turns local disks into Kubernetes persistent volumes

What it is, and what it deliberately is not

DirectPV is a CSI driver for Direct Attached Storage. The readme then makes the important clarification in the same sentence: in a simpler sense, it is a distributed persistent volume manager, and not a storage system like SAN or NAS. It is useful to discover, format, mount, schedule and monitor drives across servers.

That distinction is the whole design. A SAN or NAS driver gives you a network volume that the client reaches over the wire. DirectPV gives you the local disk, mounted, and tells Kubernetes that a pod owns it. The data never leaves the server.

The reason that matters is stated in the next paragraph, and it is the most persuasive argument in the readme. Distributed data stores such as object storage, databases and message queues are designed for direct attached storage, and they handle high availability and data durability by themselves. Running them on traditional SAN or NAS based CSI drivers, the Network PV model, adds yet another layer of replication or erasure coding and extra network hops in the data path. This additional layer of disaggregation results in increased complexity and poor performance.

So the argument is not that network storage is bad, it is that for a data store that already replicates itself, a network block device on top duplicates the work and adds latency. DirectPV removes the duplication.

The audience is therefore specific: teams running MinIO, a database or a queue on Kubernetes where the data is large enough that the network hop matters, and where the drives are local and plentiful rather than a shared SAN.

The quickstart, which is five commands and one manifest

The quickstart in the readme is short enough to reproduce, and the order matters because each step depends on the previous one.

First the plugin, so that kubectl has a directpv subcommand at all:

$ kubectl krew install directpv

Then the driver itself in the cluster:

$ kubectl directpv install

And then you check what happened:

$ kubectl directpv info

After that comes the part that is specific to direct attached storage. You probe the drives and write the results to a file, then initialise the ones you selected:

# Probe and save drive information to drives.yaml file.
$ kubectl directpv discover

# Initialize selected drives.
$ kubectl directpv init drives.yaml

The two-step discover then init is deliberate and worth understanding. Discover does not touch your disks, it inspects them and produces a list, and you then select from that list. Initialising a drive is destructive, and requiring an explicit selection step means the tool never decides on your behalf which drives to format.

Finally there is a demo to look at:

$ curl -sfL https://github.com/minio/directpv/raw/master/functests/minio.yaml | kubectl apply -f -

That manifest is a MinIO server, and it is the only way to see the driver do something interesting without writing your own workload. The functests directory in the repository holds it.

For everything beyond this, the readme points at the detailed documentation in the docs directory.

A CSI driver on top of the container storage interface spec

The technical foundation is the Container Storage Interface, and the go.mod pins the spec library at container-storage-interface/spec v1.12.0, with csi-lib-utils at v0.23.2 for the common side of the driver protocol.

The Kubernetes libraries sit at 0.35.3 across api, apiextensions-apiserver, apimachinery, client-go, kube-openapi and pod-security-admission, with controller-runtime absent from the direct list, which tells you the driver follows the CSI model rather than the operator model. It registers as a CSI plugin and answers the standard calls, and the Kubernetes side treats it like any other block storage provisioner.

A few dependencies explain what the driver actually does on a node. freddierice/go-losetup is the losetup wrapper, which is how a drive is attached. go-humanize is there for readable sizes in the output, and sha256-simd from MinIO is for checksumming. prometheus/client_golang and client_model are the metrics side, and pod-security-admission is interesting because it means the driver is aware of the pod security standards that its own pods have to satisfy.

The command line tooling is bubbletea, bubbles and lipgloss from Charm, which is the terminal UI toolkit. So there is a real TUI in the kubectl plugin, with cobra underneath and viper for configuration. The TUI is worth knowing about, because the directpv command family is where you actually watch drives being discovered and scheduled.

The rest of the tree has the pieces a driver of this kind needs: a Dockerfile, a seccomp.json and an apparmor.profile for the privileged bits, a sidecars directory, resources, and the build and release scripts. The seccomp and apparmor artefacts are the interesting ones, because a driver that formats and mounts host disks is exactly the kind of component that needs a confinement profile.

The Dockerfile explains the packaging choices

The image build is short, and every line in it is a decision about where the driver runs.

The base is registry.access.redhat.com/ubi8/ubi-minimal at 8.10, a Red Hat UBI minimal image, with WORKDIR set to / and the directpv binary plus the CREDITS and LICENSE files copied into a licenses directory. Then microdnf update runs with --nodocs, which is the usual way of keeping a minimal image small.

The most interesting part is the AlmaLinux repository dance. The build downloads the AlmaLinux 8 BaseOS RPM GPG key, installs dnf, moves a bundled AlmaLinux.repo into place, installs xfsprogs, cleans everything, and then removes a long list of dnf and rpm packages, including python3-dnf, python3-pip and rpm-build-libs, before cleaning again and deleting the repo file.

The reason is visible in the go.mod. freddierice/go-losetup is the tool for creating device mappings, and creating a device mapper device needs the device mapper kernel tooling, which is why the image has to install the distribution package manager at build time and then strip it out at runtime. The end result is an image that can create and destroy mapped devices without carrying a package manager in the final layer, and that is why the runtime base is a minimal UBI rather than a full distribution.

The entrypoint is simply the driver binary at /directpv, and there is no shell in the runtime story. The image is also built as a single architecture, since the AlmaLinux repository path it fetches is x86_64 specific, which is a constraint on the multi architecture support a storage driver would normally want.

The project is under maintenance, and the version table is unambiguous

The first thing in the readme is a notice, and it is not a soft one.

This project is currently under maintenance and is not accepting new changes.

The recommendation that follows is to use the latest version of DirectPV from the MinIO registry rather than from this repository, and the plugin from the download page, with links to the quay.io MinIO directpv repository and to a download page under dl.min.io. The upstream project is MinIO itself, and the maintainers are the MinIO authors, reachable on the MinIO Slack channel.

The version support list is where the operational reality shows. Versions v1.x, v2.x and v3.x of DirectCSI and DirectPV are marked end-of-life and unsupported. DirectPV version v4.0.x entered into maintenance mode on Jan 01, 2025. DirectPV version v4.1.x entered into maintenance mode on Jan 01, 2026.

So both current lines are in maintenance, one since the start of 2025 and one since the start of 2026, and the older lines are dead. The recent releases show the pattern, with v4.1.5 on 2025-04-28 and then v4.0.19 and v4.1.6 both published on 2026-03-25, which is a simultaneous patch across two maintained lines rather than a feature release.

The last push was on 2026-08-21. The repository is not archived, so the code is still there and still builds, but the readme's first line tells you not to expect changes.

The licence is AGPL-3.0, referenced to the LICENSE document in the repository.

Where DirectPV is the wrong tool

There are clear cases where this is the wrong choice, and they follow from what the driver assumes about the workload.

The first is a workload that wants a network filesystem. DirectPV is a block device provisioner over local media. If your application expects a shared filesystem that many pods mount concurrently, and the data is not replicated by the application itself, a local drive per node is the wrong primitive, and a network storage driver or a distributed filesystem is what you want.

The second is a cluster without spare local disks. The whole model depends on drives being present in the nodes, discovered, and claimed. A cloud provider instance with only network storage, or a cluster whose nodes are all ephemeral, has nothing for DirectPV to manage.

The third is a shared-nothing assumption you do not share. The readme's argument is that a distributed data store handles its own replication, and that is true for MinIO, for a quorum database and for a partitioned queue. It is not true for a single-instance database that you have been relying on a SAN to protect. If your application's durability story depends on the storage layer, DirectPV removes that layer.

The fourth is the maintenance status, which is the practical objection for a new adoption. A component in maintenance mode that is not accepting new changes, whose two live lines are both in maintenance, is fine if you have already evaluated it and it works for you. It is a poor foundation for a platform you are building from scratch.

And the fifth is the operational surface, which the quickstart hides. A driver that formats disks, creates device mappings, and mounts filesystems is privileged code running on every node, which is why the repository ships a seccomp profile and an apparmor profile. The README does not describe a recovery story for a node where a drive has been claimed and then fails, and for a storage system that is a question worth answering before you rely on it.

Against a network storage driver, and against managed cloud storage

Two comparisons make the trade concrete.

The first is against a conventional network block storage CSI driver, the Network PV model. The difference in approach is where the bytes travel. A network driver exposes a volume that the client fetches over the network, so every read is a network round trip, and for a distributed data store that already replicates, you are paying for the same durability twice. DirectPV exposes the local disk and lets the application own replication. The trade is that the data becomes node-local, so a pod that dies cannot be rescheduled onto a different node and keep its data, and your application's own replication and rebalancing has to cover that case.

The second is against a managed cloud block store such as a network volume from a cloud provider. That gets you elastic capacity, snapshots, and the ability to resize a volume, none of which DirectPV offers. What you give up is the per-volume cost and, more importantly, the network hop and the extra replication layer that the readme argues against. If your dataset fits comfortably in cloud block storage and the per-volume cost is not the problem, the managed option is simpler.

The honest summary is that DirectPV is a specialised answer to a specific problem: large local datasets for applications that replicate themselves, on Kubernetes nodes with spare disks, where the network hop is measurable. Outside that envelope it is more machinery than you need, and it is machinery in maintenance mode.

Editorial conclusion

Adopt DirectPV if you run stateful MinIO or another distributed data store on Kubernetes and want the data to stay on local disks without a network hop, and only if you are prepared to run a component that is explicitly in maintenance mode. Skip it if you need new features or upstream fixes, since the project states it is not accepting new changes, and prefer the MinIO registry and download page builds it points to. Verify first that your drives are XFS formatted as the project expects, that the Kubernetes version matches the CSI specification version the driver implements, and that the application you run actually wants block devices rather than a filesystem abstraction.

Frequently asked questions

Official sources

1. License: AGPL-3.0
2. minio/directpv on GitHub
3. Project website
4. README
5. Releases