Replicated and erasure-coded persistent volumes with topology-aware placement, self-healing, and persistent brick-local storage. Built in Rust for performance and reliability.
Choose replicated or erasure-coded volumes. The policy is stored with the volume and exposed through the admin API, CLI, and operator-facing docs.
TopoHash algorithm spreads data across failure domains — datacenter, rack, and host — so a single rack failure never exceeds fault tolerance.
Automatic brick failure detection via heartbeats, shard rebuild planning, and volume recovery. Degraded volumes are restored without operator intervention.
Alert on degraded bricks and volumes, inspect placement dependencies, deterministic drain with migration tracking, plan and apply rebalancing after topology changes, and guard removals with impact checks.
CSI driver, Helm chart, CRDs for clusters, bricks, and volumes with active operator reconciliation, and node-local NVMe/TCP export reconciliation. Provision volumes declaratively or with StorageClasses.
Bricks keep a stable local identity and store shard data in a persistent device-backed log, so restarts preserve both on-disk data and brick UUIDs.
A layered system from Kubernetes workloads down to brick-local storage, with replicated or erasure-coded protection, topology-aware placement, and operator-visible recovery workflows.
Cluster brain — manages volumes, placement maps, health monitoring, and rebuild orchestration. Port 9200.
Chunk storage with heartbeat and auto-registration. Each brick manages local NVMe/SSD storage. Port 9100.
Kubernetes CSI integration for PV/PVC provisioning. Creates volumes via metadata, stages and publishes on nodes. Port 9300.
`hyperblock-nbd` provides the current compatibility bridge, while `hyperblock-nvmf` and the reference SPDK target-manager path materialize node-local NVMe/TCP exports for future native serving flows.
Watches HyperblockCluster, HyperblockBrick, and HyperblockVolume CRDs. Reconciles metadata StatefulSets, brick/CSI DaemonSets, brick registration, and volume provisioning.
Admin command-line interface for volume, brick, and cluster operations.
Hyperblock's topology-aware placement engine turns a volume ID, a stripe index, and a simple placement rule into a deterministic set of brick targets and a persisted placement map.
ClusterTopology is a real hierarchy: root -> datacenter -> rack -> host -> brick. Every placement decision starts from that tree.
PlacementRule is a list of level/count/mode steps such as "pick 6 distinct racks first, then fall back to any remaining unique bricks."
compute_pg_id() hashes volume_id || stripe_index with xxh3, producing the deterministic key that drives domain and brick ranking.
The metadata service stores an ordered set of brick targets in a PlacementMap, bumps the placement version, and copies that version onto the volume as placement_epoch.
rack levelTopoHash ranks all racks once, then ranks all leaf bricks inside each chosen rack. The first unique brick in each ranked domain wins that slot.
The first four picks satisfy rack spread. The last two come from the cluster-wide unique-brick fallback because only four racks exist but six targets are required.
split_io() converts a byte range into one or more ChunkId { volume_id, index } operations using the volume's logical chunk_size.
The metadata layer hashes volume_id plus the chunk or stripe index to get the placement-group key that TopoHash evaluates.
One logical chunk location stores multiple brick IDs.
ChunkLocation {
chunk_id: 3,
brick_ids: [b3, b6, b7]
}One stripe expands into many shard locations, each with one brick target.
stripe 3
shard0 -> b3
shard1 -> b6
shard2 -> b7
shard3 -> b2
parity0 -> b5
parity1 -> b8Bricks are inserted under datacenter, rack, and host nodes. The tree stores weights and the physical path to every brick.
compute_pg_id() creates a 64-bit placement key from volume_id and stripe_index. Same inputs always produce the same key.
For each rule step, TopoHash collects every node at the requested level and deterministically ranks them from the placement key.
Leaf bricks inside the chosen domain are ranked in deterministic order. The first brick not already used wins that slot.
If the rule cannot produce enough distinct domains, TopoHash ranks the entire brick set and fills the remaining slots with any unique bricks.
The metadata service writes a PlacementMap, increments the placement version, and clients consume that map for later reads, writes, drains, and rebalance plans.
PlacementMap, and splits a block I/O into one or more chunk operations.ChunkGroup, takes the first logical ChunkLocation, and fans the same chunk out to every brick in that location's brick_ids.write_quorum replicas acknowledge the chunk. Failed bricks are marked failed locally so later operations prefer healthier targets.ChunkGroup in the cached placement map.read_quorum = 1, the client tries replicas in order, skips locally failed bricks, and returns the first healthy response.read_quorum > 1, the client reads from all healthy replicas in parallel and requires at least read_quorum byte-identical responses.PlacementMap {
volume_id,
version,
groups: [
ChunkGroup {
stripe_index,
locations: [
ChunkLocation { chunk_id, brick_ids[...] }
]
}
]
}Application writes data to a volume via the CSI-mounted block device.
The client either fans the chunk out to replicas or encodes it into data and parity shards, depending on the stored protection policy.
TopoHash maps the chunk index to target bricks across failure domains.
All shards are written to their assigned brick servers in parallel via gRPC.
Client resolves which bricks hold the shards for the requested chunk.
Shards are fetched from brick servers in parallel, skipping any failed bricks.
Replicated volumes fail over to another healthy replica. Erasure-coded volumes reconstruct the stripe locally when enough shards survive.
Data shards are concatenated and truncated to the original length.
Bricks send heartbeats every 10s. The health monitor scans every 15s for stale bricks (30s timeout).
Missed heartbeat marks brick as Down. Affected stripes and volumes are identified.
Replacement bricks are selected from the healthy pool. The RebuildPlanner creates migration tasks.
Shards are rebuilt or migrated to new bricks, and operators can inspect placement movement through the CLI before removing infrastructure.
Reed-Solomon erasure coding provides durability without full replication. Choose a profile that matches your fault tolerance and storage efficiency requirements.
| Profile | Data Chunks | Parity Chunks | Total Shards | Fault Tolerance | Storage Overhead |
|---|---|---|---|---|---|
EC_4_2 | 4 | 2 | 6 | 2 brick failures | 1.5x |
EC_8_3 | 8 | 3 | 11 | 3 brick failures | 1.375x |
EC_8_4 | 8 | 4 | 12 | 4 brick failures | 1.5x |
Default chunk size: 128 MiB. Compare with 3x replication overhead for equivalent fault tolerance.
# Prerequisites: Rust 1.75+, protobuf-compiler
cargo build --workspace
cargo test --workspace # 180+ tests
cargo clippy --workspace --all-targets # Must be warning-free# Install CRDs
kubectl apply -f deploy/helm/hyperblock/crds/
# Install with Helm
helm install hyperblock deploy/helm/hyperblock \
--namespace hyperblock-system \
--create-namespace \
--set image.repository=myregistry/hyperblock \
--set image.tag=0.1.0# CLI examples
hyperblock-cli volume create --name analytics-ec --size 100GiB --data-chunks 4 --parity-chunks 2
hyperblock-cli volume create --name postgres-r3 --size 50GiB --replicas 3
# Or use a PVC through CSI
kubectl apply -f pvc.yaml