Unclear documentation about how to implement volume expansion

[plaffitt]

It looks like the documentation about volume extension is somehow unclear.

I'm using iSCSI to attach storage devices on my nodes.

spec.md#controllerexpandvolume says:

If the plugin has only VolumeExpansion.OFFLINE expansion capability and volume is currently published or available on a node then ControllerExpandVolume MUST be called ONLY after either:

• The plugin has controller PUBLISH_UNPUBLISH_VOLUME capability and ControllerUnpublishVolume has been invoked successfully.

I can then resize the device from my appliance, but if I unpublish the volume, then the device is not accessible and thus I cannot resize the filesystem on it.

A bit later, I can read in the examples below

On the node where the ElasticSearch workload is scheduled, the CO calls NodeExpandVolume after calling NodeStageVolume.

Calling NodeExpandVolume on volume results in expanding the underlying file system and added space becomes available to workload when it starts up.

So I think that I should attach the device with NodeStageVolume and then mount it with NodePublishVolume.

But then I got confuse since nothing seems to say that NodeStageVolume should be used that way, actually I cannot find anything about what NodeStageVolume is all about. This guy here says that it's for devices supporting only 1 mount at a time, so you can mount it first, and then bind-mount the directory where it has been mounted. I can see when testing that this seems right since NodeStageVolumeRequest.GetStagingTargetPath() returns something like /var/lib/kubelet/plugins/kubernetes.io/csi/pv/pvc-xxxxx/globalmount. OK, so this staging target path is called globalmount, it should be for mount only, right? But then I can read this, saying that I can put everything, even matadata in this directory. And actually it could be nice because I cannot figure out another way to tell NodePublishVolume what device it should mount.

So yeah, I'm pretty confused now. Maybe I'm even more confused about what is NodeStageVolume? How to implement it? What it means to "stage" a volume over "publishing" it? Do I really have to implement this? If no, what are the use-cases?

Coming back to the first subject: How to implement offline volume expansion and where can I find more documentation about it?

And finally: Can I implement both online and offline volume expansion?