DLDanpLab
DanpLab · Lab NoteArchitettura operativa

ZFS RAIDZ expansion in Proxmox VE 9: practical checklist for homelab

Operational checklist to evaluate and use ZFS RAIDZ expansion in Proxmox VE 9 without turning the lab storage into a blind experiment.

6 min readBased on real operational use
ProxmoxZFSHomelabStorageBackup

Proxmox VE 9 brings a new feature that greatly interests those managing homelabs and small infrastructures: ZFS 2.3 with support for RAIDZ expansion. In practice, it becomes possible to add a disk to an existing RAIDZ vdev, increasing the pool's capacity without destroying and recreating everything. It's a feature awaited for years, especially by those who started with three or four disks and then found themselves with more VMs, more backups, and more data than expected.

The important part is not to read it as magic. RAIDZ expansion reduces operational pain, but does not eliminate planning, backups, and maintenance windows. If the pool contains production VMs, critical home services, or data you cannot lose, it must be treated as a structural modification of the storage, not as a normal apt upgrade.

What really changes

With traditional RAIDZ layouts, expanding a pool almost always meant adding a complete new vdev, for example another RAIDZ1/RAIDZ2 group, or migrating data elsewhere, recreating the pool, and restoring. In the homelab world, this was inconvenient: not everyone has enough space, SATA ports, HBAs, and disks to double a pool just to grow neatly.

The RAIDZ expansion introduced in OpenZFS 2.3 allows adding a disk to an already existing RAIDZ vdev. A 4-disk RAIDZ1 can become, after resilvering, a 5-disk RAIDZ1. A RAIDZ2 can grow the same way while maintaining the chosen parity level. Proxmox VE 9 includes this generation of ZFS, so the feature becomes interesting even for real installations on Debian 13/Trixie.

Note, however: the operation does not automatically convert the old written space into a "perfect" distribution as if the pool was born with more disks. New data benefits from the new geometry, while to obtain a more homogeneous distribution it may be necessary to progressively rewrite the datasets, for example with migrations, send/receive, or planned restores. This is normal: the main goal is to expand without recreating everything, not to instantly rewrite the entire pool.

When it makes sense to use it

I gladly use it in three scenarios. First: homelab with a single ZFS pool for VMs, containers, and non-critical but still important data. Second: small office server where adding a complete new vdev would be too expensive. Third: Proxmox node with local storage, already solid backups, and a need to increase capacity without a long downtime.

I would avoid it instead if the pool is already degraded, if you have SMART errors, if you don't have a verified backup, or if you are trying to fix a bad design. If you started with RAIDZ1 on large disks and important data, adding a disk does not solve the risk of a second failure during resilver. In that case, it makes more sense to plan a migration to RAIDZ2, multiple mirrors, or separate storage for the most delicate workloads.

Checklist before touching the pool

Before any command, do these checks:

  1. Update the node documentation: disks, serials, physical bays, pool, and datasets.
  2. Verify you have a recent backup outside the pool, ideally on Proxmox Backup Server or external storage.
  3. Check the ZFS status with zpool status and ensure it is ONLINE without errors.
  4. Check SMART and temperatures of existing disks.
  5. Use persistent names in /dev/disk/by-id/, never /dev/sdX.
  6. Plan a window where reduced performance is not a problem.
  7. Avoid doing other heavy activities: scrubs, massive migrations, restores, or controller RAID rebuilds.

On Proxmox you can start from:

zpool status
zpool list
zfs list
ls -l /dev/disk/by-id/ | less
smartctl -a /dev/disk/by-id/ID_DEL_DISCO

If you use HBAs or controllers in IT mode, also check firmware and kernel logs. A RAIDZ expansion stresses the entire I/O path: disk, cables, backplane, power, and controller.

Operational example

Let's imagine a pool called tank with a raidz1-0 vdev and a new disk visible as /dev/disk/by-id/ata-WDC_NEW_DISK. First identify the correct vdev:

zpool status tank

Then, on systems with active RAIDZ expansion support, the addition happens with the zpool attach syntax, indicating the existing RAIDZ vdev and the new disk:

zpool attach tank raidz1-0 /dev/disk/by-id/ata-WDC_NEW_DISK

During the resilver, monitor without rushing:

watch -n 30 zpool status tank

When the operation finishes, check capacity and health:

zpool status tank
zpool list tank
zfs list -o name,used,avail,refer,mountpoint

Do not run the command by copying it blindly: always verify the syntax on the installed version and test first in a non-critical environment. In a serious homelab, a test VM with virtual disks is enough to understand the flow, timing, and status messages.

Impact on Proxmox

For Proxmox the practical question is: what happens to the VMs? If the pool stays online, VMs can continue to run, but expect higher latency during resilver. The most sensitive workloads, such as databases, Home Assistant with heavy recorder, Nextcloud, or storage for noisy containers, may be affected. If possible, shut down what is not needed and limit concurrent backups.

Also check snapshots and replications. Before the intervention, reduce the noise: avoid aggressive retention, overlapping backup jobs, and unnecessary live migrations. If you have Proxmox Backup Server, do a manual backup of important VMs and verify that at least one test restore has already been tried in the past. A backup never restored is a hope, not a procedure.

Mistakes to avoid

The first mistake is using mixed disks without criteria. ZFS accepts many combinations, but capacity, speed, and reliability matter. The second is ignoring power: adding disks increases inrush current and heat. The third is treating RAIDZ as a backup. RAIDZ protects against disk failures, not against deletions, ransomware, bugs, human errors, or fire.

The fourth mistake is expanding a pool that is already too full. ZFS works better with free space; consistently reaching above 80-85% makes everything more awkward. If you are already at the limit, consider moving cold datasets to another storage before the expansion.

Recommended DanpLab procedure

For a home or small office Proxmox node I would follow this sequence: full backup, verify zpool status, SMART test, add disk, monitored resilver, final scrub, and documentation update. After a few days, I would check latency and I/O graphs to see if the pool is holding up well or if it's time to separate VMs, backups, and cold data.

RAIDZ expansion is a very useful feature, but its best value is strategic: it allows growing with fewer interruptions. It must not become an excuse for not designing the storage. In homelabs, as in production, the rule remains simple: backups first, then capacity.

Sources

  • Proxmox, “Proxmox Virtual Environment 9.0 with Debian 13 released”.
  • Proxmox VE Roadmap and 9.x administrative documentation.
  • OpenZFS 2.3: RAIDZ expansion support and new ZFS features.