Skip to main content
A pool name is an API. Services, replication jobs, and inventory all address storage through it, so it must only encode things that never change. The performance tier never changes. Everything else does.

​
The convention

Names come from the storage medium, used identically on every node that has that class of storage:

​
Why fast was retired

An earlier version of this convention used fast for any non-boot flash. That name was a relative claim, and it stopped being true. It named a SATA SSD on a node that later gained an NVMe device. So the pool called fast was the slower of the two, and the genuinely faster one was not named at all. A medium name cannot rot that way. nvme describes what the device is, not how it ranks against whatever else gets installed later. That is why medium names are allowed here while the anti-patterns below are not. The medium is a fact about the device, whereas node, RAID level, and drive count are facts about a particular arrangement of devices. A node only creates the pools it has hardware for. A proxmox-2-style node with an HDD array gets bulk. A node with spare enterprise spinning disks gets sas. A node with a spare SATA SSD gets ssd, and a node with a spare NVMe device gets nvme. Every ZFS-boot node already has rpool.

​
What a pool name must never encode

The test for a candidate name: does this fact survive a hardware change? Medium names survive all of those events. The name tells you what the device is; the dataset path below it tells you the purpose.

​
The payoff: identical paths everywhere

Because the pool name is the same on every node, a dataset’s full path is node-agnostic:
  • bulk/data means “the bulk media dataset” on whichever node currently holds it. Moving the service to another node changes zero mount configuration.
  • Replication targets line up by construction: bulk/data on the source replicates to bulk/replica/<source>/data on the destination, and a restored replica is byte-identical at the same path it had at home.
  • Inventory and IaC reference one path per dataset, not one per node × dataset.
Any node can stand in for another, because storage addressing was never node-specific to begin with.

​
What this connects to

ZFS backup & replication

The snapshot and replication layers that ride on these pools.

VMID & network tier model

The same encode-only-what-never-changes philosophy, applied to guest identity.

Homelab

The hardware behind the pools.