The module lifecycle stage: Experimental

The module has requirements for installation

v0.2.2

Release date: 2026-10-01

A volume expanded online after a restart of the node plugin is unstaged and deleted again, instead of staying mounted on its node for ever.

Highlights

Changes in this release:

  • After a restart of the csi-node pod, a volume expanded online is unstaged from its node when its Pod and PersistentVolumeClaim are deleted, for volumeMode: Filesystem and volumeMode: Block.

Fixes

This release fixes:

  • Online expansion after a restart of the node plugin: the node plugin keeps the staged volumes in memory, and after a restart of the csi-node pod an online expansion recovered the volume under the path where it is published into the Pod instead of its staging path. Unstaging the volume then failed for ever with remove staging path ...: directory not empty: the staging mount and the NBD mapping stayed on the node, the VolumeAttachment was kept and the PersistentVolume stayed Released. The expansion now recovers the volume under its staging path, and the unstage ignores a record made for another path.

Upgrade notes

Before upgrading, note the following:

  • A volume that got stuck this way with v0.2.1 or earlier is not released by the upgrade. On its node, unmount what is left in its staging path: for a filesystem volume the globalmount directory named in the kubelet event remove staging path, for a block volume .../volumeDevices/staging/<PV name>/device, which is then removed as well. The kubelet finishes the unstage at its next retry and the PersistentVolume is deleted.

Known issues

Known limitations of this release:

  • Virtual machine disks on nodes with Linux 6.6 or later (Ubuntu 24.04, RED OS 8.0 on our stand) lose their NBD connection within the first minute after the virtual machine starts (Double reply or Unexpected reply from the nbd driver in the kernel log); the guest is left without its disk and the virtual machine cannot be stopped until the device is unmapped on the node with ustor-nbd netlink-unmap /dev/nbdN. Nodes with Linux 6.1 (Debian 12, Astra 1.8) are not affected. The cause is being investigated.

v0.2.1

Release date: 2026-09-30

Raw block volumes are unstaged from their own device after a restart of the node plugin, and snapshots are created without naming the VolumeSnapshotClass.

Highlights

Changes in this release:

  • After a restart of the csi-node pod, unstaging a block volume (volumeMode: Block) no longer unmaps the volume of another pod on /dev/nbd0 and leaves its own mapped.
  • The module’s StorageClasses carry the storage.deckhouse.io/volumesnapshotclass: csi-mind-ustor annotation, so a VolumeSnapshot without volumeSnapshotClassName is created.

Fixes

This release fixes:

  • Block volumes after a restart of the node plugin: the node plugin keeps the device of a staged volume in memory, and after a restart of the csi-node pod it read the device of a block volume from the mount table, where the source of a block volume is udev. Unstaging the volume then unmapped /dev/nbd0, whichever volume was served there, and left its own image mapped, so its PersistentVolume could not be deleted (still used by client(s)). The device is now taken from the mount table entry of the device file and checked to serve the volume’s image before it is unmapped; if it does not, the device serving the image is looked up. Online expansion of a block volume after a restart uses the same lookup.
  • Snapshots: the module’s StorageClasses carry the storage.deckhouse.io/volumesnapshotclass: csi-mind-ustor annotation. Without it snapshot-controller refused every VolumeSnapshot of a volume of the module, storage-foundation did not fill in the class of a VolumeSnapshot that names none, and the flows of storage-foundation that read the class from the StorageClass failed. A value already set on the StorageClass is kept.

Upgrade notes

Before upgrading, note the following:

  • The annotation is added to the StorageClasses of existing MindUstorStorageClass resources in place; nothing has to be done by hand.
  • A block volume unstaged with v0.2.0 after a restart of the node plugin stays mapped on its node, and its PersistentVolume stays Released. Find such mappings with ustor-nbd ls on the node, compare them with the VolumeAttachments of the node, and unmap each one by its full device name: ustor-nbd netlink-unmap /dev/nbdN; the PersistentVolume is then deleted. A pod whose block volume lost its device (I/O errors on the device) has to be recreated.

v0.2.0

Release date: 2026-09-29

Volume snapshots, raw block volumes and live migration of virtual machines on uStor, with volume statistics, topology and a check of the uStor login added to the driver.

Highlights

Changes in this release:

  • Volume snapshots: the module creates the csi-mind-ustor VolumeSnapshotClass, and a PersistentVolumeClaim can be restored from a snapshot, also into a claim larger than the snapshot.
  • Raw block volumes (volumeMode: Block), and ReadWriteMany block volumes for the virtual machines of the virtualization module, which can now be live-migrated between nodes.
  • A MindUstorStorageConnection reports whether uStor accepts the login of its user in the new Authenticated condition, so that a locked user or an expired password shows up in the connection and its alert.

New features

This release adds:

  • Snapshots: with a module that provides the snapshot.storage.k8s.io API in the cluster (for example storage-foundation), the CSI controller runs the snapshotter and the module creates the csi-mind-ustor VolumeSnapshotClass. A restored volume is a full, independent copy of the snapshot; it can be larger than the snapshot, and its filesystem is grown to the requested size when it is mounted.
  • Raw block volumes: a PersistentVolumeClaim with volumeMode: Block and the ReadWriteOncePod access mode gets the uStor volume as a device, with online expansion and snapshots.
  • Block volumes on several nodes for virtual machines: the driver accepts ReadWriteMany for volumeMode: Block. The pvc-validation webhook admits such a claim only from the service accounts of the virtualization module, and refuses ReadWriteMany with volumeMode: Filesystem for everyone.
  • The module’s StorageClasses carry virtualdisk.virtualization.deckhouse.io/volume-mode: Block and virtualdisk.virtualization.deckhouse.io/access-mode: ReadWriteMany, so the virtualization module creates its VirtualDisks on them as ReadWriteMany block volumes; a value already set on the StorageClass is kept.
  • Volume statistics: the node plugin answers NodeGetVolumeStats, so kubelet exports kubelet_volume_stats_* for uStor volumes and the PersistentVolumeClaim fill alerts and dashboards cover them.
  • The Authenticated condition of MindUstorStorageConnection: the module logs in to the uStor management API with the connection’s credentials every hour and as soon as the credentials Secret changes. Its reason names the cause of a failure (UserLocked, PasswordExpired, TemporaryPassword, UserNotFound, LoginRejected, Unreachable), Ready turns False while the login fails, and the D8CsiMindUstorStorageConnectionNotInUse alert fires. The hourly login also keeps uStor from locking the user of a cluster that creates no volumes for a while.

Improvements

This release improves:

  • Pods using uStor volumes are only scheduled onto nodes that run the node plugin: the driver reports the topology.ustor-nbd.csi.mindsw.io/data-plane topology segment, new PersistentVolumes get the node affinity of it, and the module’s StorageClasses select it in allowedTopologies. WaitForFirstConsumer now does what the description of volumeBindingMode says.
  • The node plugin runs only on nodes where the uStor client is installed, which the module labels storage.deckhouse.io/csi-mind-ustor-client-ready=true; a node with an unsupported operating system no longer registers the driver.
  • The uStor client is installed with every library it needs from the module itself, without packages from the node’s repositories, so a node without a route to its distribution’s repositories gets the client too.
  • An error of a rejected uStor login carries the reason uStor gives, instead of “invalid credentials” for every cause, and a rejected login is not retried with the same credentials for 5 minutes, so a mistyped password in the Secret no longer locks the uStor user within seconds.
  • On Deckhouse 1.78 and later the module grants access to its resources through the capability/scope RBAC model, next to the manage/use roles of earlier versions.

Upgrade notes

Before upgrading, note the following:

  • The StorageClasses of existing MindUstorStorageClass resources are recreated once to add allowedTopologies; volumes already provisioned are not affected. PersistentVolumes created before the upgrade have no topology node affinity and keep working as before.
  • After the upgrade the node plugin leaves a node until bashible has applied the new NodeGroupConfiguration there and labeled the node (usually minutes). Volumes staged on the node keep working meanwhile; their unmount and expansion wait for the label.
  • Nothing has to be done by hand: the new StorageClass annotations, the VolumeSnapshotClass and the webhook are created by the module.

Known issues

Known limitations of this release:

  • Cloning a volume directly from another PersistentVolumeClaim is not supported; take a snapshot and restore it instead.
  • A block volume without ReadWriteMany is only served with ReadWriteOncePod, and ReadWriteMany is reserved for the virtual machine disks of the virtualization module.
  • The live migration of a virtual machine between nodes with different operating systems can fail in QEMU on the state of the virtio network device, with the disks already attached on the target node; a migration between nodes of the same operating system works.

Docs

Documentation changes:

  • The documentation is reorganized into an overview, a usage guide, the configuration, the custom resources and a FAQ. The usage guide describes the uStor user the CSI controller needs and its password policy, changing its password, snapshots and restore, raw block volumes and block volumes for virtual machines.

Dependencies

Dependency updates:

  • uStor CSI driver: delivery 2026-08-25 → delivery 2026-09-28
    • The vendor’s delivery adds snapshots and raw block volumes; the module applies its own fixes on top (volume statistics, topology, the login reason and back-off, restore into a larger volume, multi-node block volumes).

v0.1.0

Release date: 2026-09-25

First release of the module: persistent volumes on uStor 1.6 over NBD, driven by MindUstorStorageConnection and MindUstorStorageClass resources.

Highlights

Changes in this release:

  • A uStor cluster is described once, by a MindUstorStorageConnection: the management API, the Secret with the uStor user, the etcd addresses and the Secret with the client certificates. Its Ready condition says whether the module uses it and what is missing otherwise.
  • A MindUstorStorageClass states the connection, the pool, the filesystem, the reclaim policy and the binding mode, and the module creates the StorageClass for it. StorageClasses for this driver cannot be created or changed by hand — the module owns them.
  • The nodes are prepared by the module: the uStor client (ustor-client, ustor-nbd) is installed on Astra Linux 1.8, RED OS 8, Ubuntu 22.04 and 24.04 and Debian 12, and its configuration and certificates are kept in step with the connection.

New features

This release adds:

  • Volume lifecycle: provisioning, attach and detach, online expansion, and migration of a Pod between nodes. The volume survives a restart of the node plugin.
  • The module setting clusterID separates the images of several Kubernetes clusters served by one uStor installation.
  • Alerts D8CsiMindUstorStorageConnectionNotInUse and D8CsiMindUstorStorageClassNotReady fire when a connection or a StorageClass stays Failed for 15 minutes.

Known issues

Known limitations of this release:

  • The module serves one uStor cluster: every MindUstorStorageConnection but the oldest is reported as Failed.
  • Snapshots and raw block volumes are not offered.
  • On a node with an operating system outside the supported list the uStor client is not installed, and uStor volumes cannot be mounted there.