HwameiStor: local block storage with HA replicas for Kubernetes

A local disk pool exposed over CSI

HwameiStor is described as an HA local storage system for cloud-native stateful workloads. It creates a local storage resource pool for centrally managing all disks such as HDD, SSD and NVMe, uses the CSI architecture to provide distributed services with local volumes, and provides data persistence for stateful cloud-native workloads or components.

That last phrase, local access, is the design commitment. The performance argument for local storage is that a pod talking to a disk on its own node avoids a network hop and a network filesystem's semantics, which is why this exists alongside network block storage rather than instead of it. The cost is that the volume's data lives on one machine, and a machine can fail.

The HA part is what addresses that cost, and the readme is clear about the mechanism it uses. DRBD, Distributed Replicated Block Device, is one of the third-party HA modules which HwameiStor leverages to provide an HA volume. It is composed of Linux kernel modules and related scripts to build highly available clusters, and it works by mirroring the entire device over the network, which the readme describes as a kind of network RAID. The HA module installer can install DRBD directly into a container cluster.

So a volume can have a replica elsewhere, and the application can fail over to the node holding that replica. The readme's module list also names DRBD as one option rather than the only one, which implies the HA layer is pluggable.

The project is a Cloud Native Computing Foundation sandbox project, and the primary language is Go with the module github.com/hwameistor/hwameistor. The releases are v1.1.1 from 2026-07-22, v1.1.0 from 2026-07-06 and v1.0.2 from 2026-01-20, with the last push on 2026-10-20.

Twelve modules, and two of them do the hard work

The module list in the readme is the clearest picture of what the system actually does, and it is longer than the headline suggests.

Two modules are the core. local-disk-manager, LDM, holds the management of disks on nodes, and other modules such as local-storage can take advantage of the disk management feature it provides. local-storage, LS, provides the cloud-native local storage system, aiming to provision high-performance persistent LVM volume with local access to applications. So the disk inventory and the volume provisioning are separate components, and the second depends on the first.

The rest are the parts that make a storage system usable in a cluster rather than merely present.

The Scheduler automatically schedules a pod to a correct node which has the associated HwameiStor volumes. That is the piece that makes local volumes work at all, because the default scheduler knows nothing about where a volume's data lives. The admission-controller is a webhook that determines which pod uses the HwameiStor volume and helps modify the schedulerName to hwameistor-scheduler, so the two work together: the webhook notices a pod with such a volume and points it at the right scheduler.

The Evictor is the failure path. It automatically migrates HwameiStor volumes when a node or pod is evicted. When a node or pod is evicted as either Planned or Unplanned, the associated volumes which have a replica on the node are detected and migrated out of that node automatically.

Then the operational modules. Exporter collects system metrics including nodes, storage pools, volumes and disks, and supports Prometheus. The UI provides a friendly interface to operate the cluster. Audit provides the resource history for cluster, node, storage pool, volume and more.

The Makefile's compile target lists the same set of binaries, one per module, and the image and release targets repeat the list for each, which is the shape of a system where each piece ships as its own container.

Volume features, and the one gap the readme names

The volume level features are listed separately from the modules, and they are the part a platform team would actually evaluate.

Volume Snapshot provides snapshot and restore on the LVM volumes, with the limitation stated in the same breath: currently, the snapshot and restore feature works for LVM non-HA volume. That is a real constraint rather than a footnote, because the whole point of the HA layer is the replicated volume, and the snapshot feature does not cover the case most interesting users will have.

Volume Auto Resize expands the LVM volume according to a pre-defined resize policy. The user defines the preferred policy and describes how and when to expand the volume, and HwameiStor takes the policy into effect. This is the kind of feature that a storage system either has or that every team writes themselves, and having it driven by a policy object rather than by a sidecar is the difference between a shared platform and a script per application.

Volume IO Throttling sets a maximum rate, such as bandwidth or IOPS, to access a volume. The readme explains why this matters in a way that generalises beyond this project: the feature is very important to prevent the Pod from crashing, especially in the low-resource condition. A pod that writes faster than its disk can serve will be throttled or OOM killed, and with a local disk the contention is often between the pod and a neighbour on the same node, which makes per-volume limits the only fair mechanism.

App Failover is the last one, and it is the counterpart to the Evictor. Rather than migrating data after a failure, it actively helps the application fail over to another healthy node with the volume replica and continue working. The Evictor moves the data, the App Failover moves the application.

The Kubernetes version table, read carefully

The compatibility table in the readme is the sort of thing most projects hide, and it deserves to be read line by line before you plan an upgrade.

The columns are HwameiStor versions v0.4.3, greater than or equal to v0.5.0, and greater than or equal to 0.13.0. The rows are Kubernetes versions from 1.18 through 1.30.

For v0.4.3 the supported range is Kubernetes 1.18 to 1.24. For v0.5.0 and later, the range starts at 1.21 and runs through 1.26. For 0.13.0 and later, the range is 1.24 through 1.30.

So the trend is clear: newer HwameiStor drops old Kubernetes versions and supports newer ones. The oldest Kubernetes you can run with the current releases is 1.21, and the newest listed is 1.30. If your cluster is on 1.20 or older, the table says you need the old v0.4.3 line.

The go.mod explains why the table is not simply a policy. It requires go 1.21, the Kubernetes libraries at k8s.io/api v0.26.0, k8s.io/apimachinery v0.26.0, controller-runtime v0.9.2 and operator-sdk v0.18.2, and it pulls in k8s.io/kubernetes v1.24.0 as a dependency. A Go module that vendors the Kubernetes libraries at those versions will not build cleanly against a cluster several minor versions away, and the compatibility table is the visible consequence.

The CSI dependency is the container-storage-interface spec at v1.5.0, plus the CSI library utilities, and the volume snapshot support uses the external-snapshotter client, which is the standard Kubernetes way to expose snapshot objects. The API server is built with gin and served with swagger, so the project also exposes a documented HTTP surface for its own API.

The examples directory is where the configuration lives

The examples in the repository are the most concrete thing in it, and their names tell you what a real deployment looks like.

There are two StorageClass-shaped files, sc_ha.yaml and sc_local.yaml, which is the first choice every adopter makes: local storage without replication, or local storage with an HA replica. There is a clone example and a snapshot example. Then there are two workload manifests, sts-mysql_local.yaml and sts-mysql_ha.yaml, each a StatefulSet running MySQL against one of the two storage classes.

MySQL on a StatefulSet is the canonical test for this kind of system, because a database with a stable identity per replica is exactly the workload that benefits from a volume staying with its pod. Seeing those manifests in the repository is more informative than any feature description, since it shows the storage class name, the volume mode, the reclaim policy and the access modes actually used.

The other thing worth noting is what is not in the examples. There is no example of a workload that spans two HwameiStor volumes on different nodes, and no multi-cluster example. The scope of the demonstrated use cases is a single workload with a single local volume, replicated or not.

The docs site itself is built from a docs directory and previewed locally with two commands, one for English and one for the Chinese locale:

cd docs
npm run start  # for English
npm run start -- --locale cn # for i18n/cn

The repository layout supports a large, multi-binary project. There is a cmd directory, a pkg directory with the module implementations, a vendor directory, a helm directory for charts, a deploy directory, an examples directory, a test directory, a hack directory, a build directory, a third_party directory, an adopters.md listing deployments in production or user acceptance environments, a release-process.md, MAINTAINERS.md and a changelogs directory. The presence of a vendor directory in a Go project is itself a signal about the deployment audience, since vendoring exists to make air-gapped and reproducible builds possible.

Editorial conclusion

Adopt HwameiStor if you run Kubernetes with local NVMe or SSD you want to expose as PVCs, and you need the volume replica to stay on the same node as the pod, including the failover behaviour when a node goes away. Do not adopt it if your data must survive a cluster-wide failure without replication, or if you need a mature project with a long support history, since HwameiStor is a CNCF sandbox project and the sandbox stage is explicitly the incubation step. Before you commit, read the Kubernetes compatibility table against your cluster version, and check the examples directory to see the StorageClass and workload manifests for the configuration you intend to run.

Frequently asked questions

Official sources

1. hwameistor/hwameistor on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases