Guides:Enterprise Shared Storage for Proxmox VE Clusters

From OSNEXUS Online Documentation Site
Jump to navigation Jump to search

By Steve Umbehocker, CTO, OSNexus · Updated October 3, 2026

Shared storage for a Proxmox VE cluster is a block or file store that every node can reach, so virtual machines and containers can migrate between nodes and restart elsewhere when a node fails. QuantaStor provides that storage from a central appliance or HA cluster, and its open-source Proxmox VE storage plugin adds a native quantastor storage type that provisions one iSCSI volume per Proxmox disk, with snapshots, templates, clones, resize and migration driven from the standard Proxmox tools. This guide covers the shared storage options, how the plugin works, and a walkthrough from storage pool to first VM disk.

Why it matters

Proxmox VE runs well on local disks, but local disks tie each guest to one node. Live migration, HA restart and a single place to manage capacity all need storage every node can see. Teams moving off VMware hit the same issue in reverse: a vSAN cluster combined compute and storage in the same hosts, and the replacement hypervisor needs somewhere to put the data.

External shared storage separates those concerns. Compute nodes can be added, upgraded or reinstalled without touching the data, and capacity grows by adding drives to the storage tier rather than buying matching hypervisor hosts. The storage tier also brings its own data services: snapshots, replication to a second site, encryption and role-based administration.

How it works

Proxmox VE has several built-in ways to consume shared storage (see the Proxmox storage documentation). QuantaStor can serve the common ones:

Option What Proxmox sees QuantaStor side Best fit
QuantaStor storage plugin (iSCSI) A quantastor storage; one block device per disk Scale-up storage pool, one storage volume per disk VM and LXC disks with per-disk snapshots and clones
NFS A shared directory for disk images, ISOs and backups NFS share on a storage pool ISO libraries, backups, file-based disk images
Ceph RBD Proxmox's own RBD storage type Scale-out block storage on a Ceph cluster Scale-out deployments across many storage nodes

For the RBD option, Proxmox creates images directly with its own Ceph client. QuantaStor recognizes block devices that were created outside its own management by Proxmox, OpenStack or Kubernetes and cleans up their volume objects automatically, so the grid view stays consistent with the cluster. Ceph block storage needs its own Ceph pool, separate from any pool that holds a CephFS file system, and the web manager only offers compatible pools when you create block storage.

The rest of this guide focuses on the plugin, because it gives Proxmox the most direct control over each disk. It separates management traffic from storage traffic:

  • Control plane. Create, delete, snapshot, clone, resize and access-control operations are REST calls to the QuantaStor REST API over HTTPS on port 8153, authenticated with HTTP Basic credentials.
  • Data plane. Guest I/O runs over iSCSI on port 3260. The plugin drives the standard open-iscsi initiator with iscsiadm: it discovers the target, logs in and waits for the device before handing it to Proxmox.

Each storage volume is exported through its own iSCSI target at LUN 0, and the plugin addresses it by a stable /dev/disk/by-path/...-lun-0 path rather than a /dev/sdX name. QEMU attaches the raw block device for VM disks; for containers, Proxmox formats the same device with ext4 and mounts it as the root filesystem.

On first activation, the plugin registers each Proxmox node as a host using the initiator IQN from /etc/iscsi/initiatorname.iscsi. Before a node uses a volume, the plugin assigns that host to the volume's access control list, and it removes the assignment when the volume is released. A volume is visible only to the nodes actively using it.

Volume names follow the Proxmox convention, so mapping a disk to its volume needs no lookup table:

Type Name pattern Example
VM or container disk vm-<vmid>-disk-<N> vm-100-disk-0
Template base disk base-<vmid>-disk-<N> base-100-disk-0
Template snapshot template-base-<vmid>-disk-<N> template-base-100-disk-0
Snapshot <volume>_<snapshot> vm-100-disk-0_snap1

The plugin does not patch or replace Proxmox source files, so Proxmox package upgrades do not break it. It is distributed as a Debian package from the pve-quantastor-plugin repository.

Design and sizing

Plan the cluster around these requirements from the plugin reference:

Item Requirement
Proxmox VE 9.1.x and 9.2.x, which can be mixed in one cluster. 8.4.x and older do not load the plugin, so keep 8.x nodes out of the cluster.
Storage A storage pool to provision from, on a current QuantaStor release
Network Every Proxmox node reaches the appliance on TCP 8153 (REST API) and TCP 3260 (iSCSI)
QuantaStor configuration None beyond the pool: the plugin creates volumes, host entries and ACL assignments

For production clusters, put the pool in a high-availability failover group so a storage controller failure doesn't take every VM down with it. The plugin's configuration options cover HA pools and SSL; see the plugin reference for the exact settings. The grid below shows scale-up ZFS pools next to scale-out Ceph block, file and object pools on the same grid, with the HA group controls in the toolbar.

The Storage Pools grid: scale-up (ZFS) pools that can back the Proxmox plugin, scale-out block pools for Ceph RBD, and the Storage Pool HA Resource Group toolbar used to make a pool highly available

Keep the iSCSI data path on a dedicated storage network where possible. The REST API traffic is light, but guest I/O follows every disk.

Setting it up

1. Create a least-privilege API user

The admin account works, but credentials stored on the Proxmox cluster should carry only what the plugin needs. Create a role under Security → Role → Create, then a user with that role under Security → User → Add. The role needs view access to everything plus these write operations:

  • Storage Volume: create, delete, modify, resize, createSnapshot, deleteSnapshot, rollback, clone
  • Storage Volume ACL: add, remove
  • Host: add, addInitiator, modify, remove, assignVolume, unassignVolume
The Create Role dialog: filter the Object Type list, tick the rows the plugin needs, then use Apply Permission Scope to Selected to give them System scope

Or create both in one pass with the QuantaStor CLI: 

qs role-add --name=pve-plugin-role --desc="Role for the Proxmox VE storage plugin" \
  --permissions="*:view:system,\
StorageVolume:create:system,StorageVolume:delete:system,StorageVolume:modify:system,\
StorageVolume:resize:system,StorageVolume:createSnapshot:system,StorageVolume:deleteSnapshot:system,\
StorageVolume:rollback:system,StorageVolume:clone:system,\
StorageVolumeAcl:add:system,StorageVolumeAcl:remove:system,\
Host:add:system,Host:addInitiator:system,Host:modify:system,Host:remove:system,\
Host:assignVolume:system,Host:unassignVolume:system"

qs user-add --name=pve-plugin --password=<password> --role=pve-plugin-role

2. Check connectivity from each Proxmox node

Before installing anything, confirm every node can reach both ports on the appliance (192.0.2.10 here): 

nc -zv 192.0.2.10 8153
nc -zv 192.0.2.10 3260
cat /etc/iscsi/initiatorname.iscsi

3. Install the plugin and add the storage

Install the pve-storage-quantastor package from the releases page on every node in the cluster. The quantastor type then appears under Datacenter → Storage → Add in the Proxmox web interface, alongside the built-in types. Enter the appliance address, the storage pool and the API user created in step 1. The plugin reference lists every configuration option, including the HA pool and SSL settings.

Operating and testing

Once the storage is added, it works with the standard pvesm, qm and pct tooling. A quick check from any node: 

pvesm status
qm create 9001 --name test-vm --memory 2048 --scsi0 <storage-id>:8
iscsiadm -m session

The new disk appears in QuantaStor as a storage volume named vm-9001-disk-0, and the node that owns the VM appears as a host assigned to it. Migrate the VM to another node and the assignment moves with it: the volume is released from the old node and assigned to the new one.

Snapshots, templates, clones, resize and migration all run through the plugin; the Usage section of the plugin reference describes how each behaves. Each Proxmox disk is a regular storage volume, so the volume-level tools on the QuantaStor side also apply: snapshot schedules for point-in-time copies outside Proxmox, and remote replication to a second site for disaster recovery. For the replication design, see Asynchronous Remote Replication and Disaster Recovery Failover.

FAQ

Which Proxmox VE versions does the QuantaStor plugin support?

Proxmox VE 9.1.x and 9.2.x, and both can run in the same cluster. On 9.2 the plugin logs a cosmetic message about implementing an older storage API. Proxmox VE 8.4 and older do not load the plugin, so any storage operation routed to an 8.x node fails.

Does the plugin work for LXC containers as well as VMs?

Yes. Container root filesystems run on QuantaStor volumes: Proxmox formats the iSCSI block device with ext4 and mounts it as the container root, using the same provisioning and access control as VM disks.

Do I need to configure iSCSI targets or host entries on QuantaStor first?

No. Apart from the storage pool, the plugin creates everything itself: a volume and dedicated target per disk, a host entry per Proxmox node from its initiator IQN, and the ACL assignments that make a volume visible only to the node using it.

Can QuantaStor replace vSAN after moving from VMware to Proxmox?

It replaces vSAN's role as shared storage with an external tier. Proxmox nodes use QuantaStor over iSCSI through the plugin, over NFS, or over Ceph RBD for scale-out designs, and the storage tier adds HA pools, snapshots and remote replication of its own. Compute and storage then scale independently instead of in matched hypervisor hosts.

Should I use the plugin, NFS or Ceph RBD?

Use the plugin for VM and container disks when you want one volume per disk with storage-side snapshots, clones and per-node access control. Use NFS for ISO libraries, backups and file-based images. Choose Ceph RBD when the deployment needs to scale out across many storage nodes.

Part of the QuantaStor Guides series. For reference documentation, see the QuantaStor documentation.

Retrieved from "https://wiki.osnexus.com/index.php?title=Guides:Enterprise_Shared_Storage_for_Proxmox_VE_Clusters&oldid=28237"